> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> For full documentation content, see https://docs.vapi.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# Inbound SMS

## 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](https://www.youtube.com/watch?v=NCf9Q-z-xUk)

## 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

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

See: [Import number from Twilio](/phone-numbers/import-twilio)

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

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

### Request

POST [https://api.vapi.ai/phone-number](https://api.vapi.ai/phone-number)

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

```python
from vapi import Vapi
from vapi.phone_numbers import CreatePhoneNumbersRequest_ByoPhoneNumber

client = Vapi(
    token="YOUR_TOKEN_HERE",
)

client.phone_numbers.create(
    request=CreatePhoneNumbersRequest_ByoPhoneNumber(
        credential_id="string",
    ),
)

```

```go
package example

import (
    context "context"

    serversdkgo "github.com/VapiAI/server-sdk-go"
    client "github.com/VapiAI/server-sdk-go/client"
    option "github.com/VapiAI/server-sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithToken(
            "YOUR_TOKEN_HERE",
        ),
    )
    request := &serversdkgo.CreatePhoneNumbersRequest{
        ByoPhoneNumber: &serversdkgo.CreateByoPhoneNumberDto{
            CredentialId: "string",
        },
    }
    client.PhoneNumbers.Create(
        context.TODO(),
        request,
    )
}

```

Key fields:

* **provider**: `twilio`
* **smsEnabled**: `true` (lets Vapi manage Twilio Messaging webhooks)

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

### Request

PATCH [https://api.vapi.ai/phone-number/\{id}](https://api.vapi.ai/phone-number/\{id})

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

```python
from vapi import Vapi

client = Vapi(
    token="YOUR_TOKEN_HERE",
)

client.phone_numbers.update(
    id="id",
)

```

```go
package example

import (
    context "context"

    serversdkgo "github.com/VapiAI/server-sdk-go"
    client "github.com/VapiAI/server-sdk-go/client"
    option "github.com/VapiAI/server-sdk-go/option"
)

func do() {
    client := client.NewClient(
        option.WithToken(
            "YOUR_TOKEN_HERE",
        ),
    )
    request := &serversdkgo.UpdatePhoneNumbersRequest{
        Id: "id",
    }
    client.PhoneNumbers.Update(
        context.TODO(),
        request,
    )
}

```

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](https://api.vapi.ai/api-json).

## Next steps

Now that you have inbound SMS enabled:

* **[SMS chat](/chat/sms-chat)** - Learn how customers can have full conversations with your assistants via SMS
* **[Session management](/chat/session-management)** - Understand how SMS conversations maintain context automatically
* **[Chat quickstart](/chat/quickstart)** - Explore the underlying chat technology powering SMS interactions