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

Import your Twilio number

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

See: Import number from Twilio

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.

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

1 curl -X POST https://api.vapi.ai/phone-number \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "provider": "byo-phone-number",
6   "credentialId": "string"
7 }'

Try it

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

1 curl -X PATCH https://api.vapi.ai/phone-number/id \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{}'

Try it

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

1	curl -X POST https://api.vapi.ai/phone-number \
2	-H "Authorization: Bearer <token>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"provider": "byo-phone-number",
6	"credentialId": "string"
7	}'

1	curl -X PATCH https://api.vapi.ai/phone-number/id \
2	-H "Authorization: Bearer <token>" \
3	-H "Content-Type: application/json" \
4	-d '{}'