---
title: "Assistant WhatsApp Chat"
method: POST
path: "/ai/assistants/{assistant_id}/chat/whatsapp"
tags: ["Assistants"]
---

# Assistant WhatsApp Chat

`POST /ai/assistants/{assistant_id}/chat/whatsapp`

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.

## Path parameters

- `assistant_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- AssistantWhatsappChatReq
  - `from` string, required — WhatsApp number on your account to send from, in E.164 format. Its messaging profile must have this assistant configured.
  - `to` string, required — Customer to message, as an E.164 phone number or a WhatsApp business-scoped user ID (BSUID).
  - `content` string, required — Instruction for the assistant, including the values for the template variables, e.g. `Send the login verification code 482913 to the customer.`
  - `conversation_metadata` object — Metadata stored on the conversation. Keys starting with `telnyx_` and the `assistant_id` key are reserved.

## Response `200`

Successful Response

- AssistantWhatsappChatResponse
  - `conversation_id` string, required — ID of the conversation created for this WhatsApp chat.
  - `message_id` string, required — ID of the WhatsApp template message that was sent.

## Other responses

- `400` — Bad Request. Missing required fields or a reserved `conversation_metadata` key, or the assistant is not the one configured on the messaging profile of `from` (10015). Invalid JSON (10023). A field of the wrong type, for example a non-string `from`, `to` or `content`, or a `conversation_metadata` value that is not a string, integer or boolean (10026). `from` is not a valid WhatsApp number on a messaging profile (40305). `to` is not a valid E.164 number or BSUID (40310). Invalid, duplicate, empty, malformed, or overlong Idempotency-Key headers are rejected by Edge with HTTP 400 and error code 10015.
- `401` — Authentication Failed (10009). The API key is missing or invalid.
- `403` — Forbidden. The `from` number is not associated with your account (10010), messaging is disabled on the account (40314), or the account is inactive (20012), blocked (20013) or unverified (20014).
- `404` — Not Found (10005). The assistant does not exist.
- `409` — Conflict. The messaging profile of `from` is disabled (40312), or a request with the same Idempotency-Key is still being processed (10036), in which case retry later with the same key and request.
- `413` — Payload Too Large. A request sent with an Idempotency-Key whose body exceeds the endpoint's Edge replay-protection limit (256 KB) is rejected before it reaches the service. Requests sent without the header are not subject to this limit.
- `422` — Unprocessable Entity (10027). The assistant did not return a WhatsApp template, or its privacy settings do not allow storing conversations. Reusing an Idempotency-Key with a different request body also returns 422 with error code 10027.
- `503` — Service Unavailable (10037). The assistant could not be looked up, the conversation could not be started, or the template could not be sent. Retry the request.

## Changes

> 112 revisions in range; 1 not diffed.

- **2026-10-01** `3957c3463375` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/ai/assistants/:assistant_id/chat/whatsapp/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/b64f92d897b2?raw)