Home API and integrations | Keys, endpoints and webhooks How to send a proactive WhatsApp message via API

How to send a proactive WhatsApp message via API

Last updated on Sep 23, 2026

The most up-to-date documentation for the Cloud Humans APIs is at docs.cloudhumans.com/api-reference. If this article and the reference disagree, the reference prevails.

When to use

  • You want to start a WhatsApp conversation via API from an external system
  • You need to trigger Meta-approved templates with dynamic variables
  • You need to understand the expected behavior of the ticket created by this API

Prerequisites

About this article

This endpoint creates a proactive WhatsApp conversation using a previously configured template. The template parameters are dynamic and vary according to the template configuration.

Ticket creation behavior

Since the system does not know which agent should receive it, the message is not assigned when created. That is why the bubble appears green (automated messages) instead of orange.

  • Creates a new ticket — unless the inbox is configured with single conversation (lock to single conversation), in which case the message is added to the contact's existing conversation

  • The ticket is created with open status

If the customer has two open tickets, new messages sent by the customer will always be routed to the most recent ticket.

Endpoint

POST https://cloudchat.cloudhumans.com/api/v1/accounts/{account_id}/conversations/create_proactive_whatsapp_conversation

Headers

Header Value
content-type application/json
api_access_token API access key

Body parameters

Parameter Required Description
inbox_id Yes ID of the inbox the message will be sent through
phone_number Yes Recipient's number in E.164 format
template_name Yes Exact name of the approved template
labels No Array of strings with tags to apply to the created conversation — see Applying tags (labels) below
header_attachment No Attachment URL, if the template supports media in the header
button_param_# No Button variables — replace # with the index (0 to N)
Template variables Yes, if the template has variables One field for each variable, with its exact name, at the root of the JSON (see below)

About dynamic variables

Each template variable becomes a field at the root of the JSON, alongside inbox_id, phone_number and template_name, with the variable's exact name:

  • Template with named variables, such as Hi {{customer}}, your {{amount}} invoice is due tomorrow: send the fields "customer" and "amount".

  • Template with numbered variables, such as Hi {{1}}, your {{2}} invoice is due tomorrow: send the fields "1" and "2".

If any variable is missing, the API rejects the request with the error missing params. Fields that do not match any variable are ignored. Variable names with dots or accents (such as {{contact.name}} or {{horário}}) are not accepted by Meta as variables.

Request example

curl --location 'https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/conversations/create_proactive_whatsapp_conversation' \
  --header 'content-type: application/json' \
  --header 'api_access_token: ACCESS_TOKEN' \
  --data '{
    "inbox_id": "INBOX_ID",
    "phone_number": "+5511999998888",
    "template_name": "payment_reminder",
    "labels": ["campaign-x", "vip"],
    "header_attachment": "ATTACHMENT_URL",
    "button_param_0": "BUTTON PARAMETER",
    "button_param_1": "ANOTHER BUTTON PARAMETER",
    "customer": "John",
    "amount": "$120.00"
  }'

Where to find the parameters

  • account_id — in the account's admin panel

  • inbox_id — ID of the configured inbox (https://cloudchat.cloudhumans.com/app/accounts/{account_id}/settings/inboxes/{inbox_id})

  • api_access_token — generate it in the API settings panel

  • Dynamic variables — check the template configuration in the admin panel. These parameters go at the root of the payload.

Make sure the phone number is in E.164 format, including the country code.

Applying tags (labels) to the created conversation

The optional labels parameter takes an array of strings with the titles of the tags to apply to the conversation created by the dispatch — no second call to the labels API needed.

"labels": ["campaign-x", "vip"]

Behavior:

  • Titles are normalized: surrounding whitespace is trimmed, they are converted to lowercase, and duplicates are removed.

  • Tags are appended to the conversation (they never replace existing tags) — on inboxes with single conversation enabled, tags from previous dispatches and tags applied by agents are preserved.

  • If the tag does not exist in the account yet, it is created automatically (and starts showing up in the dashboard filters) — as long as the token belongs to an administrator or CX Engineer. With an agent (non-admin) token, only tags that already exist in the account are applied; new titles are silently ignored.

  • Omitting the parameter (or sending an empty array) keeps the previous behavior — no tags are applied.

Rate limit

This endpoint accepts at most 200 requests per minute.

Above this limit, the API responds with HTTP 429 and the request is not processed (the message is not sent). The response includes the following headers:

Header Description
Retry-After Seconds until the window allows new requests
X-RateLimit-Limit Request limit for the window (200)
X-RateLimit-Remaining Remaining requests in the current window

Example response when the limit is exceeded:

{
  "error": "Rate limit exceeded. Retry later.",
  "retry_after": 42
}

If your integration sends messages in batches, handle the 429 response by resending the request after the time indicated in Retry-After. Without this handling, sends that exceed the limit will be lost.

Notes