Sign in
Assistants

Assistant WhatsApp Chat

Start a WhatsApp conversation with a customer from the business side. This endpoint:

  1. Validates that from is a WhatsApp number on your account whose messaging profile has this assistant configured
  2. Creates a new whatsapp_chat conversation with the provided metadata
  3. Asks the assistant to pick one of its approved WhatsApp templates and fill its variables from content
  4. Sends the template from from to to
  5. Returns the conversation ID and the message ID

When the customer replies, the reply is routed to the same conversation and the assistant answers within the 24-hour customer service window. The assistant needs a whatsapp_template tool with at least one approved template, data retention enabled and PII redaction disabled.

post/ai/assistants/{assistant_id}/chat/whatsapp

Path parameters

assistant_idstring required

Unique identifier of the assistant. Must be the assistant configured on the messaging profile of the from number.

Headers

Idempotency-Keystring

Optional opaque, unquoted key for safely retrying the same logical request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores. Generate a unique UUID v4 for each operation and reuse it only when retrying that operation with the same request. Invalid headers—including duplicate, empty, malformed, or overlong values—return 400 with error code 10015. A request already in progress with the same key returns 409; reusing the key with a different request returns 422. Only successful responses are replayed, for up to 24 hours. Do not include sensitive data in the key.

Request body

fromstring required

WhatsApp number on your account to send from, in E.164 format. Its messaging profile must have this assistant configured.

tostring required

Customer to message, as an E.164 phone number or a WhatsApp business-scoped user ID (BSUID).

contentstring required

Instruction for the assistant, including the values for the template variables, e.g. Send the login verification code 482913 to the customer.

conversation_metadataobject

Metadata stored on the conversation. Keys starting with telnyx_ and the assistant_id key are reserved.

Response

Successful Response

conversation_idstring required

ID of the conversation created for this WhatsApp chat.

message_idstring required

ID of the WhatsApp template message that was sent.

Changes

Changed in 1 of the 112 revisions of this API.1

Of the 112 revisions, 1 has no diff computed.