Messages

Integration summary
Endpoint: POST https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging
Token: messaging token, in the Authorization: Bearer {{wa-msg-api-token}} header (how to generate it)
Common fields: from, to (phone number or BSUID) and type (details)
Activation field: category with the value "utility"
Response: the same for every message (see response)

The messages you can send with Direct Send, with their fields and examples. All are sent with POST /v1/messaging adding the category field.

General structure

Fields in addition to the common fields:

Name	Description	Type	Requirements
text	Message text.	String	Required. Maximum length: 1,024 characters.
category	Direct Send activation category. Valid value: `utility`. Sending `service` is considered outside Direct Send and follows the existing send behavior.	String	Required to use Direct Send API. If omitted, it is treated as a normal message send.
ttl_seconds	Lets you configure the TTL; it is added below the `category` field. For `utility`: 30 days by default. Minimum 30 seconds. Maximum 43,200 seconds (12 hours).	String	Optional.
direct_send_config	Object to attribute the messages to a template with an explicit name.	Object	Optional.

Text message

Sends a Direct Send text message. The type field must be "text" and category must be "utility".

Example

HTTP request

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5215500000001",
    "to": "5215500000002",
    "type": "text",
    "text": "Your order is on its way.",
    "category": "utility"
}'

Template attribution

By default, Direct Send automatically matches the message against existing templates or creates a new one with a name generated by Meta. If you need every message in the same flow to always be attributed to the same template, you can set an explicit name in the direct_send_config object.

Body

Name	Description	Type	Requirements
template_name	Explicit name of the template to create or reuse. Unique per WABA. Only valid together with `category: "utility"`.	String	Optional. Lowercase letters, numbers and underscore only (`^[a-z0-9_]{1,512}$`).

Example

HTTP request

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5215500000001",
    "to": "5215500000002",
    "type": "text",
    "text": "Your order TC01-9988 is on its way.",
    "category": "utility",
    "direct_send_config": { "template_name": "order_on_its_way_v1" }
}'

Combined buttons (CTA URL + reply)

A single interactive message can combine URL buttons (cta_url) and reply buttons (reply), defined in the buttons array of the replyButtons object. The type field must be "interactive" and category must be "utility". See Reply buttons for the full object.

Up to 10 buttons in total.
Maximum 2 buttons of type cta_url.
The cta_url buttons must come before the reply buttons in the array.

Example

Body

{
    "from": "5215500000001",
    "to": "5215500000002",
    "type": "interactive",
    "category": "utility",
    "direct_send_config": {
        "template_name": "order_update_btns"
    },
    "replyButtons": {
        "body": "Choose an option",
        "buttons": [
            { "type": "cta_url", "title": "Visit site", "url": "https://www.conceptomovil.com" },
            { "type": "reply", "id": "btn_1", "title": "Option 1" },
            { "type": "reply", "id": "btn_2", "title": "Option 2" }
        ]
    }
}

Voice call button

The WhatsApp voice call button ("Call on WhatsApp") lets a user tap to start a WhatsApp voice call to the business phone number. It is sent as a free-form interactive message with the top-level category: "utility" label and a single call button, defined in the voice_call object. See Call button (voice call) for the full object.

Note: to use this feature the number must have WhatsApp Calling enabled in WhatsApp Manager; otherwise, Meta returns error 138000 ("Calling API not enabled") even if the JSON is correct.

Example

Body

{
    "from": "5215500000001",
    "to": "5215500000002",
    "type": "interactive",
    "category": "utility",
    "direct_send_config": {
        "template_name": "order_confirmation_call"
    },
    "voice_call": {
        "body": "We will call you to confirm your order",
        "action": {
            "parameters": {
                "display_text": "Call now",
                "ttl_minutes": 60
            }
        }
    }
}

Account without Direct Send enabled

If the WABA does not have Direct Send enabled, the message fails and the following notification is sent to the webhook:

{
  "statuses": [{
    "id": "",
    "recipient_id": "5512345678",
    "status": "failed",
    "timestamp": "...",
    "errors": [{
      "code": 100,
      "title": "Internal error, please retry. If the problem persist, please contact support",
      "details": "(#100) Invalid parameter.Parameter Invalid: The 'category' value requires Direct Send, which isn't enabled for this account. Use an approved message template instead."
    }]
  }]
}

The Direct Send-specific error codes (1148 to 1151) and the rest of the API codes are in Error codes.