How to Integrate Bandwidth with V0

Log in to the Bandwidth Dashboard at dashboard.bandwidth.com. You need three values for API authentication: your Account ID (visible in the top-right of the dashboard or in Settings → Account), an API Token, and an API Secret. To generate an API Token and Secret, navigate to Account → Users → API Credentials or Settings → API Credentials. Click Add Credentials, give them a name like 'V0 Integration', and generate the token/secret pair. Store both values immediately — the secret is only shown once. Also note your Account ID, which is a numeric identifier. Bandwidth's messaging API uses a different endpoint path than voice — for SMS and MMS, you'll use the Bandwidth Messaging API v2 at https://messaging.bandwidth.com/api/v2/users/{accountId}/messages. For voice, the API is at https://voice.bandwidth.com/api/v2/accounts/{accountId}/calls. Both APIs use HTTP Basic Auth with your API Token as the username and API Secret as the password. You'll also need the Application ID associated with your Bandwidth phone number — find this in the Bandwidth Dashboard under Numbers → My Numbers, then click on your number to see its associated application. The Application ID links incoming messages and calls to your webhook URLs.

Open V0 at v0.dev and describe the SMS or voice interface you want to build. For a messaging dashboard, describe the conversation list layout, the compose form, and the message thread view in detail. Ask V0 to use realistic mock data that matches Bandwidth's response structure: message objects with id, to, from, text, direction (inbound/outbound), status (queued/sent/delivered/failed), and createdTime. For a two-way inbox, the conversation thread view should clearly differentiate inbound messages (customer-sent) from outbound messages (your replies). For voice interfaces, describe a call log table with columns for from, to, duration, direction, and status. V0's Design Mode helps you polish the UI after initial generation — adjust the message bubble styling, timestamp formatting, and status badge colors. Once the layout looks right, identify which API endpoints each component needs: the message list needs GET /api/bandwidth/messages, the send form needs POST /api/bandwidth/messages, and the conversation view needs per-contact message filtering.

Build the Next.js API routes that interact with Bandwidth's messaging API. Create a utility at lib/bandwidth.ts that provides an authenticated fetch wrapper — Bandwidth uses HTTP Basic Auth where your API Token is the username and API Secret is the password. The base URL for the messaging API v2 is https://messaging.bandwidth.com/api/v2/users/{accountId}/messages. To send an SMS, make a POST request to this endpoint with a JSON body containing applicationId, to (array of phone numbers), from (your Bandwidth number), and text. The response includes a messageId and status. For fetching sent messages and their delivery statuses, use GET on the same endpoint with optional query filters. For inbound messages, Bandwidth pushes events to your webhook URL — create a separate POST route at app/api/bandwidth/webhook/route.ts that receives and processes incoming message payloads. Bandwidth's webhook sends events for inbound messages (type: message-received), delivery receipts (type: message-delivered), and failures (type: message-failed). Your webhook handler should parse the event type, extract the relevant data, and store it in your database or forward it to your frontend via Server-Sent Events or WebSockets. For the webhook to work, you must deploy to a public URL and configure it in the Bandwidth Dashboard under your messaging application's settings.

1// lib/bandwidth.ts
2const BANDWIDTH_ACCOUNT_ID = process.env.BANDWIDTH_ACCOUNT_ID;
3const BASE_URL = `https://messaging.bandwidth.com/api/v2/users/${BANDWIDTH_ACCOUNT_ID}/messages`;
4
5function getAuthHeader(): string {
6  const credentials = Buffer.from(
7    `${process.env.BANDWIDTH_API_TOKEN}:${process.env.BANDWIDTH_API_SECRET}`
8  ).toString('base64');
9  return `Basic ${credentials}`;
10}
11
12export async function bandwidthFetch(url: string, options?: RequestInit) {
13  const res = await fetch(url, {
14    ...options,
15    headers: {
16      Authorization: getAuthHeader(),
17      'Content-Type': 'application/json',
18      Accept: 'application/json',
19      ...options?.headers,
20    },
21  });
22  if (!res.ok) {
23    const error = await res.text();
24    throw new Error(`Bandwidth API error ${res.status}: ${error}`);
25  }
26  return res.json();
27}
28
29// app/api/bandwidth/messages/route.ts
30import { NextRequest, NextResponse } from 'next/server';
31import { bandwidthFetch } from '@/lib/bandwidth';
32
33const BASE_URL = `https://messaging.bandwidth.com/api/v2/users/${process.env.BANDWIDTH_ACCOUNT_ID}/messages`;
34
35export async function GET() {
36  try {
37    const data = await bandwidthFetch(`${BASE_URL}?direction=outbound&limit=50`);
38    return NextResponse.json({ messages: data });
39  } catch (error) {
40    return NextResponse.json({ error: 'Failed to fetch messages' }, { status: 500 });
41  }
42}
43
44export async function POST(req: NextRequest) {
45  try {
46    const { to, message } = await req.json();
47    const result = await bandwidthFetch(BASE_URL, {
48      method: 'POST',
49      body: JSON.stringify({
50        applicationId: process.env.BANDWIDTH_APPLICATION_ID,
51        to: [to],
52        from: process.env.BANDWIDTH_FROM_NUMBER,
53        text: message,
54      }),
55    });
56    return NextResponse.json({ id: result.id, status: result.status }, { status: 201 });
57  } catch (error) {
58    return NextResponse.json({ error: 'Failed to send message' }, { status: 500 });
59  }
60}
61
62// app/api/bandwidth/webhook/route.ts
63import { NextRequest, NextResponse } from 'next/server';
64
65export async function POST(req: NextRequest) {
66  try {
67    const events = await req.json();
68    for (const event of Array.isArray(events) ? events : [events]) {
69      const { type, message, to, from } = event;
70      if (type === 'message-received') {
71        console.log(`Inbound SMS from ${from[0]}: ${message?.text}`);
72        // Store in database or trigger notification
73      } else if (type === 'message-delivered') {
74        console.log(`Message ${message?.id} delivered`);
75      } else if (type === 'message-failed') {
76        console.log(`Message ${message?.id} failed: ${message?.errorCode}`);
77      }
78    }
79    return NextResponse.json({ received: true });
80  } catch {
81    return NextResponse.json({ error: 'Webhook error' }, { status: 400 });
82  }
83}

Bandwidth's webhook system requires a publicly accessible HTTPS URL to push inbound messages and delivery receipts. This means you must deploy to Vercel before you can test the full two-way messaging flow — webhooks cannot point to localhost. After deploying your app to Vercel (your URL will be something like https://your-app.vercel.app), configure the webhook URL in the Bandwidth Dashboard. Navigate to Dashboard → Applications → your messaging application. Set the Callback URL to https://your-app.vercel.app/api/bandwidth/webhook. Bandwidth will POST event payloads to this URL for every inbound message and delivery status update on phone numbers associated with this application. Test the webhook by sending a text message to your Bandwidth phone number from a real mobile phone. You should see the event logged in your Vercel Function Logs (Dashboard → Your Project → Functions tab). Once working, update your webhook handler to store inbound messages in your database (Neon PostgreSQL or Supabase via Vercel Marketplace work well here) and potentially send a real-time update to your frontend. For a production SMS inbox, connect Bandwidth webhooks to a database layer so conversation history is persisted across sessions.

1# .env.local — never commit this file
2# Bandwidth credentials (all server-only, no NEXT_PUBLIC_ prefix)
3BANDWIDTH_ACCOUNT_ID=123456789
4BANDWIDTH_API_TOKEN=t-your-api-token
5BANDWIDTH_API_SECRET=your-api-secret-here
6BANDWIDTH_APPLICATION_ID=a-your-app-id
7BANDWIDTH_FROM_NUMBER=+15551234567

Update your V0-generated messaging components to fetch from and post to your Bandwidth API routes. The send form should POST to /api/bandwidth/messages with the to phone number and message text. After a successful response, add the new message to local state with a 'Sent' status and clear the form. For the messages table, fetch from GET /api/bandwidth/messages on component mount and every 30 seconds to show updated delivery statuses. For the two-way inbox, the inbound webhook events need to reach the frontend — either through periodic polling of a database endpoint or via Server-Sent Events. For polling, create GET /api/bandwidth/conversations?phone={number} that queries your database for messages from that phone number. Add the BANDWIDTH environment variables to Vercel Settings → Environment Variables: BANDWIDTH_ACCOUNT_ID, BANDWIDTH_API_TOKEN, BANDWIDTH_API_SECRET, BANDWIDTH_APPLICATION_ID, and BANDWIDTH_FROM_NUMBER. Push to GitHub, wait for deployment, then test by sending a real SMS from the compose form. Check Vercel Function Logs for any API errors. For enterprise-scale SMS workflows with high message volumes or regulatory compliance requirements, RapidDev can help architect a robust message queuing and delivery tracking system on top of Bandwidth.

1'use client';
2
3import { useState } from 'react';
4
5export default function SMSComposeForm() {
6  const [to, setTo] = useState('');
7  const [message, setMessage] = useState('');
8  const [sending, setSending] = useState(false);
9  const [status, setStatus] = useState<'idle' | 'success' | 'error'>('idle');
10
11  const isValidPhone = (phone: string) => /^\+[1-9]\d{10,14}$/.test(phone);
12  const segmentCount = Math.ceil(message.length / 160) || 1;
13
14  const handleSend = async () => {
15    if (!isValidPhone(to)) {
16      alert('Phone number must start with + and include country code (e.g. +15551234567)');
17      return;
18    }
19    setSending(true);
20    try {
21      const res = await fetch('/api/bandwidth/messages', {
22        method: 'POST',
23        headers: { 'Content-Type': 'application/json' },
24        body: JSON.stringify({ to, message }),
25      });
26      if (!res.ok) throw new Error('Send failed');
27      setStatus('success');
28      setTo('');
29      setMessage('');
30    } catch {
31      setStatus('error');
32    } finally {
33      setSending(false);
34      setTimeout(() => setStatus('idle'), 3000);
35    }
36  };
37
38  return (
39    <div className="space-y-4 p-4 border rounded-lg">
40      <input
41        type="tel" value={to} onChange={(e) => setTo(e.target.value)}
42        placeholder="+15551234567" className="w-full border rounded p-2"
43      />
44      <textarea
45        value={message} onChange={(e) => setMessage(e.target.value)}
46        placeholder="Your message..." rows={3} className="w-full border rounded p-2"
47      />
48      <div className="flex justify-between text-sm text-gray-500">
49        <span>{message.length} chars · {segmentCount} segment{segmentCount > 1 ? 's' : ''}</span>
50        {message.length > 155 && <span className="text-yellow-600">Long SMS will be split</span>}
51      </div>
52      <button
53        onClick={handleSend} disabled={sending || !to || !message}
54        className="px-4 py-2 bg-blue-600 text-white rounded disabled:opacity-50"
55      >
56        {sending ? 'Sending...' : 'Send SMS'}
57      </button>
58      {status === 'success' && <p className="text-green-600">Message sent successfully!</p>}
59      {status === 'error' && <p className="text-red-600">Failed to send. Check the console.</p>}
60    </div>
61  );
62}