> ## Documentation Index
> Fetch the complete documentation index at: https://polyai-mintlify-7055a538.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Send an outbound SMS/RCS

> Send an outbound SMS or RCS message and open a reply-enabled conversation session.

Sends an outbound message to the specified user number and opens a new conversation session. The endpoint handles both **SMS** and **RCS** on the same route: for SMS, send to a plain E.164 number; for RCS, prefix the recipient number with `rcs:` and pass a Twilio Messaging Service SID for your RCS sender in `messaging_service_sid`. If the recipient's device or carrier doesn't support RCS, delivery automatically falls back to SMS. The message behaves like a greeting, so it is fully part of the conversation context that the agent can access. If the user replies, the agent handles the conversation as a normal SMS or RCS session.

<Warning>
  It is your responsibility to ensure that messages are sent in compliance with applicable laws and regulations, including [A2P 10DLC registration](/voice-channel/message-templates#a2p-10dlc-registration-us-and-canada) for US and Canadian numbers, and [RCS Business Messaging registration](/messaging-channel/sms-and-rcs/sms-and-rcs-campaign-registration-compliance-requirements-us) where applicable.
</Warning>

## Request

### Headers

<ParamField header="X-PolyAi-Auth-Token" type="string" required>
  Your PolyAI API key, provisioned in the **API keys** tab under your account section in Agent Studio.
</ParamField>

<ParamField header="X-TOKEN-ID" type="string" required>
  Connector ID for the target project. Contact your PolyAI representative.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

### Body

<ParamField body="message" type="string">
  The plain-text message to send to the user. Delivered as RCS when the recipient supports it, or as SMS otherwise.
</ParamField>

<ParamField body="user_number" type="string" required>
  Recipient phone number in E.164 format (e.g. `+14155551234`). For **RCS**, prefix the number with `rcs:` (e.g. `rcs:+14155551234`).
</ParamField>

<ParamField body="agent_number" type="string">
  Sender phone number in E.164 format. Must be one of the numbers provisioned for your project. If omitted, the API picks one automatically from the numbers available for the connector token's environment. Not used for RCS — RCS senders are selected via `messaging_service_sid`.
</ParamField>

<ParamField body="messaging_service_sid" type="string">
  **Required for RCS.** The Twilio Messaging Service SID for your RCS sender.
</ParamField>

## Response

| Status                      | Description                                                                                        |
| --------------------------- | -------------------------------------------------------------------------------------------------- |
| `202 Accepted`              | Message will be sent and a conversation session will be created.                                   |
| `400 Bad Request`           | Invalid body, missing fields, bad E.164 format, or `agent_number` not provisioned for the project. |
| `401 Unauthorized`          | Missing or invalid `X-PolyAi-Auth-Token`.                                                          |
| `403 Forbidden`             | API key account does not match the connector's account.                                            |
| `404 Not Found`             | Connector not found, or no numbers provisioned for this project.                                   |
| `429 Too Many Requests`     | Per-project rate limit exceeded.                                                                   |
| `500 Internal Server Error` | Unexpected server error.                                                                           |

The `202` response has an empty body.

## Example

### SMS

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.us-1.platform.polyai.app/v1/outbound-sms \
    -H "X-PolyAi-Auth-Token: YOUR_API_KEY" \
    -H "X-TOKEN-ID: YOUR_CONNECTOR_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "message": "Hi Jane, your appointment is confirmed for tomorrow at 2pm. Reply to this message if you need to reschedule.",
      "user_number": "+14155551234"
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  url = "https://api.us-1.platform.polyai.app/v1/outbound-sms"
  headers = {
      "X-PolyAi-Auth-Token": "YOUR_API_KEY",
      "X-TOKEN-ID": "YOUR_CONNECTOR_ID",
      "Content-Type": "application/json",
  }
  payload = {
      "message": "Hi Jane, your appointment is confirmed for tomorrow at 2pm. Reply to this message if you need to reschedule.",
      "user_number": "+14155551234",
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.status_code)  # 202
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    'https://api.us-1.platform.polyai.app/v1/outbound-sms',
    {
      method: 'POST',
      headers: {
        'X-PolyAi-Auth-Token': 'YOUR_API_KEY',
        'X-TOKEN-ID': 'YOUR_CONNECTOR_ID',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        message:
          'Hi Jane, your appointment is confirmed for tomorrow at 2pm. Reply to this message if you need to reschedule.',
        user_number: '+14155551234',
      }),
    }
  );

  console.log(response.status); // 202
  ```
</CodeGroup>

### RCS

Outbound RCS uses the same endpoint. Prefix `user_number` with `rcs:` and pass the Twilio Messaging Service SID for your RCS sender in `messaging_service_sid`. If the recipient's device doesn't support RCS, the message automatically falls back to SMS — no extra handling needed.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.us-1.platform.polyai.app/v1/outbound-sms \
  -H "X-PolyAi-Auth-Token: YOUR_API_KEY" \
  -H "X-TOKEN-ID: YOUR_CONNECTOR_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hi Jane, your appointment is confirmed for tomorrow at 2pm. Reply to this message if you need to reschedule.",
    "user_number": "rcs:+14155551234",
    "messaging_service_sid": "YOUR_TWILIO_MESSAGING_SERVICE_SID"
  }'
```

This can lead to a conversation like:

| Direction   | Message                                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| **Agent →** | Hi Jane, your appointment is confirmed for tomorrow at 2pm. Reply to this message if you need to reschedule. |
| **← User**  | Can I move it to 3pm instead?                                                                                |
| **Agent →** | Of course, I've rescheduled your appointment to 3pm tomorrow. See you then!                                  |

## Error response format

All error responses return a JSON object:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "A human-readable description of the error."
}
```

## Notes

* **SMS vs RCS delivery** — SMS is sent to a plain E.164 `user_number`. RCS requires an `rcs:` prefix on `user_number` **and** a `messaging_service_sid`. If the recipient can't receive RCS, delivery automatically falls back to SMS.
* **Agent number selection** — by default the API picks from the numbers provisioned for your project for the environment linked to the connector token. Pass `agent_number` to override; it must be one of the provisioned numbers or the request is rejected with a `400`.
* **Rate limits** are applied per project. If you hit a `429`, back off and retry.
* **Inactivity timeout** — if the conversation is engaged (the user has replied), after 24 hours of inactivity a warning message is sent. If the user replies within 10 minutes, the conversation stays open and a new 24-hour inactivity timer starts. Otherwise the session terminates.
* **Number availability** — not every country supports SMS or RCS. Check [Number availability & compliance](/voice-channel/number-availability) for country-by-country details, throughput limits, and regulatory links before sending to a new region.