Phone numbers

Inbound SMS

Let agents auto-start chats from incoming text messages (US only)

Overview

Vapi agents can automatically initiate a conversation when your number receives an inbound SMS.

Inbound SMS is currently supported only for Twilio US numbers with SMS enabled, and only for US ↔ US messaging. Messages sent from or to non‑US numbers are not supported.

When enabled, Vapi configures the Twilio Messaging webhook on your number so inbound texts start a session with your agent.

Prefer a walkthrough? Watch the video guide: Inbound SMS with Vapi

Requirements

  • Twilio number in the US
  • SMS capability enabled on that number (in Twilio and in Vapi)
  • US-to-US messaging only

Set up from the dashboard

1

Import your Twilio number

Bring your number into Vapi so we can manage voice and messaging webhooks.

See: Import number from Twilio

2

Enable SMS for the number

In the number settings, turn on the SMS option. Vapi will set the Twilio Messaging webhook to route inbound texts to your agent.

3

Attach your agent (optional)

Assign the assistant you want handling conversations for this number. Inbound texts will start a session with that assistant.

Set up via API

You can enable inbound SMS while creating or updating a Twilio phone number by setting smsEnabled: true.

Create or import a Twilio number with SMS enabled

POST
/phone-number
1import { VapiClient } from "@vapi/server-sdk";
2
3const client = new VapiClient({ token: "YOUR_TOKEN" });
4await client.phoneNumbers.create({
5    provider: "byo-phone-number",
6    credentialId: "credentialId"
7});

Key fields:

  • provider: twilio
  • smsEnabled: true (lets Vapi manage Twilio Messaging webhooks)
smsEnabled
booleanDefaults to true

Controls whether Vapi configures the Twilio Messaging webhook during import/creation. If false, Vapi leaves your Twilio messaging URL unchanged.

Enable SMS on an existing number

PATCH
/phone-number/:id
1import { VapiClient } from "@vapi/server-sdk";
2
3const client = new VapiClient({ token: "YOUR_TOKEN" });
4await client.phoneNumbers.update("id");

Update your number to set smsEnabled: true if it was previously disabled.

Notes and limitations

  • US-only: Both sender and recipient must be US numbers.
  • Twilio only: Other telephony providers are not supported for inbound SMS at this time.
  • Webhooks: With smsEnabled: true, Vapi manages the Twilio Messaging webhook for you.

For full endpoint details, see the OpenAPI reference.

Next steps

Now that you have inbound SMS enabled:

  • SMS chat - Learn how customers can have full conversations with your assistants via SMS
  • Session management - Understand how SMS conversations maintain context automatically
  • Chat quickstart - Explore the underlying chat technology powering SMS interactions