Quickstart
This quickstart walks you through sending one message, reading the API response, and confirming delivery through a webhook callback.
Before you start
Make sure you have all of the following:
- Hosts, credentials, and IP access provisioned by Operations. Requests from IPs that aren't allowlisted are rejected. See General information.
- An assigned business sender and WABA (WhatsApp Business Account), including the sender's phone number ID.
- A controlled test recipient, meaning a WhatsApp number you own that has opted in to receive messages from your business.
- An approved template, or an open service window with the test recipient (see below).
- A registered webhook that can receive status callbacks. Without it, you can't confirm delivery. See Webhook.
Choose the message type
Which message you can send depends on whether the customer has messaged you recently:
- The customer messaged or called you within the last 24 hours (the service window is open): you can send a free-form message (service message) such as text, media, or interactive content. See Non-template messages.
- Otherwise: you must send an approved template. This includes the first message to a new customer. See Template messages and Create template.
If you aren't sure whether the window is open, send a template. Templates are valid both inside and outside the window. A free-form message sent outside the window fails with error 470.
Step 1: Send the message
Every message is sent with POST /v1/messaging and the messaging token (how to generate it). This example sends an approved template:
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": "template","template":{"language": "es","name": "body_text","components":[{"type":"body","parameters":[{"type":"text","text":"123456"}]}]}}'
If the service window is open, you can send free-form text instead by replacing the type and template fields with "type": "text" and a text field:
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": "~Strikethrough text~ \n _Italic text_ \n *Bold text* \n Emojis 😋"}'
Step 2: Read the response
A successful request returns HTTP 200 with a message ID:
[{"id": "gBGHUhVUByKUHwIJCSIVo3YWvs8i"}]
Save the id: it's the only way to match the status callbacks of this message.
HTTP 200 means the platform accepted the request, not that the message was delivered. Delivery is confirmed only by the delivered status callback (step 3). Errors returned at this point (400, 401, 500) are described in Response.
Step 3: Match the status callback
Your webhook receives status callbacks carrying the same message ID. The status moves through sent → delivered → read, or ends in failed. Callbacks can arrive out of order, so match them by id, not by arrival time.
All fields are described in Status notifications.
sent
{"statuses": [{"id": "gBGHUhVUByKUHwIJCSIVo3YWvs8i","status": "sent","timestamp": "1693419170","recipient_id": "5215500000002","conversation":{"id": "05b0852529d1652f2ccf3cde096f2150","origin":{"type": "utility"}},"pricing":{"billable": true,"pricing_model": "CBP","category": "utility"}}]}
delivered
{"statuses": [{"id": "gBGHUhVUByKUHwIJCSIVo3YWvs8i","status": "delivered","timestamp": "1693419173","recipient_id": "5215500000002","conversation":{"id": "05b0852529d1652f2ccf3cde096f2150","origin":{"type": "utility"}},"pricing":{"billable": true,"pricing_model": "CBP","category": "utility"}}]}
read
{"statuses": [{"id": "gBGHUhVUByKUHwIJCSIVo3YWvs8i","status": "read","timestamp": "1693419180","recipient_id": "5215500000002"}]}
failed
For example, a free-form message sent outside the service window:
{"statuses": [{"errors": [{"code": 470,"title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider."}],"id": "gBGHUhVUByKUHwIJCSIVo3YWvs8i","recipient_id": "5215500000002","status": "failed","timestamp": "1693419173"}]}
When the status is failed, look up errors[].code in Error codes.
