WhatsApp API reference for developers: send endpoints, fields, error codes and limits
The ArabyBot WhatsApp send API reference: the five endpoints, the fields for sending a template and text, the message statuses, every refusal code with its HTTP status and what to do, and the request and queue limits.
On this page 9
The short answer
The ArabyBot WhatsApp send API is five endpoints under https://app.arabybot.com/api/v1, with a key in the Authorization header: check the key, list the approved templates, send a template, send free text inside the 24-hour window, and ask for a message's status. It takes 600 requests a minute per key, whatever exceeds the number's pace at WhatsApp waits in a queue and is not lost, and the reference field prevents sending twice.
Also asked as: «توثيق واتساب api» · «ارسال رسالة واتساب عن طريق api» · «واتساب api للمطورين» · «whatsapp api documentation» · «whatsapp send message api» · «whatsapp api error codes» · «whatsapp api rate limit»
The address and authentication
| Item | Value |
|---|---|
| Base address | https://app.arabybot.com/api/v1 |
| The key | From «Developer tools» in the dashboard; starts with abk_ and is shown once |
| The header | Authorization: Bearer abk_… or X-Api-Key: abk_… |
| Request body | JSON; a plain form post is accepted for systems that cannot send JSON |
| The answer | Always JSON, with success, and on a refusal an error_code and a message in Arabic and English |
The call goes from your server to ours. Never put the key in a page a visitor opens or in a mobile app: whoever holds it sends from your number.
The five endpoints
| Call | What it does | What it returns |
|---|---|---|
GET /me | Checks the key works | The key's name and the WhatsApp numbers it sends from, and which is the default |
GET /templates | Lists the approved templates | Each template's name, language, category and text, and a ready request body to send it in example |
POST /messages/template | Sends an approved template to one number | id, message_id, status |
POST /messages/text | Sends free text inside the 24-hour window | id, message_id, status |
GET /messages/{id} | Asks where the message is | The status, and the reason if it failed |
Sending a template: the fields
| Field | Required? | Value |
|---|---|---|
to | Yes | The recipient's number with the country code, e.g. 966501234567 |
template | Yes | The template name as in GET /templates |
language | No | The template's language when one name exists in several, e.g. ar |
variables | If the template has variables | A list in order ["Ahmed","1042"], or by number {"1":"Ahmed"}, or by name for templates with named variables |
header | If the template's header takes a value | Text, or a link to an image, video or file, or {"link":"…","filename":"…"} |
buttons | If a button needs a value | A list with each button's value in order, such as the link's tail or a coupon code |
from | No | The number to send from when your account has more than one |
reference | No, but recommended | A reference from your system, up to a hundred characters; it prevents sending twice |
POST https://app.arabybot.com/api/v1/messages/template
Authorization: Bearer abk_…
Content-Type: application/json
{
"to": "966501234567",
"template": "order_shipped",
"language": "ar",
"variables": ["Ahmed", "1042"],
"header": "https://example.com/invoice-1042.pdf",
"buttons": ["1042"],
"reference": "order-1042-shipped"
}
200
{ "success": true, "id": 512, "message_id": "wamid.…", "status": "accepted", "to": "966501234567" } Before the request reaches Meta we check the values against the approved template itself: a missing variable, the picture for a template whose header is a picture, a value containing a line break. All of that is refused once with BAD_VALUES and a problems list, rather than Meta refusing it for every message.
Sending free text
POST /messages/text takes to and text up to 4,096 characters, with from and reference optional. It suits answering a customer who wrote to you within the last 24 hours — a notice from your system that their order is ready after they asked about it, say. Outside the window Meta refuses it and the answer carries META_REFUSED.
The message status
| Status | Meaning |
|---|---|
queued | Waiting its turn in your number's queue; it goes out by itself |
accepted | WhatsApp accepted it |
sent | It left for the customer's phone |
delivered | It arrived |
read | The customer read it |
failed | It failed; error holds Meta's code and the reason |
GET https://app.arabybot.com/api/v1/messages/512
Authorization: Bearer abk_…
200
{ "success": true, "id": 512, "message_id": "wamid.…", "to": "966501234567",
"status": "delivered", "reference": "order-1042-shipped",
"created_at": "2026-11-15 18:04:10", "updated_at": "2026-11-15 18:04:13" }
# a failed message carries the reason
{ "success": true, "id": 513, "status": "failed",
"error": { "meta_code": "131026", "message": "…", "meta_message": "…" } } A message is asked about by our id or by Meta's message_id. API messages show in the live chat inside the customer's conversation with the rest of their messages, so your team sees them.
The refusal codes and what to do with each
409
{ "success": false, "error_code": "TEMPLATE_NOT_APPROVED",
"message": "…", "message_en": "Template \"order_shipped\" is still in Meta's review — it can be sent once approved.",
"template_status": "PENDING" } | Code | HTTP | What it means and what to do |
|---|---|---|
NO_KEY · INVALID_KEY | 401 | The key is missing, wrong or revoked. Make one under «Developer tools». |
SUBSCRIPTION_EXPIRED · MONTHLY_LIMIT | 402 | The subscription has ended, or the account reached its plan's monthly sending limit. |
NOT_IN_PLAN · API_OFF | 403 | The plan does not include «Developer tools», or the API is not available for the account right now. |
NO_NUMBER | 409 | No WhatsApp number is connected to the account, or the number in from is not one of its numbers. |
NO_TEMPLATE · NO_TEXT · BAD_PHONE · TEXT_TOO_LONG | 422 | A missing field, a number without its country code, or text longer than 4,096 characters. Fix the request. |
TEMPLATE_NOT_FOUND | 404 | No template with that name and language on the number. The names are in GET /templates. |
TEMPLATE_NOT_APPROVED | 409 | The template is in review, rejected or paused; the state is in template_status. |
BAD_VALUES | 422 | Values that do not fit the template; the detail is in problems. |
OPTED_OUT | 409 | The customer turned off marketing messages in WhatsApp, so no marketing template reaches them. Do not retry. |
META_REFUSED | 422 | WhatsApp refused the message; its code is in meta_code and its text in meta_message. |
TRY_AGAIN | 503 | WhatsApp is busy or the message could not be recorded for a moment. Repeat the same request with the same reference after a minute. |
UNCERTAIN | 202 | WhatsApp stopped answering after the send and the message may have arrived. Ask with GET /messages/{id} before you repeat. |
NOT_FOUND | 404 | No message with that id on the account. |
BAD_JSON · METHOD · NO_SUCH_ENDPOINT | 400 · 405 · 404 | A body that is not valid JSON, an address that takes POST, or an address that does not exist. |
SERVER | 500 | A fault on our side. Try again, and tell support if it repeats. |
Meta's WhatsApp API error codes and what each means
The limits
| The limit | The rule |
|---|---|
| Requests | 600 requests a minute per key; beyond that the answer is 429 with a Retry-After header |
| The number's pace | A number's messages leave at the pace WhatsApp accepts; the excess waits in the queue as queued |
| WhatsApp refusing for throughput | We send it again automatically under the first message id |
| Free text | 4,096 characters, and inside the 24-hour window |
| The reference | Up to a hundred characters, unique across the account |
Meta's own limits on your number — how many people you may start conversations with in a day, and the quality rating — stay as they are behind this API. The quality rating and sending limits
Plans and languages
The API is on the WhatsApp Pro, WhatsApp Premium, Complete Plan and Ultimate Plan plans, and Meta's fees are on your own WhatsApp Business account with no markup from us. The «Developer tools» page has a builder that writes the request for you in four forms. And here is a full walkthrough in each language:
- Sending a WhatsApp message with PHP and Laravel
- Sending a WhatsApp message with Python
- Sending a WhatsApp message from Node.js
- The WhatsApp OTP API
- Everything developers have in ArabyBot: sending, webhooks and agent tools
Frequently asked questions
Where do I get the send API key?
From the «Developer tools» page in the ArabyBot dashboard. The key starts with abk_ and is shown once when it is made, because we keep only its fingerprint. If it is lost, revoke it and make another.
Can I send free text to any number?
No. Free text is accepted within 24 hours of the customer's last message — Meta's rule, not ours. Outside that window you send an approved template.
What happens if my system sends hundreds of messages at once?
No message is lost. Whatever exceeds the pace WhatsApp accepts for your number goes into a queue and is answered with the status queued and the message id, then goes out by itself within moments. If WhatsApp refuses a message for throughput, we send it again under the same id.
How do I stop a message being sent twice?
Send a reference field with every request, holding a stable value from your system such as the order number plus the notice type. If the same reference reaches us again we send nothing and return the first message with "duplicate": true.
Does ArabyBot take a fee per message?
No. Meta's conversation fees are charged to your own WhatsApp Business account, as for any template you send, and we add nothing to them. The API is part of the plans that include «Developer tools».
Read next
Try the agent before you pay anything
The agent that will answer your customers is the one answering you now: ask it from the chat button here or on WhatsApp. Your account is free with no credit card, and the free trial on your own number or page is activated after you contact our team on customer-service WhatsApp.