Assistant WhatsApp Chat

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

Validates that from is a WhatsApp number on your account whose messaging profile has this assistant configured
Creates a new whatsapp_chat conversation with the provided metadata
Asks the assistant to pick one of its approved WhatsApp templates and fill its variables from content
Sends the template from from to to
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

assistants

{assistant_id}

chat

Assistant WhatsApp Chat

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

import requests

url = "https://api.telnyx.com/v2/ai/assistants/{assistant_id}/chat/whatsapp"

payload = {
    "from": "+13125550001",
    "to": "+13125550002",
    "content": "Send the login verification code 482913 to the customer.",
    "conversation_metadata": { "order_id": "A1" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    from: '+13125550001',
    to: '+13125550002',
    content: 'Send the login verification code 482913 to the customer.',
    conversation_metadata: {order_id: 'A1'}
  })
};

fetch('https://api.telnyx.com/v2/ai/assistants/{assistant_id}/chat/whatsapp', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.telnyx.com/v2/ai/assistants/{assistant_id}/chat/whatsapp",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from' => '+13125550001',
    'to' => '+13125550002',
    'content' => 'Send the login verification code 482913 to the customer.',
    'conversation_metadata' => [
        'order_id' => 'A1'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.telnyx.com/v2/ai/assistants/{assistant_id}/chat/whatsapp"

	payload := strings.NewReader("{\n  \"from\": \"+13125550001\",\n  \"to\": \"+13125550002\",\n  \"content\": \"Send the login verification code 482913 to the customer.\",\n  \"conversation_metadata\": {\n    \"order_id\": \"A1\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.telnyx.com/v2/ai/assistants/{assistant_id}/chat/whatsapp")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": \"+13125550001\",\n  \"to\": \"+13125550002\",\n  \"content\": \"Send the login verification code 482913 to the customer.\",\n  \"conversation_metadata\": {\n    \"order_id\": \"A1\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.telnyx.com/v2/ai/assistants/{assistant_id}/chat/whatsapp")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from\": \"+13125550001\",\n  \"to\": \"+13125550002\",\n  \"content\": \"Send the login verification code 482913 to the customer.\",\n  \"conversation_metadata\": {\n    \"order_id\": \"A1\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10036",
      "title": "Resource is being processed",
      "detail": "A request with this Idempotency-Key is already being processed.",
      "source": {
        "pointer": "/header/Idempotency-Key"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

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.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9_-]{1,255}$

Path Parameters

assistant_id

string

required

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

Body

application/json

from

string

required

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

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

Conversation Metadata · object

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

Show child attributes

Response

Successful Response

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.

Assistant WhatsApp Chat

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

import requests

url = "https://api.telnyx.com/v2/ai/assistants/{assistant_id}/chat/whatsapp"

payload = {
    "from": "+13125550001",
    "to": "+13125550002",
    "content": "Send the login verification code 482913 to the customer.",
    "conversation_metadata": { "order_id": "A1" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    from: '+13125550001',
    to: '+13125550002',
    content: 'Send the login verification code 482913 to the customer.',
    conversation_metadata: {order_id: 'A1'}
  })
};

fetch('https://api.telnyx.com/v2/ai/assistants/{assistant_id}/chat/whatsapp', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.telnyx.com/v2/ai/assistants/{assistant_id}/chat/whatsapp",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from' => '+13125550001',
    'to' => '+13125550002',
    'content' => 'Send the login verification code 482913 to the customer.',
    'conversation_metadata' => [
        'order_id' => 'A1'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.telnyx.com/v2/ai/assistants/{assistant_id}/chat/whatsapp"

	payload := strings.NewReader("{\n  \"from\": \"+13125550001\",\n  \"to\": \"+13125550002\",\n  \"content\": \"Send the login verification code 482913 to the customer.\",\n  \"conversation_metadata\": {\n    \"order_id\": \"A1\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.telnyx.com/v2/ai/assistants/{assistant_id}/chat/whatsapp")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": \"+13125550001\",\n  \"to\": \"+13125550002\",\n  \"content\": \"Send the login verification code 482913 to the customer.\",\n  \"conversation_metadata\": {\n    \"order_id\": \"A1\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.telnyx.com/v2/ai/assistants/{assistant_id}/chat/whatsapp")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from\": \"+13125550001\",\n  \"to\": \"+13125550002\",\n  \"content\": \"Send the login verification code 482913 to the customer.\",\n  \"conversation_metadata\": {\n    \"order_id\": \"A1\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10036",
      "title": "Resource is being processed",
      "detail": "A request with this Idempotency-Key is already being processed.",
      "source": {
        "pointer": "/header/Idempotency-Key"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

Guides

Missions

AI Insights

Assistants API

Missions API

Conversations API

For AI Agents

Assistant WhatsApp Chat

Authorizations

Headers

Path Parameters

Body

Response