WhatsApp in the XBASE API
Send templates and messages, react, mark as read and open Flows on the WhatsApp numbers connected through Meta's official API.
Updated on
With the Send WhatsApp messages scope (whatsapp:send), the API uses the workspace WhatsApp numbers to send templates and messages, react, mark messages as read and open Flows. Everything sent through the API goes into the contact's conversation, in the Chatcenter.
Which numbers send through the API
The WhatsApp numbers connected through Meta's official API (WhatsApp Cloud API): the ones listed in WhatsApp API → Numbers, including the phone's WhatsApp Business connected in coexistence. Each number has an id, which goes in numberId when sending (list the numbers).
Endpoints
| Method and route | What it does |
|---|---|
GET /whatsapp/numbers | Lists the workspace numbers |
GET /whatsapp/templates | Lists the templates |
POST /whatsapp/templates | Sends an approved template |
POST /whatsapp/messages | Sends a message: text, media, location, buttons, list or Flow |
POST /whatsapp/messages/{messageId}/reaction | Reacts to a message |
POST /whatsapp/messages/{messageId}/read | Marks a received message as read |
GET /whatsapp/flows | Lists the published Flows of a number |
All of them use the whatsapp:send scope and the base URL https://api.xbase.app/api/external/v1.
24-hour window
WhatsApp only lets a business send a free-form message (text, media, location, buttons, list and Flow) up to 24 hours after the contact's last message to that number. Outside this window, only an approved template goes out, and it is how you restart the conversation.
- If the contact never wrote to the number, or wrote more than 24 hours ago,
POST /whatsapp/messagesreturns 422WINDOW_CLOSEDand nothing is sent. - A template goes out at any time, inside or outside the window.
- The window opens again when the contact replies.
How the conversation is recorded
- Every send shows up in the contact's conversation with that number, in the Chatcenter, as if it had been sent on screen. The sender is the API key name.
- A template creates the contact and the conversation if they do not exist yet. A free-form message uses the conversation that already exists.
- Every send response has the
messageId(the message id at Meta, starting withwamid.), thethreadId(the conversation) and thedialogId(the message in the conversation). ThemessageIdis the same as in the workspace webhooks events, and it is what you use to react and to mark as read. - The API does not prevent duplicate sends: repeating the call sends again.