How to Integrate Bolt.new with Bandwidth

Bandwidth uses three credentials for API authentication: your Account ID, an API token, and an API secret. All three are required for every API call. Log in to the Bandwidth Dashboard at dashboard.bandwidth.com. Your Account ID (also called a subaccount ID) is displayed in the top navigation bar and in the URL of your account pages — it is a 7-10 digit number. Navigate to API Credentials (in the left sidebar under Settings or Security) to find your API token and API secret. The API token is a long alphanumeric string and the API secret is its paired secret. If you have not generated API credentials before, click the option to create new credentials. Both the token and secret are shown once when created — save them immediately to your password manager because the secret cannot be retrieved later. Next, ensure you have a phone number provisioned in your account. Navigate to Numbers → My Numbers to see your available numbers. If you do not have one, you can purchase a number through the Bandwidth Dashboard or use a trial number if you are on a trial account. Note the phone number in E.164 format (+1XXXXXXXXXX) — this is your from number for outbound messages and calls. Also note the messaging application ID and voice application ID if you have configured applications in the Dashboard, as some SDK methods require the application ID rather than just the from number.

Add all Bandwidth credentials to your Bolt project's .env file. Bandwidth requires four environment variables: BANDWIDTH_ACCOUNT_ID (your numeric account ID), BANDWIDTH_API_TOKEN (the token), BANDWIDTH_API_SECRET (the secret), and BANDWIDTH_FROM_NUMBER (your provisioned E.164 phone number). Optionally add BANDWIDTH_MESSAGING_APP_ID if your messaging setup uses application IDs. These are all server-side credentials — none of them get the VITE_ or NEXT_PUBLIC_ prefix. Prompt Bolt to install the @bandwidth/sdk npm package, which is Bandwidth's official TypeScript/JavaScript SDK. The SDK provides typed classes for creating message requests, managing calls, and generating BXML. After installation, verify the package appears in package.json. The SDK uses Basic Authentication under the hood — it combines your API token and secret into a Base64-encoded Authorization header for each request. You provide the token and secret when constructing the SDK client and the authentication is handled automatically. The Bandwidth SDK supports both CommonJS and ES modules, so it works in both Vite and Next.js projects without additional configuration. Prompt Bolt to create a lib/bandwidth.ts utility that initializes and exports the SDK client, similar to how you would export a Supabase or Stripe client.

1// lib/bandwidth.ts
2import { Client, MessagesApi, VoiceApi } from '@bandwidth/sdk';
3
4const client = new Client({
5  basicAuthUserName: process.env.BANDWIDTH_API_TOKEN!,
6  basicAuthPassword: process.env.BANDWIDTH_API_SECRET!,
7});
8
9export const messagesApi = new MessagesApi(client);
10export const voiceApi = new VoiceApi(client);
11export const accountId = process.env.BANDWIDTH_ACCOUNT_ID!;
12export const fromNumber = process.env.BANDWIDTH_FROM_NUMBER!;

Bandwidth's Messaging V2 API supports SMS (text only) and MMS (text plus media attachments). The createMessage method on the MessagesApi client accepts a message request object with from (your Bandwidth number), to (array of recipient numbers in E.164 format), text (message body), applicationId (your Bandwidth messaging application ID), and optionally media (array of media URLs for MMS). The API is asynchronous: you get a response immediately with a message ID, but the actual delivery happens through Bandwidth's network and final delivery status is reported via a webhook callback to your configured status callback URL. For outbound-only notifications, the immediate response with the message ID is sufficient — you know the message was accepted into Bandwidth's delivery queue. For tracking delivery status, you need the status callback webhook configured in your Bandwidth Dashboard under your messaging application. During development in Bolt's WebContainer, the createMessage call goes from your API route to Bandwidth's servers via outbound HTTP — this works in the WebContainer and you will see real messages delivered to real phone numbers. The inbound message webhook and delivery status callbacks require your deployed URL and cannot be tested in the WebContainer preview. Test outbound messaging in the preview, then deploy to test the complete bidirectional flow.

1// app/api/send-sms/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { messagesApi, accountId, fromNumber } from '@/lib/bandwidth';
4import { MessageRequest } from '@bandwidth/sdk';
5
6export async function POST(request: NextRequest) {
7  const { to, message, mediaUrls } = await request.json();
8
9  if (!to || !message) {
10    return NextResponse.json({ error: 'Missing required fields: to, message' }, { status: 400 });
11  }
12
13  // Validate E.164 format
14  const e164Regex = /^\+1[2-9]\d{9}$/;
15  if (!e164Regex.test(to)) {
16    return NextResponse.json({ error: 'Phone number must be in E.164 format: +1XXXXXXXXXX' }, { status: 400 });
17  }
18
19  try {
20    const body: MessageRequest = {
21      from: fromNumber,
22      to: [to],
23      text: message,
24      applicationId: process.env.BANDWIDTH_MESSAGING_APP_ID!,
25      ...(mediaUrls && mediaUrls.length > 0 ? { media: mediaUrls } : {}),
26    };
27
28    const response = await messagesApi.createMessage(accountId, body);
29    const messageId = response.result.id;
30
31    return NextResponse.json({ messageId, status: 'queued' });
32  } catch (error: unknown) {
33    const errorMessage =
34      error instanceof Error ? error.message : 'Failed to send message';
35    return NextResponse.json({ error: errorMessage }, { status: 400 });
36  }
37}

When a customer sends an SMS to your Bandwidth number, Bandwidth POSTs an event to the inbound message callback URL configured in your messaging application. The payload includes the from number, to number, message body, message ID, and whether it contains media attachments. Configuring this callback URL requires a publicly accessible endpoint — it cannot be a WebContainer preview URL. The workflow is: deploy your Bolt app first, then go to your Bandwidth Dashboard → Applications → your messaging application → Message Callback, and enter your deployed webhook URL. In Bandwidth's callback format, the payload wraps the message data in a message object with type and message fields. The type field indicates the event type: message-received for inbound messages, message-delivered for delivery confirmations, and message-failed for delivery failures. Parse these in your webhook handler and route them to the appropriate logic. For inbound messages, store them in Supabase and notify your team (via a Slack message, email, or real-time Supabase channel). For a two-way SMS system, you need both this inbound webhook and the outbound /api/send-sms route from the previous step. The WebContainer limitation is relevant here: you cannot receive these inbound message callbacks during development. Build and test the inbound handler code in Bolt, deploy, register the webhook URL, then test by sending a text to your Bandwidth number.

1// app/api/bandwidth/inbound/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { createClient } from '@supabase/supabase-js';
4
5const supabase = createClient(
6  process.env.NEXT_PUBLIC_SUPABASE_URL!,
7  process.env.SUPABASE_SERVICE_ROLE_KEY!
8);
9
10interface BandwidthCallback {
11  type: string;
12  time: string;
13  message: {
14    id: string;
15    owner: string;
16    from: string;
17    to: string[];
18    text: string;
19    direction: string;
20  };
21}
22
23export async function POST(request: NextRequest) {
24  const payload: BandwidthCallback[] = await request.json();
25
26  for (const event of payload) {
27    if (event.type === 'message-received') {
28      const { id, from, to, text } = event.message;
29      await supabase.from('sms_messages').insert({
30        direction: 'inbound',
31        phone_number: from,
32        to_number: to[0],
33        body: text,
34        bandwidth_id: id,
35      });
36    } else if (event.type === 'message-delivered' || event.type === 'message-failed') {
37      const status = event.type === 'message-delivered' ? 'delivered' : 'failed';
38      await supabase
39        .from('sms_messages')
40        .update({ status })
41        .eq('bandwidth_id', event.message.id);
42    }
43  }
44
45  // Always return 200 to acknowledge receipt
46  return NextResponse.json({ received: true });
47}

Bandwidth's Voice API lets you initiate outbound calls programmatically and control the call using BXML (Bandwidth Extensible Markup Language). BXML is similar to Twilio's TwiML — XML documents that tell Bandwidth what to do during an active call: speak text, play audio files, gather digits from the keypad, or transfer to another number. The voice call flow works like this: your API route calls Bandwidth's Voice API to create an outbound call, specifying the to number, from number, and an answerUrl — a URL on your server that Bandwidth fetches when the call is answered. Bandwidth fetches the answerUrl via HTTP GET (or POST) and your server returns a BXML document. The BXML content controls the call: a SpeakSentence verb converts text to speech using Bandwidth's TTS engine, a PlayAudio verb streams an audio file, a Gather verb collects DTMF keypad input, and a Hangup verb ends the call. Creating a BXML endpoint in your Bolt app means building a route that returns XML with the correct Content-Type header (application/xml). Like the messaging webhooks, the answerUrl must be publicly accessible — Bandwidth's servers call it when the phone is answered. This means voice call completion requires a deployed URL. You can initiate the call from the WebContainer (the createCall API call is outbound), but the call will fail when Bandwidth tries to fetch BXML from your answerUrl if it is not a public URL.

1// app/api/bandwidth/bxml/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4export async function GET(request: NextRequest) {
5  const { searchParams } = new URL(request.url);
6  const message = searchParams.get('message') || 'Hello, this is an automated message.';
7  const decodedMessage = Buffer.from(message, 'base64').toString('utf-8');
8
9  const bxml = `<?xml version="1.0" encoding="UTF-8"?>
10<Response>
11  <SpeakSentence voice="Susan" locale="en_US" gender="female">${decodedMessage}</SpeakSentence>
12  <Pause duration="1" />
13  <Hangup />
14</Response>`;
15
16  return new NextResponse(bxml, {
17    headers: { 'Content-Type': 'application/xml' },
18  });
19}