Send a WhatsApp message
curl --request POST \
--url http://localhost:8080/whatsapp/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"phone_number_id": "<string>",
"contact": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"type": "template",
"template_id": "<string>",
"variables": [
"<string>"
],
"reference_id": "<string>",
"idempotency_key": "<string>",
"header_document_filename": "<string>",
"when_session_open": "append"
}
'import requests
url = "http://localhost:8080/whatsapp/messages"
payload = {
"phone_number_id": "<string>",
"contact": { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a" },
"type": "template",
"template_id": "<string>",
"variables": ["<string>"],
"reference_id": "<string>",
"idempotency_key": "<string>",
"header_document_filename": "<string>",
"when_session_open": "append"
}
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({
phone_number_id: '<string>',
contact: {id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'},
type: 'template',
template_id: '<string>',
variables: ['<string>'],
reference_id: '<string>',
idempotency_key: '<string>',
header_document_filename: '<string>',
when_session_open: 'append'
})
};
fetch('http://localhost:8080/whatsapp/messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "8080",
CURLOPT_URL => "http://localhost:8080/whatsapp/messages",
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([
'phone_number_id' => '<string>',
'contact' => [
'id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
],
'type' => 'template',
'template_id' => '<string>',
'variables' => [
'<string>'
],
'reference_id' => '<string>',
'idempotency_key' => '<string>',
'header_document_filename' => '<string>',
'when_session_open' => 'append'
]),
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 := "http://localhost:8080/whatsapp/messages"
payload := strings.NewReader("{\n \"phone_number_id\": \"<string>\",\n \"contact\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n },\n \"type\": \"template\",\n \"template_id\": \"<string>\",\n \"variables\": [\n \"<string>\"\n ],\n \"reference_id\": \"<string>\",\n \"idempotency_key\": \"<string>\",\n \"header_document_filename\": \"<string>\",\n \"when_session_open\": \"append\"\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("http://localhost:8080/whatsapp/messages")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"phone_number_id\": \"<string>\",\n \"contact\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n },\n \"type\": \"template\",\n \"template_id\": \"<string>\",\n \"variables\": [\n \"<string>\"\n ],\n \"reference_id\": \"<string>\",\n \"idempotency_key\": \"<string>\",\n \"header_document_filename\": \"<string>\",\n \"when_session_open\": \"append\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8080/whatsapp/messages")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone_number_id\": \"<string>\",\n \"contact\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n },\n \"type\": \"template\",\n \"template_id\": \"<string>\",\n \"variables\": [\n \"<string>\"\n ],\n \"reference_id\": \"<string>\",\n \"idempotency_key\": \"<string>\",\n \"header_document_filename\": \"<string>\",\n \"when_session_open\": \"append\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"whatsapp_message_id": "<string>",
"reference_id": "<string>",
"delivery": "session",
"opencx_session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"opencx_message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"statusCode": 422,
"message": "<string>",
"error": "<string>"
}{
"statusCode": 123,
"message": "<string>",
"error": "<string>"
}AI WhatsApp
Send a WhatsApp message
Send any WhatsApp message type from your own platform: templates, text, media, location, location requests, buttons, lists and link buttons. Templates stay out of the inbox until the customer replies.
POST
/
whatsapp
/
messages
Send a WhatsApp message
curl --request POST \
--url http://localhost:8080/whatsapp/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"phone_number_id": "<string>",
"contact": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"type": "template",
"template_id": "<string>",
"variables": [
"<string>"
],
"reference_id": "<string>",
"idempotency_key": "<string>",
"header_document_filename": "<string>",
"when_session_open": "append"
}
'import requests
url = "http://localhost:8080/whatsapp/messages"
payload = {
"phone_number_id": "<string>",
"contact": { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a" },
"type": "template",
"template_id": "<string>",
"variables": ["<string>"],
"reference_id": "<string>",
"idempotency_key": "<string>",
"header_document_filename": "<string>",
"when_session_open": "append"
}
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({
phone_number_id: '<string>',
contact: {id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'},
type: 'template',
template_id: '<string>',
variables: ['<string>'],
reference_id: '<string>',
idempotency_key: '<string>',
header_document_filename: '<string>',
when_session_open: 'append'
})
};
fetch('http://localhost:8080/whatsapp/messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "8080",
CURLOPT_URL => "http://localhost:8080/whatsapp/messages",
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([
'phone_number_id' => '<string>',
'contact' => [
'id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
],
'type' => 'template',
'template_id' => '<string>',
'variables' => [
'<string>'
],
'reference_id' => '<string>',
'idempotency_key' => '<string>',
'header_document_filename' => '<string>',
'when_session_open' => 'append'
]),
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 := "http://localhost:8080/whatsapp/messages"
payload := strings.NewReader("{\n \"phone_number_id\": \"<string>\",\n \"contact\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n },\n \"type\": \"template\",\n \"template_id\": \"<string>\",\n \"variables\": [\n \"<string>\"\n ],\n \"reference_id\": \"<string>\",\n \"idempotency_key\": \"<string>\",\n \"header_document_filename\": \"<string>\",\n \"when_session_open\": \"append\"\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("http://localhost:8080/whatsapp/messages")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"phone_number_id\": \"<string>\",\n \"contact\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n },\n \"type\": \"template\",\n \"template_id\": \"<string>\",\n \"variables\": [\n \"<string>\"\n ],\n \"reference_id\": \"<string>\",\n \"idempotency_key\": \"<string>\",\n \"header_document_filename\": \"<string>\",\n \"when_session_open\": \"append\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8080/whatsapp/messages")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone_number_id\": \"<string>\",\n \"contact\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n },\n \"type\": \"template\",\n \"template_id\": \"<string>\",\n \"variables\": [\n \"<string>\"\n ],\n \"reference_id\": \"<string>\",\n \"idempotency_key\": \"<string>\",\n \"header_document_filename\": \"<string>\",\n \"when_session_open\": \"append\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"whatsapp_message_id": "<string>",
"reference_id": "<string>",
"delivery": "session",
"opencx_session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"opencx_message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"statusCode": 422,
"message": "<string>",
"error": "<string>"
}{
"statusCode": 123,
"message": "<string>",
"error": "<string>"
}One endpoint for every outbound WhatsApp message, driven from your own platform. Pick the shape with
type; the rest of the body is that type’s fields plus the shared phone_number_id, contact, reference_id and idempotency_key.
The contact must have a phone number: an unknown phone number creates the contact, while an id or email must point at an existing contact that has one.
Templates and sessions
Atemplate is the only type that can go out at any time. What happens to it depends on whether the contact already has an open session on that number:
- No open session: the template is sent and no session opens. Nothing shows in the inbox. When the customer replies, their session opens carrying every template sent to them that has not yet appeared on a session, oldest first, before the reply. The response says
"delivery": "hidden". - Open session: by default the template is added to it, visibly (
"delivery": "session"). Send"when_session_open": "hidden"to keep it off the timeline until the customer’s next reply, which then pulls it in before the reply.
422 and "error": "recipient_blocked". A customer who stops marketing messages from you on their device is added to that blocklist automatically.
Every other type
Text, media, location, location requests, buttons, lists and link buttons are replies: WhatsApp only delivers them inside the contact’s 24-hour reply window, and they land on the contact’s open session.- Window closed →
422with"error": "reply_window_closed". Send a template instead. - Window open but the session is closed →
422with"error": "no_open_session". Send a template instead; the customer’s reply opens a new session.
Do you approve?\n[Approve] [Decline]), with the full request kept on the message. Media URLs must be public; links into private networks are refused.
Errors from WhatsApp
When WhatsApp refuses the message, the answer carries a stableerror code and WhatsApp’s own explanation in message:
| Status | error | Meaning |
|---|---|---|
422 | contact_channel_restricted, contact_address_blocked | The contact asked not to be reached on WhatsApp, or the number is on the do-not-contact list. Nothing is sent; see refused sends. |
422 | recipient_unreachable | The number is not on WhatsApp, or cannot be messaged. |
422 | template_pending, template_paused, template_in_appeal, template_disabled | The template is not sendable in its current state. |
422 | rejected_by_whatsapp, sender_restricted | WhatsApp rejected the message or restricted the sender. |
429 | rate_limited | Sending too fast for this number; retry later. |
502 | provider_error, provider_unreachable | WhatsApp failed or could not be reached; nothing was sent. |
502 | send_outcome_unknown | The connection dropped after the request left, or WhatsApp accepted the message but its result could not be recorded; the message may have been delivered. See retries. |
Retries
Send the sameidempotency_key on a retry and you get the first result back without a second message going out. Keys are permanent per organization and the body is not compared, so key on the message (order id + event), not on the order alone.
- A key whose send WhatsApp refused is released: the retry sends.
- A key whose outcome is unknown stays taken and keeps answering
502 send_outcome_unknown; use a new key to send again. - A retry that overlaps the first request gets
409with"error": "idempotency_key_in_flight". A first request that never finished on our side stops blocking after 10 minutes: its key then answers502 send_outcome_unknownlike any other unknown outcome.
reference_id is yours (an order id, for example): it is stored and echoed back in the response.
Delivery
The response confirms WhatsApp accepted the message (whatsapp_message_id). Delivery, read and failure receipts are kept on the send for the inbox and the timeline; they are not yet readable through the API.Authorizations
Body
application/json
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
Send the same key on a retry and the first result comes back without a second message going out. Keys are permanent per organization and the body is not compared, so key on the message (order id + event), not on the order. A key whose send WhatsApp refused is released; one whose outcome is unknown stays taken.
Required string length:
1 - 255Response
Default Response
- Option 1
- Option 2
Was this page helpful?