WhatsApp API (Beta)
Sending Messages

Sending Messages

Send WhatsApp template messages using approved templates. This endpoint delivers messages to recipients using your WhatsApp Business number.

Send Template Message

Send a template-based WhatsApp message to one or more recipients.

Endpoint

POST /v1/whatsapp/send

Request Body

{
  "destination": "0720000000",
  "template_id": "115XXXXXXXXXX295",
  "phone_number_id": "46646XXXXXXX268",
  "component_list": {
    "components": [
      {
        "component_type": "BODY",
        "fields": [
          { "name": "1", "value": "Peter Pan" },
          { "name": "2", "value": "KES 4000" },
          { "name": "3", "value": "2025-06-20" }
        ]
      }
    ]
  }
}

Request Fields

FieldTypeRequiredDescription
destinationstringYesRecipient's phone number (local or international format)
template_idstringYesTemplate ID from the templates endpoint
phone_number_idstringYesYour WhatsApp Number phone_number_id. Do not confuse with the id field
component_listobjectYesTemplate variable values

Component List Structure

The component_list contains template variables:

{
  "components": [
    {
      "component_type": "BODY",
      "fields": [
        { "name": "1", "value": "First variable value" },
        { "name": "2", "value": "Second variable value" }
      ]
    }
  ]
}
  • component_type: It can be "HEADER", "BODY", or "BUTTONS"
  • fields: Array of variable replacements
  • name: Variable number as string ("1", "2", "3", etc.)
  • value: Actual value to replace the placeholder

Response

{
  "recipients": [
    {
      "id": "bae1d2dd-f27d-4d2b-96d9-e907e12b0ba2",
      "cost": 0.8,
      "number": "+254725089232",
      "status": "Success"
    }
  ]
}

Response Fields

FieldTypeDescription
idstringUnique message ID for tracking
costnumberMessage cost in your account currency
numberstringRecipient number in international format
statusstringDelivery status (Success, Failed, etc.)

Complete Examples

Authentication Code Example

Using the authentication template from the templates section:

Template:

*{{1}}* is your verification code. For your security, do not share this code.

Request:

{
  "destination": "254720000000",
  "template_id": "1250589476699956",
  "phone_number_id": "46646XXXXXXX268",
  "component_list": {
    "components": [
      {
        "component_type": "BODY",
        "fields": [{ "name": "1", "value": "123456" }]
      }
    ]
  }
}

Sent Message:

*123456* is your verification code. For your security, do not share this code.

Order Confirmation Example

Template:

Hi {{1}}, your order #{{2}} worth {{3}} is confirmed for delivery on {{4}}.

Request:

{
  "destination": "254720000000",
  "template_id": "template_order_confirmation_id",
  "phone_number_id": "46646XXXXXXX268",
  "component_list": {
    "components": [
      {
        "component_type": "BODY",
        "fields": [
          { "name": "1", "value": "John Doe" },
          { "name": "2", "value": "ORD-2025-001" },
          { "name": "3", "value": "$99.99" },
          { "name": "4", "value": "June 28, 2025" }
        ]
      }
    ]
  }
}

Code Examples

curl -X POST https://whatsapp.smsleopard.com/v1/whatsapp/send \
  -H "Authorization: Basic $(echo -n 'api_key:api_secret' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "254720000000",
    "template_id": "1250589476699956",
    "phone_number_id": "46646XXXXXXX268",
    "component_list": {
      "components": [
        {
          "component_type": "BODY",
          "fields": [
            {
              "name": "1",
              "value": "123456"
            }
          ]
        }
      ]
    }
  }'

Phone Number Formats

The API accepts phone numbers in International format:

  • International format: +254720000000
  • Without plus: 254720000000

Error Response Shape

The API returns a consistent error response shape for all errors:

{
  "error_code": string, // e.g., "bad_request", "invalid_format", "unauthorized"
  "error_message": string, // actual error message describing the issue
  "status_code": integer // e.g., 400, 401, 404, 500
}

Best Practices

  1. Validate phone numbers before sending
  2. Check template variables - ensure all required variables are provided
  3. Store message IDs for tracking
  4. Monitor delivery status using the returned message ID

Message Tracking

Each sent message returns a unique id that you can use for:

  • Tracking delivery status
  • Customer support queries
  • Message analytics
  • Debugging failed messages

Next Steps

TemplatesExamples