Skip to main content
POST
Start a channel thread

Authorizations

Authorization
string
header
required

Access token from POST /management/v1/auth/token (publishable-key exchange) or a login session. Publishable-key tokens are agent-scoped and serve the messaging surface; login tokens also serve management.

Path Parameters

channel
string
required

Channel id: 'whatsapp' or 'sms'.

Body

application/json

Start (or continue) an outbound-first thread on a channel — the agent is identified by your access token. thread_id is optional: present -> continue that thread; absent -> a new thread is created and its id returned.

phone_number
string
required

Recipient phone number in E.164 (e.g. +14155551234).

thread_id
string | null

When set, continue this thread instead of creating a new one.

Pattern: ^[0-9a-fA-F]{24}$
user_id
string | null

User id for a new thread; defaults to the phone's digits.

text
string | null

Opener body for non-template channels (SMS). Ignored by WhatsApp (uses templates).

agent_display_name
string | null

WhatsApp only: bound to template variable {{1}}.

Response

Successful Response

thread_id
string
required

Thread the opener landed on (new or continued).

message_sid
string
required

Provider message id for the sent opener.