Open (or find) the thread to write to a recipient in
POST/api/compose/start
A channel, and either contact_id or the address typed into the box
(to: E.164 for a number channel, an e-mail address for a mailbox).
Returns the person's live thread on that channel when there is one —
a history is never split in two — otherwise opens one, assigned to
the member when the tenant's assignment rules say so (doc 64 §2 #32)
and always when the member could not reply in it otherwise.
Nothing is sent. The client lands in the thread and writes there; when
template_required is true (WhatsApp outside the 24-hour window, which
a new number always is) the thread's template picker is the way in.
A number nobody owns creates an UNSAVED contact (it lives in the inbox
like one an inbound message creates). When the number might already
belong to somebody, the first call answers 409 possible_duplicate
with the candidates; allow_new: true confirms a new person. A thread
opened here that nobody writes in is removed again, with the contact
made for it — by POST /api/compose/conversations/{conversation}/abandon
and by an hourly sweep.
Requires the conversations.reply permission and the channel's
access list. Throttled (30/min).
Request
Responses
- 200
- 201
- 401
- 403
- 404
- 409
- 422
- 429
The person's existing live thread on this channel.
A new thread was opened.
Not authenticated. code: account_disabled means the member's seat was deactivated in this workspace: the session is over even though the token was not revoked (clients sign out and clean up).
Authenticated but not allowed.
Resource not found (or not visible to the current tenant).
The number may already belong to these contacts; repeat with allow_new to create a new one.
The request failed validation.
Rate limit exceeded.
Response Headers
Request quota for the current window.
Remaining requests in the current window.
Seconds to wait before retrying.