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

# Channels (WhatsApp & SMS)

> Reach users on WhatsApp or SMS — your agent handles the conversation.

Channels let your agent hold conversations over WhatsApp and SMS. You initiate
the thread with an opening message; from then on, the user's replies flow to
the agent and the agent's replies flow back on the same channel — no polling
or webhooks needed on your side.

***

## Start a channel thread

Send the opening message on a channel and bind the recipient's phone number to
a conversation thread.

```bash cURL theme={"dark"}
curl -X POST "https://api-v3.aui.io/apollo-api/messaging/v1/channels/whatsapp/threads" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "phone_number": "+14155551234",
    "agent_display_name": "Aria"
  }'
```

### POST `/messaging/v1/channels/{channel}/threads`

<ParamField path="channel" type="string" required>
  `whatsapp` or `sms`.
</ParamField>

#### Request body

<ParamField body="phone_number" type="string" required>
  Recipient phone number in E.164 format (e.g. `+14155551234`).
</ParamField>

<ParamField body="thread_id" type="string">
  Continue an existing thread instead of starting a new one. Omitted, a new
  thread is created and its id returned.
</ParamField>

<ParamField body="user_id" type="string">
  Your identifier for the user on a new thread. Defaults to the phone number's
  digits.
</ParamField>

<ParamField body="text" type="string">
  Opening message body for SMS. WhatsApp ignores it — the opener uses your
  approved WhatsApp template.
</ParamField>

<ParamField body="agent_display_name" type="string">
  WhatsApp only: the agent name substituted into the template's first
  variable.
</ParamField>

#### Response

<ResponseField name="thread_id" type="string">
  The conversation thread the opener landed on — new or continued.
</ResponseField>

<ResponseField name="message_sid" type="string">
  The provider's message id for the sent opener, for delivery tracking.
</ResponseField>

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "thread_id": "68e78d0dc5a4b19a030d03d6",
    "message_sid": "SM8f14e45fceea167a5a36dedd4bea2543"
  }
  ```
</ResponseExample>

***

## How the conversation continues

Once the thread exists:

1. The recipient replies on WhatsApp/SMS.
2. The reply is routed to your agent on the bound thread.
3. The agent's answer is delivered back on the same channel.

The thread is a regular conversation thread — read its transcript with
[`GET /messaging/v1/threads/{threadId}/messages`](/api/messaging/threads) and
inspect its reasoning with [traces](/api/messaging/traces).

<Info>
  WhatsApp requires the opening message of a business-initiated conversation
  to use a pre-approved template; `text` applies to SMS only. Channel
  configuration (phone numbers, templates) is set up with your AUI contact.
</Info>