API documentation

Authentication

Send your personal API token in the HTTP Authorization header. Tokens can be created after signing in under account API tokens.

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
Content-Type: application/json

The legacy token request field is supported for compatibility, but Bearer authentication is recommended because it avoids credentials appearing in URLs and application logs.

Errors and limits

Public API routes are limited to 60 requests per minute. Messaging requests can also return 402 when a messaging subscription is required, 422 for consent or customer-service-window restrictions, and 429 for plan limits.

{
  "status": "error",
  "message": "Contact has not opted in or has opted out of WhatsApp messaging."
}

Outbound order webhooks

Configure an HTTPS order webhook URL and signing secret in the authenticated Integrations area. Events contain event, order, customer, and items. Verify the hexadecimal X-Wpbox-Signature header using HMAC-SHA256 over the raw request body.

<?php
$expected = hash_hmac('sha256', $rawRequestBody, $webhookSecret);
$valid = hash_equals($expected, $_SERVER['HTTP_X_WPBOX_SIGNATURE'] ?? '');

Messages

curl -X POST 'https://whatsapbox.com/api/wpbox/sendmessage' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{"phone":"+254700000000","message":"Hello from WhatsAppBox"}'

{
    "status": "success",
    "message_id": 123,
    "message_wamid": "wamid.example"
}

curl -X POST 'https://whatsapbox.com/api/wpbox/sendtemplatemessage' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{"phone":"+254700000000","template_name":"order_update","template_language":"en","components":[]}'

{
    "status": "success",
    "message_id": 124,
    "message_wamid": "wamid.example"
}

Commerce

curl -X POST 'https://whatsapbox.com/api/wpbox/sendcatalogproduct' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{"phone":"+254700000000","retailer_id":"SKU-100","body":"View this product","footer":"Reply for help"}'

{
    "status": "success",
    "message_id": 125,
    "message_wamid": "wamid.example"
}

curl -X POST 'https://whatsapbox.com/api/wpbox/sendcatalogproducts' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{"phone":"+254700000000","retailer_ids":["SKU-100","SKU-101"],"body":"Choose a product"}'

{
    "status": "success",
    "message_id": 126,
    "message_wamid": "wamid.example"
}

curl -X GET 'https://whatsapbox.com/api/wpbox/getCatalogProducts' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

{
    "status": "success",
    "data": []
}

curl -X POST 'https://whatsapbox.com/api/wpbox/createOrder' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{"phone":"+254700000000","retailer_ids":["SKU-100"],"delivery_address":"Nairobi","notes":"Call on arrival","send_confirmation":false}'

{
    "status": "success",
    "order": {
        "id": 88,
        "order_number": "ORD-EXAMPLE"
    }
}

curl -X GET 'https://whatsapbox.com/api/wpbox/getOrders?status=pending' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

{
    "status": "success",
    "data": []
}

Resources

curl -X GET 'https://whatsapbox.com/api/wpbox/getTemplates' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

{
    "status": "success",
    "templates": []
}

curl -X GET 'https://whatsapbox.com/api/wpbox/getGroups?showContacts=yes' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

{
    "status": "success",
    "groups": []
}

curl -X GET 'https://whatsapbox.com/api/wpbox/getContacts' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

{
    "status": "success",
    "contacts": []
}

Contacts

curl -X POST 'https://whatsapbox.com/api/wpbox/makeContact' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{"phone":"+254700000000","groups":[1],"custom":{"2":"Nairobi"}}'

{
    "status": "success",
    "contact": {
        "id": 42,
        "phone": "+254700000000"
    }
}