API - Send Proactive Message via WhatsApp

This article is the quick reference for the WhatsApp endpoint. The full guide, including Web Widget and tags, is at Trigger a proactive message via API (WhatsApp and Web Widget).

Description

This endpoint allows creating a proactive conversation through WhatsApp using a pre-configured template. The template parameters are dynamic and may vary depending on the template configuration used.

Endpoint

URL:

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

Headers:

• content-type: application/json

• api_access_token: Your API access key.

Parameters

Path Parameter

account_id

• Type: String

• Required: Yes

• Description: Account ID in the system.

Body Parameters

1. inbox_id

   • Type: String

   • Required: Yes

   • Description: ID of the inbox where the message will be sent.

2. phone_number

   • Type: String

   • Required: Yes

   • Description: Recipient's phone number, including country code.

3. template_name

   • Type: String

   • Required: Yes

   • Description: Name of the template configured in the system.

4. Dynamic Template Parameters

   • Type: Various

   • Required: Yes, if the template has variables (all of them are required)

   • Description: One field for each template variable, with its exact name (see below).

5. labels

   • Type: Array of strings

   • Required: No

   • Description: Titles of the tags to apply to the created conversation. Details in the full guide.

About Dynamic Parameters

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": "+15551234567",
  "template_name": "payment_reminder",
  "customer": "John",
  "amount": "$120.00"
}'

Notes

1. account_id: The account_id can be found in the account's admin panel.

2. inbox_id: The inbox_id corresponds to the ID of the configured inbox for receiving messages.

3. api_access_token: Generate the token in the API configuration panel.

4. Dynamic Template Parameters: Check your template configuration in the admin panel to identify available and mandatory variables. These parameters should be sent directly at the root of the payload.

Important: Ensure that the phone number is in international format (E.164), including the country code.

Rate limit

This endpoint accepts up to 200 requests per minute per API key. Above that, the response is 429 with the Retry-After header (seconds until you can try again). Wait that long before resending and, for large batches, spread the sends across minutes. A request that received 429 was not processed, so resending it does not duplicate the message. The response body and the other headers are in the rate limit section of How to send a proactive WhatsApp message via API.

Campaigns via API

To send to a list of contacts, use campaign creation on the public API (api.cloudhumans.com), also available through the Cloud Humans MCP:

• The audience is defined by tag: the campaign goes to the contacts that have the tag.

• Before creating, the API asks you to confirm how many contacts will receive it.

• Sending goes through the campaign scheduler, within a few minutes or at the scheduled time.

• Authentication is by user login (Bearer token), not by this endpoint's api_access_token.

Reference: Create a campaign. The endpoint on this page remains the way to send one by one; to send in volume through it, respect the limit of 200 requests per minute.