How to Integrate Bolt.new with Twilio

Your Twilio integration requires three pieces of information from the Twilio Console: your Account SID (a 34-character string starting with 'AC'), your Auth Token (another 34-character string), and a Twilio phone number that can send SMS. Log into console.twilio.com. On the main dashboard page, your Account SID and Auth Token are displayed (click the eye icon to reveal the Auth Token). Copy both. Next, get a phone number: in the left sidebar, navigate to Phone Numbers → Manage → Buy a Number. Filter by SMS capability and choose a number in your country. Trial accounts get one free number and can only send to verified phone numbers (add your personal number under Phone Numbers → Verified Caller IDs for testing). For Twilio Verify (OTP), go to Verify → Services → Create Service. Give it a name like 'MyApp Verification' and copy the Service SID (starts with 'VA') shown after creation.

The twilio npm package is the official Node.js helper library. It's pure JavaScript and works cleanly in Bolt's WebContainer runtime. Prompt Bolt to install it and set up the environment variable structure. Twilio credentials must only be accessed server-side — never in client components. Your Account SID and Auth Token give full control over your Twilio account including sending messages and making calls to any number. In a Next.js project, server-side environment variables (without NEXT_PUBLIC_) are only readable in API routes and server components. The phone number can also be stored as an environment variable so you can change it without touching code — useful when moving from a trial number to a production number.

1# .env
2TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
3TWILIO_AUTH_TOKEN=your_auth_token_here
4TWILIO_PHONE_NUMBER=+15551234567
5TWILIO_VERIFY_SERVICE_SID=VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The SMS API route is the core of your Twilio integration. It receives a phone number and message from your frontend, validates the input, then uses the Twilio client to send the SMS. The route runs server-side in Bolt's WebContainer Node.js process, so it can access environment variables and make outbound HTTPS calls to Twilio's API without CORS restrictions. This outbound SMS sending works fully in the Bolt preview — you can test it immediately without deploying. Important: always validate phone number format before passing to Twilio. Numbers must be in E.164 format (+[country code][number], e.g., +14155552671). The Twilio SDK throws an error if the format is invalid, so a simple regex validation in the route prevents unhelpful error messages.

1import twilio from 'twilio';
2import { NextResponse } from 'next/server';
3
4const client = twilio(
5  process.env.TWILIO_ACCOUNT_SID,
6  process.env.TWILIO_AUTH_TOKEN
7);
8
9const E164_REGEX = /^\+[1-9]\d{1,14}$/;
10
11export async function POST(request: Request) {
12  try {
13    const { to, message } = await request.json();
14
15    if (!to || !E164_REGEX.test(to)) {
16      return NextResponse.json(
17        { error: 'Invalid phone number. Use E.164 format: +14155552671' },
18        { status: 400 }
19      );
20    }
21
22    if (!message || message.trim().length === 0) {
23      return NextResponse.json(
24        { error: 'Message cannot be empty' },
25        { status: 400 }
26      );
27    }
28
29    const msg = await client.messages.create({
30      body: message,
31      from: process.env.TWILIO_PHONE_NUMBER!,
32      to,
33    });
34
35    return NextResponse.json({ success: true, messageSid: msg.sid });
36  } catch (error: unknown) {
37    const twilioError = error as { message: string; code?: number };
38    return NextResponse.json(
39      { error: twilioError.message, code: twilioError.code },
40      { status: 500 }
41    );
42  }
43}

Twilio Verify provides a managed OTP service that handles the complexity of phone verification: generating secure codes, managing expiry (10 minutes by default), rate limiting (5 attempts per verification), and supporting both SMS and voice delivery. Using Verify instead of building your own OTP system saves significant development time and avoids security mistakes. The flow has two API calls: first, send a verification code to the user's phone number; second, check the code the user entered. Twilio handles everything in between. Verify is separate from basic SMS — it uses a Verify Service (identified by a Service SID starting with 'VA') and has its own pricing ($0.05 per verification, separate from message costs).

1// app/api/twilio/verify/send/route.ts
2import twilio from 'twilio';
3import { NextResponse } from 'next/server';
4
5const client = twilio(
6  process.env.TWILIO_ACCOUNT_SID,
7  process.env.TWILIO_AUTH_TOKEN
8);
9
10export async function POST(request: Request) {
11  try {
12    const { phoneNumber } = await request.json();
13
14    const verification = await client.verify.v2
15      .services(process.env.TWILIO_VERIFY_SERVICE_SID!)
16      .verifications.create({ to: phoneNumber, channel: 'sms' });
17
18    return NextResponse.json({ status: verification.status });
19  } catch (error: unknown) {
20    const e = error as { message: string };
21    return NextResponse.json({ error: e.message }, { status: 500 });
22  }
23}
24
25// app/api/twilio/verify/check/route.ts
26export async function POST(request: Request) {
27  try {
28    const { phoneNumber, code } = await request.json();
29
30    const check = await client.verify.v2
31      .services(process.env.TWILIO_VERIFY_SERVICE_SID!)
32      .verificationChecks.create({ to: phoneNumber, code });
33
34    if (check.status === 'approved') {
35      return NextResponse.json({ verified: true });
36    }
37    return NextResponse.json(
38      { verified: false, error: 'Invalid or expired code' },
39      { status: 400 }
40    );
41  } catch (error: unknown) {
42    const e = error as { message: string };
43    return NextResponse.json({ error: e.message }, { status: 500 });
44  }
45}

Outbound SMS, WhatsApp, and Twilio Verify all work in the Bolt preview. However, receiving incoming SMS messages (when someone texts your Twilio number) and receiving voice call webhooks requires Twilio to call an HTTP endpoint on your server. Bolt's WebContainer has no public URL — it runs inside a browser tab that Twilio cannot reach. Deploy to Netlify or Bolt Cloud first. After deployment, go to the Twilio Console → Phone Numbers → Manage → Active Numbers → click your number. In the Messaging Configuration section, set the 'A message comes in' webhook URL to your deployed API endpoint (e.g., https://your-app.netlify.app/api/twilio/incoming-sms). Twilio supports HTTP or HTTPS. Always use HTTPS in production. Create the incoming webhook handler route that parses Twilio's webhook body, extracts the sender number and message, and responds with TwiML (Twilio Markup Language) to control the response.

1import { NextResponse } from 'next/server';
2import twilio from 'twilio';
3
4export async function POST(request: Request) {
5  const formData = await request.formData();
6  const from = formData.get('From') as string;
7  const body = formData.get('Body') as string;
8  const messageSid = formData.get('MessageSid') as string;
9
10  console.log(`Incoming SMS from ${from}: ${body}`);
11  // Save to database here...
12
13  // Respond with TwiML
14  const twiml = new twilio.twiml.MessagingResponse();
15  twiml.message('Thanks for your message! We will get back to you soon.');
16
17  return new Response(twiml.toString(), {
18    headers: { 'Content-Type': 'text/xml' },
19  });
20}