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

Open the Twilio import form

Open the Dashboard, select Phone Numbers, and select Create Phone Number. Choose Import Twilio under Phone Number Options.

2

Import the number with SMS enabled

Enter the number and its Twilio credentials. Turn on SMS Enabled, then select Import from Twilio. Vapi will configure the Twilio Messaging webhook to route inbound texts to your agent.

Enable SMS while importing a Twilio number

For the complete import workflow, see Import a Twilio number.

3

Choose an assistant (optional)

To assign a default assistant, open the imported phone number. Under Inbound Settings, choose the Assistant that should handle conversations for this number, then select Save. 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
1curl -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
1curl -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