How to Integrate Bolt.new with Vonage (formerly Nexmo)

Sign up at dashboard.nexmo.com for a free trial account. Vonage provides €2 in free credits on signup, which is enough to send approximately 20-30 test SMS messages depending on destination country. The dashboard shows your API Key and API Secret on the home page — copy both immediately. For sending SMS, you need a virtual phone number as the 'from' sender in most countries. Navigate to Numbers → Buy Numbers in the dashboard, choose your target country (United States numbers start around €0.90/month), and complete the purchase. The number appears in Your Numbers and should be in E.164 format (e.g., +14155550100). For the Messages API (the recommended modern API), you also need to set your inbound and status webhook URLs in the Vonage dashboard. These are used when messages are received or delivery receipts arrive. You can use placeholder URLs now and update them after deployment. Go to API Settings → Default SMS setting and switch from 'SMS API' to 'Messages API' — this affects which SDK methods work correctly.

The @vonage/server-sdk is the modern unified SDK for all Vonage APIs. It replaces the older nexmo npm package and provides TypeScript types for all API responses. Install it in your Bolt.new project along with its peer dependencies. The SDK supports both Basic Auth (API key + secret) and JWT authentication. For simplicity, Basic Auth is sufficient for sending SMS and most use cases. JWT is required for Voice API calls and provides better security for production apps. Start with Basic Auth and upgrade if you need Voice API functionality. Store all Vonage credentials in your .env file with no NEXT_PUBLIC_ prefix — they are server-side only secrets that must never be included in client bundles. The Vonage API secret especially should never appear in browser-accessible code.

1# .env file additions
2# Vonage credentials — server-side only, never NEXT_PUBLIC_
3VONAGE_API_KEY=your_api_key_here
4VONAGE_API_SECRET=your_api_secret_here
5VONAGE_FROM_NUMBER=+14155550100
6# For Voice API (optional — needed for making/receiving calls)
7# VONAGE_APPLICATION_ID=your_application_id
8# VONAGE_PRIVATE_KEY_PATH=./vonage_private_key.pem

Build the core API route that sends SMS messages using the Vonage Messages API. The Messages API v1 is the modern endpoint that supports SMS, MMS, WhatsApp, Viber, Facebook Messenger, and RCS from a single consistent interface — unlike the legacy SMS API which only handles basic SMS. The API route should validate the input (phone number in E.164 format, non-empty message text), call the Vonage Messages API via the SDK, and return the message UUID on success. Vonage returns a unique message_uuid for each sent message, which you can use to track delivery status via webhooks later. Phone numbers must be in E.164 format (international format with + prefix, e.g., +14155550123 for a US number). A common source of send failures is locally formatted numbers without the country code — validate and normalize numbers before sending.

1// app/api/send-sms/route.ts
2import { NextResponse } from 'next/server';
3import { Vonage } from '@vonage/server-sdk';
4import { Auth } from '@vonage/auth';
5
6const vonage = new Vonage(
7  new Auth({
8    apiKey: process.env.VONAGE_API_KEY ?? '',
9    apiSecret: process.env.VONAGE_API_SECRET ?? '',
10  })
11);
12
13const E164_REGEX = /^\+[1-9]\d{6,14}$/;
14
15export async function POST(request: Request) {
16  try {
17    const { to, text, from } = await request.json();
18
19    if (!to || !E164_REGEX.test(to)) {
20      return NextResponse.json(
21        { error: 'Invalid phone number. Use E.164 format (e.g., +14155550123)' },
22        { status: 400 }
23      );
24    }
25    if (!text || text.trim().length === 0) {
26      return NextResponse.json({ error: 'Message text is required' }, { status: 400 });
27    }
28    if (text.length > 1600) {
29      return NextResponse.json({ error: 'Message exceeds 1600 character limit' }, { status: 400 });
30    }
31
32    const fromNumber = from ?? process.env.VONAGE_FROM_NUMBER;
33    if (!fromNumber) {
34      return NextResponse.json({ error: 'No sender number configured' }, { status: 500 });
35    }
36
37    const response = await vonage.messages.send({
38      message_type: 'text',
39      to,
40      from: fromNumber,
41      channel: 'sms',
42      text: text.trim(),
43    });
44
45    return NextResponse.json({
46      success: true,
47      message_uuid: response.message_uuid,
48    });
49  } catch (error: unknown) {
50    console.error('Vonage SMS error:', error);
51    const vonageError = error as { response?: { data?: { title?: string; detail?: string } } };
52    const detail = vonageError.response?.data?.detail ?? 'Failed to send SMS';
53    return NextResponse.json({ error: detail }, { status: 500 });
54  }
55}

To receive incoming SMS messages or delivery receipts, you need webhook endpoints that Vonage can call when events occur. Vonage sends a POST request to your registered webhook URL with the message content or delivery status. During development in Bolt's WebContainer, these webhooks cannot be tested — Bolt's browser-based runtime cannot receive incoming HTTP connections from external servers like Vonage. This is a fundamental WebContainer limitation: the runtime virtualizes networking within the browser but cannot expose ports to the public internet. Build the webhook handler routes now, but register the webhook URLs in the Vonage dashboard only after deploying. After deployment, go to Vonage Dashboard → API Settings → Default SMS Setting → Messages webhooks, and update the Inbound URL and Status URL to your deployed endpoint URLs. For local development testing before deploying, you can use tools like ngrok to expose a local port — but that requires running Next.js outside Bolt. The practical approach is to deploy early and test webhooks on the deployed URL.

1// app/api/webhooks/vonage-inbound/route.ts
2import { NextResponse } from 'next/server';
3
4export async function POST(request: Request) {
5  try {
6    const payload = await request.json();
7    // Vonage Messages API inbound SMS payload shape
8    const {
9      from,        // sender phone number
10      to,          // your Vonage virtual number
11      text,        // message content
12      timestamp,   // ISO timestamp
13      message_uuid,
14    } = payload;
15
16    console.log('Inbound SMS:', { from, to, text, timestamp, message_uuid });
17
18    // Process the message here:
19    // - Save to database
20    // - Trigger auto-reply
21    // - Route to support ticket
22
23    // IMPORTANT: Always return 200 quickly
24    // Vonage retries delivery if no 200 within 10 seconds
25    return NextResponse.json({ status: 'received' }, { status: 200 });
26  } catch (error) {
27    console.error('Inbound webhook error:', error);
28    // Still return 200 to prevent Vonage from retrying
29    return NextResponse.json({ status: 'error' }, { status: 200 });
30  }
31}