How to Integrate Bolt.new with Plivo

Your Plivo integration requires three things from the Plivo console: your Auth ID, your Auth Token, and a Plivo phone number. Log into console.plivo.com. On the main dashboard, you will see your Auth ID (a string starting with 'MA') and your Auth Token immediately. The Auth Token is shown masked by default — click the eye icon to reveal it. Copy both. To get a phone number: in the left sidebar, go to Phone Numbers → Buy Numbers. Filter by the country and select 'SMS' capability (and 'Voice' if you need voice calls). Choose a number and click Buy. Plivo trial accounts start with $0.10 credit which is enough to send several test messages. Trial accounts can send SMS to any number, unlike Twilio which restricts trial sends to verified numbers — this makes initial testing easier with Plivo. Plivo's API uses HTTPS Basic Authentication internally: the Auth ID is the username and Auth Token is the password. The plivo npm package handles this for you — you just pass them to the constructor. Never use them in client-side code or add them to any variable with NEXT_PUBLIC_ prefix.

1# Plivo credentials locations in console.plivo.com:
2# Auth ID: console.plivo.com/dashboard/ → shown as 'AUTH ID' (starts with 'MA')
3# Auth Token: console.plivo.com/dashboard/ → click eye icon to reveal
4# Phone Number: console.plivo.com/phone-numbers/ → your purchased numbers
5
6# API Base URL: https://api.plivo.com/v1/Account/{AUTH_ID}/

The official Plivo Node.js SDK is the `plivo` npm package. It is pure JavaScript with no native binary dependencies, making it fully compatible with Bolt's WebContainer runtime. The package communicates with Plivo's REST API over HTTPS and installs without any compilation step. Configure environment variables in your .env file. Plivo credentials are server-side only — they should never be exposed to the client. Using PLIVO_AUTH_ID and PLIVO_AUTH_TOKEN as names (no NEXT_PUBLIC_ prefix) ensures they stay server-side in Next.js API routes. Create a lib/plivo.ts utility that initializes the Plivo client and exports it. The plivo package constructor takes Auth ID and Auth Token as parameters. Initialize the client once and export the instance — avoid re-initializing on every API call. TypeScript types are included in the plivo package from version 4.x onwards.

1// lib/plivo.ts
2import plivo from 'plivo';
3
4const authId = process.env.PLIVO_AUTH_ID;
5const authToken = process.env.PLIVO_AUTH_TOKEN;
6
7if (!authId || !authToken) {
8  throw new Error('PLIVO_AUTH_ID and PLIVO_AUTH_TOKEN must be set in environment variables');
9}
10
11export const plivoClient = new plivo.Client(authId, authToken);
12export const PLIVO_PHONE_NUMBER = process.env.PLIVO_PHONE_NUMBER!;
13
14// .env content:
15// PLIVO_AUTH_ID=MAxxxxxxxxxxxxxxxxxxxxxxxx
16// PLIVO_AUTH_TOKEN=your_auth_token_here
17// PLIVO_PHONE_NUMBER=+15551234567

The SMS API route is the core of the Plivo integration. It runs server-side in the Next.js API routes directory, has access to the Plivo credentials from environment variables, and communicates with Plivo's API over HTTPS. The route accepts a destination phone number and message, validates them, and sends the SMS using the plivo client. Plivo's message create method signature is slightly different from Twilio's: it takes an object with src (source number), dst (destination number), and text fields. The src field is your Plivo phone number; dst is the recipient in E.164 format. For sending to multiple recipients in one API call, Plivo supports comma-separated numbers in the dst field (e.g., '+14155552671<+14155552672') — a feature Twilio doesn't offer on its standard API. The response from Plivo's message API includes a message_uuid array (array because of multi-recipient support) and an api_id for request tracking. Store the message_uuid if you want to check delivery status later. Plivo returns HTTP 202 Accepted (not 200 OK) for successful message sends — this is important to note for error handling logic.

1// app/api/plivo/send-sms/route.ts
2import { NextResponse } from 'next/server';
3import { plivoClient, PLIVO_PHONE_NUMBER } from '@/lib/plivo';
4
5const E164_REGEX = /^\+[1-9]\d{1,14}$/;
6
7export async function POST(request: Request) {
8  try {
9    const { to, message } = await request.json();
10
11    if (!to || !E164_REGEX.test(to)) {
12      return NextResponse.json(
13        { error: 'Invalid phone number. Use E.164 format: +14155552671' },
14        { status: 400 }
15      );
16    }
17
18    if (!message || message.trim().length === 0) {
19      return NextResponse.json(
20        { error: 'Message cannot be empty' },
21        { status: 400 }
22      );
23    }
24
25    const response = await plivoClient.messages.create(
26      PLIVO_PHONE_NUMBER, // src
27      to,                 // dst
28      message             // text
29    );
30
31    return NextResponse.json({
32      success: true,
33      messageUuid: response.message_uuid[0],
34      apiId: response.api_id,
35    });
36  } catch (error: unknown) {
37    const e = error as { message: string; statusCode?: number };
38    return NextResponse.json(
39      { error: e.message },
40      { status: e.statusCode || 500 }
41    );
42  }
43}

Plivo's voice call API initiates outbound calls using the calls.create() method. Unlike SMS, voice calls require a publicly accessible URL (the answer_url) that Plivo fetches when the call is answered to determine what to do — read a message, collect keypad input, transfer, or hang up. This answer_url is controlled via Plivo's XML markup (similar to Twilio's TwiML). The answer_url limitation means voice calls that play dynamic messages require a deployed endpoint. However, you can specify any public URL as the answer_url — including a static URL hosted elsewhere if you just need to play a fixed message. For development, the recommended pattern is to create the call-handling XML endpoint in Bolt, deploy it quickly to Netlify, and test the full voice flow on the deployed app. Plivo's XML response format uses plivo.Response() to create the response object. Add elements like Speak (text-to-speech), Play (pre-recorded audio), GetDigits (collect DTMF input), Dial (transfer to a number), or Hangup. The Speak element supports text-to-speech with language and voice options — useful for multilingual applications without pre-recording audio files.

1// app/api/plivo/call-answer/route.ts
2import { NextResponse } from 'next/server';
3import plivo from 'plivo';
4
5export async function GET(request: Request) {
6  const { searchParams } = new URL(request.url);
7  const message = searchParams.get('message') || 'Hello, this is an automated message.';
8
9  const response = new plivo.Response();
10  response.addSpeak(message, {
11    voice: 'WOMAN',
12    language: 'en-US',
13    loop: '1',
14  });
15  response.addHangup();
16
17  return new Response(response.toXML(), {
18    headers: { 'Content-Type': 'text/xml' },
19  });
20}
21
22// app/api/plivo/make-call/route.ts
23import { plivoClient, PLIVO_PHONE_NUMBER } from '@/lib/plivo';
24
25export async function POST(request: Request) {
26  try {
27    const { to, message } = await request.json();
28    const appUrl = process.env.NEXT_PUBLIC_APP_URL;
29    const answerUrl = `${appUrl}/api/plivo/call-answer?message=${encodeURIComponent(message)}`;
30
31    const callResponse = await plivoClient.calls.create(
32      PLIVO_PHONE_NUMBER,
33      to,
34      answerUrl,
35      { answerMethod: 'GET' }
36    );
37
38    return NextResponse.json({ success: true, requestUuid: callResponse.request_uuid });
39  } catch (error: unknown) {
40    const e = error as { message: string };
41    return NextResponse.json({ error: e.message }, { status: 500 });
42  }
43}

Outbound SMS and call initiation work during Bolt development. To receive inbound SMS (texts sent to your Plivo number) or handle inbound voice calls, Plivo must send HTTP requests to your server. Since Bolt's WebContainer has no public URL, you must deploy before setting up inbound webhooks. Deploy your Bolt project to Netlify via Settings → Applications → Netlify. After the deploy completes, add your environment variables in Netlify's dashboard (Site Settings → Environment Variables): PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN, PLIVO_PHONE_NUMBER. Redeploy after adding env vars. Configure inbound SMS in the Plivo console: go to Phone Numbers → Your Number → click the number → in the 'Message' section, set the 'Message URL' to your deployed webhook endpoint (https://your-app.netlify.app/api/plivo/incoming-sms) and method to POST. For inbound calls, set the 'Answer URL' and 'Fallback URL' in the 'Voice' section. Create the incoming-sms handler route that parses Plivo's webhook format — Plivo sends form data with fields: From, To, Text, MessageUUID — and responds with a Plivo XML response for auto-replies.

1// app/api/plivo/incoming-sms/route.ts
2import { NextResponse } from 'next/server';
3import plivo from 'plivo';
4
5export async function POST(request: Request) {
6  try {
7    const formData = await request.formData();
8    const from = formData.get('From') as string;
9    const text = formData.get('Text') as string;
10    const messageUuid = formData.get('MessageUUID') as string;
11
12    console.log(`Inbound SMS from ${from}: ${text} (UUID: ${messageUuid})`);
13    // Save to database here...
14
15    // Respond with Plivo XML
16    const response = new plivo.Response();
17    response.addMessage(
18      'Thanks for your message! We will get back to you soon.',
19      { src: process.env.PLIVO_PHONE_NUMBER!, dst: from }
20    );
21
22    return new Response(response.toXML(), {
23      headers: { 'Content-Type': 'text/xml' },
24    });
25  } catch (error: unknown) {
26    const e = error as { message: string };
27    console.error('Plivo webhook error:', e.message);
28    return NextResponse.json({ error: e.message }, { status: 500 });
29  }
30}