Start WhatsApp Conversations with an AI Assistant

Use POST /v2/ai/assistants/{assistant_id}/chat/whatsapp to reach out to a customer first. The assistant picks one of its approved WhatsApp templates, fills the variables from your content, and Telnyx sends it. When the customer replies, the reply lands in the same conversation and the assistant answers free-form within the 24-hour customer service window.

Prerequisites

A connected WhatsApp number on your account. See the quickstart.
The assistant set as the AI assistant on that number’s messaging profile. Replies are routed through the profile’s assistant, so a request with any other assistant is rejected.
A whatsapp_template tool on the assistant with at least one approved template.
Data retention enabled and PII redaction disabled in the assistant’s privacy settings.

Send the first message

curl -X POST "https://api.telnyx.com/v2/ai/assistants/{assistant_id}/chat/whatsapp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+13125550001",
    "to": "+13125550002",
    "content": "Send the login verification code 482913 to the customer.",
    "conversation_metadata": {"order_id": "A1"}
  }'

Field	Required	Description
`from`	Yes	Your WhatsApp number in E.164 format.
`to`	Yes	The customer’s number in E.164 format, or their WhatsApp business-scoped user ID.
`content`	Yes	Instruction for the assistant, including the values for the template variables.
`conversation_metadata`	No	Values stored on the conversation. Keys starting with `telnyx_` and the `assistant_id` key are reserved.

The response returns the conversation and the sent template message:

{
  "conversation_id": "59f1f39e-180c-4f5d-81e9-393b46ca4077",
  "message_id": "4031a0e8-f724-4e22-a086-0f18720ac829"
}

Track delivery of message_id with your usual messaging webhooks, and read the conversation’s messages, including the customer’s reply, with the conversations API.

Errors

Status	Meaning
`400`	Invalid or missing fields, a reserved metadata key, an invalid `from` or `to`, or the assistant is not the one set on the `from` number’s messaging profile.
`401`	The API key is missing or invalid.
`403`	The `from` number is not on your account, or the account is inactive, blocked, unverified or has messaging disabled.
`404`	The assistant does not exist.
`409`	The `from` number’s messaging profile is disabled, or a request with the same `Idempotency-Key` is still being processed.
`413`	The request has an `Idempotency-Key` and its body is larger than 256 KB.
`422`	The assistant did not return a template, its privacy settings do not allow storing conversations, or an `Idempotency-Key` was reused with a different body.
`503`	The assistant could not be reached, or the conversation or template send failed. Retry the request.

Getting Started

Sending Messages

Coexistence

Calling

Management API

Sending API

For AI Agents

Start WhatsApp Conversations with an AI Assistant

Start WhatsApp Conversations with an AI Assistant

Prerequisites

Send the first message

Errors

​Start WhatsApp Conversations with an AI Assistant

​Prerequisites

​Send the first message

​Errors

Start WhatsApp Conversations with an AI Assistant

Prerequisites

Send the first message

Errors