@chat-adapter/twilio

npm package: @chat-adapter/twilio

Twilio adapter for Chat SDK. Build SMS and MMS bots with Twilio Messaging webhooks and the Messages API.

Documentation: chat-sdk.dev/adapters/official/twilio · Guides: vercel.com/kb/chat-sdk

Installation

pnpm add @chat-adapter/twilio

Scaffold with the CLI

To scaffold a new Twilio bot with this adapter preselected:

npx create-chat-sdk@latest my-bot --adapter twilio memory

Visit the adapters directory to see other available official and vendor-official adapters.

Usage

The adapter auto-detects TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER, and TWILIO_MESSAGING_SERVICE_SID from environment variables:

import { createTwilioAdapter } from "@chat-adapter/twilio";
import { Chat } from "chat";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    twilio: createTwilioAdapter(),
  },
});

bot.onDirectMessage(async (thread, message) => {
  await thread.post(`You said: ${message.text}`);
});

Point your Twilio Messaging webhook to a route that calls bot.webhooks.twilio(request):

import { bot } from "@/lib/bot";

export async function POST(request: Request): Promise<Response> {
  return bot.webhooks.twilio(request);
}

Configuration

createTwilioAdapter({
  accountSid: process.env.TWILIO_ACCOUNT_SID,
  authToken: process.env.TWILIO_AUTH_TOKEN,
  phoneNumber: process.env.TWILIO_PHONE_NUMBER,
  messagingServiceSid: process.env.TWILIO_MESSAGING_SERVICE_SID,
  webhookUrl: "https://your-domain.com/api/webhooks/twilio",
});

Use phoneNumber for a single Twilio number, or messagingServiceSid when sending through a Twilio Messaging Service.

Typing indicators

WhatsApp and RCS conversations can show a typing indicator via thread.startTyping(). Twilio's v3 Indicators API uses one URL with channel-specific JSON:

• WhatsApp: { channel: "WHATSAPP", messageId } (inbound Message SID)
• RCS: { channel: "RCS", from: "rcs:<agent_id>", to: "rcs:+E164", event: "START" }

On WhatsApp, Twilio also marks the referenced message as read. Phone-number threads are SMS and never send typing. Messaging Service (MG…) threads send RCS typing only when rcsSenderId is set and the thread has an inbound message; rcs: threads always do. If Twilio rejects the request, the adapter logs a warning instead of throwing. Set messagingApiUrl (or apiUrl) to point typing requests at a proxy or emulator.

Media

Inbound MMS media is exposed as attachments. Twilio media URLs are private, so attachments include fetchData() for authenticated downloads.

Outbound MMS supports attachments with public url values. Chat SDK cannot upload binary files to Twilio because Twilio's Messages API requires media URLs that Twilio can fetch.

Templates

Cards create Content API templates on demand for RCS senders only. To send a template on any channel, such as an approved WhatsApp template, pass its ContentSid to sendTemplate:

const twilio = bot.getAdapter("twilio");

const threadId = twilio.encodeThreadId({
  sender: "whatsapp:+15550000001",
  recipient: "whatsapp:+15551234567",
});

await twilio.sendTemplate(threadId, {
  contentSid: "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  contentVariables: { "1": "Tomorrow at 2pm" },
});

WhatsApp templates need a whatsapp: sender or a Messaging Service with a WhatsApp sender. Quick-reply taps on templates sent this way are not decoded as Chat SDK actions: taps that carry a message body arrive as regular messages, and taps without one reach onAction with the raw ButtonPayload as actionId.

Low-level helpers

Runtime-light api, format, voice, and webhook subpaths are available for apps that only need Twilio primitives. These subpaths do not import the full Chat SDK adapter or the twilio npm package.

Voice

Voice calls are exposed as low-level helpers, not routed through the SMS/MMS adapter. Use @chat-adapter/twilio/voice with @chat-adapter/twilio/webhook when your app owns the voice route and wants reusable TwiML or call-update helpers.

Custom voice routes should verify the Twilio signature and apply your own caller allow-list before returning TwiML.

AI Coding Agents

If you use an AI coding agent such as OpenAI Codex, Claude Code, or Cursor, install the Chat SDK skill so it knows the SDK APIs, adapter patterns, and project conventions before writing code.

npx skills add vercel/chat

The skill references bundled documentation in node_modules/chat/docs, plus adapter guides and starter templates in the published package.

You can also install the Vercel Plugin for a broader agent toolkit — it includes the Chat SDK skill alongside specialist agents, agent slash commands, and more:

npx plugins add vercel/vercel-plugin

The plugin is optional; the skill alone is enough to build with Chat SDK.

For agent-readable documentation, see chat-sdk.dev/llms.txt (page index) or chat-sdk.dev/llms-full.txt (full text).

License

MIT