> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Outbound SMS

> Programmatically start an SMS conversation from your Twilio number.

> [!NOTE]
>
> In some regions, automated text messages without consent may violate local regulations. You are responsible for ensuring compliance with all relevant laws.

Outbound SMS lets your agent start a text conversation programmatically. You can use this to send a first message for things like welcome texts, appointment reminders, or follow-ups, triggered from tools like Zapier or your own backend scripts. The recipient's reply is handled as [inbound SMS](https://www.voiceflow.com/docs/documentation/deploy/sms/inbound.md) and continues the same conversation.

Outbound SMS is supported for Twilio numbers that are assigned for SMS. The number you send from must already be [connected](https://www.voiceflow.com/docs/documentation/deploy/phone/connect-a-phone-number.md) and assigned to an environment for SMS.

## Starting an outbound conversation

To start an outbound conversation, send a `POST` request to your agent's outbound SMS endpoint. You can find this endpoint by opening **Phone numbers** in the sidebar, then clicking **View** in the **Outbound SMS API** column for your number.

The modal displays a ready-to-use curl command with your agent's endpoint and required headers. You can also test the message directly from this modal by entering a phone number and clicking **Send**.

Each request starts a fresh conversation. Your agent writes the first message from its launch path. You do not supply the message body in the request.

## API reference

### Endpoint

```
POST https://runtime-api.voiceflow.com/v1/phone-number/<PHONE_NUMBER_ID>/sms/outbound
```

### Headers

| Header | Value |
| - | - |
| `Authorization` | Your [Dialog Manager API key](https://docs.voiceflow.com/reference/how-to-get-your-voiceflow-project-api-key) |
| `Content-Type` | `application/json` |

### Request body

```json theme={null}
{
  "to": "+15551234567",
  "variables": {
    "user_name": "Jane",
    "account_type": "Premium"
  }
}
```

| Field | Description |
| - | - |
| `to` | The phone number to text in E.164 format (eg: `+15551234567`). |
| `variables` | Optional. A JSON object of string values to inject when the conversation starts. |

### Response

A successful request returns `202` with the new session ID. The first text is sent after the request returns, once the agent has run its launch path.

```json theme={null}
{
  "sessionID": "session-key-1"
}
```

The request is refused if the number is not assigned for SMS, the recipient number is invalid, or the recipient is already in an active turn or a [live agent handoff](https://www.voiceflow.com/docs/documentation/build/steps/handoff.md) (`409`). Outbound SMS is also rate limited per recipient and per phone number.

The recipient's phone number is set as the `user_id` [variable](https://www.voiceflow.com/docs/documentation/build/data/variables.md), the same way inbound SMS uses the sender's number.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.