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

<Info>
  In some regions, automated text messages without consent may violate local regulations. You are responsible for ensuring compliance with all relevant laws.
</Info>

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](/docs/documentation/deploy/sms/inbound) 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](/docs/documentation/deploy/phone/connect-a-phone-number) 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](/docs/documentation/build/steps/handoff) (`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](/docs/documentation/build/data/variables), the same way inbound SMS uses the sender's number.