Integrations

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.

9 min read Updated 15 November 2026 ArabyBot team
The ArabyBot teamOfficial Meta partner · written from our own platform data
On this page 9
  1. The address and authentication
  2. The five endpoints
  3. Sending a template: the fields
  4. Sending free text
  5. The message status
  6. The refusal codes and what to do with each
  7. The limits
  8. Plans and languages
  9. Frequently asked questions

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

ItemValue
Base addresshttps://app.arabybot.com/api/v1
The keyFrom «Developer tools» in the dashboard; starts with abk_ and is shown once
The headerAuthorization: Bearer abk_… or X-Api-Key: abk_…
Request bodyJSON; a plain form post is accepted for systems that cannot send JSON
The answerAlways 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

CallWhat it doesWhat it returns
GET /meChecks the key worksThe key's name and the WhatsApp numbers it sends from, and which is the default
GET /templatesLists the approved templatesEach template's name, language, category and text, and a ready request body to send it in example
POST /messages/templateSends an approved template to one numberid, message_id, status
POST /messages/textSends free text inside the 24-hour windowid, message_id, status
GET /messages/{id}Asks where the message isThe status, and the reason if it failed

Sending a template: the fields

FieldRequired?Value
toYesThe recipient's number with the country code, e.g. 966501234567
templateYesThe template name as in GET /templates
languageNoThe template's language when one name exists in several, e.g. ar
variablesIf the template has variablesA list in order ["Ahmed","1042"], or by number {"1":"Ahmed"}, or by name for templates with named variables
headerIf the template's header takes a valueText, or a link to an image, video or file, or {"link":"…","filename":"…"}
buttonsIf a button needs a valueA list with each button's value in order, such as the link's tail or a coupon code
fromNoThe number to send from when your account has more than one
referenceNo, but recommendedA 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

StatusMeaning
queuedWaiting its turn in your number's queue; it goes out by itself
acceptedWhatsApp accepted it
sentIt left for the customer's phone
deliveredIt arrived
readThe customer read it
failedIt 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" }
CodeHTTPWhat it means and what to do
NO_KEY · INVALID_KEY401The key is missing, wrong or revoked. Make one under «Developer tools».
SUBSCRIPTION_EXPIRED · MONTHLY_LIMIT402The subscription has ended, or the account reached its plan's monthly sending limit.
NOT_IN_PLAN · API_OFF403The plan does not include «Developer tools», or the API is not available for the account right now.
NO_NUMBER409No 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_LONG422A missing field, a number without its country code, or text longer than 4,096 characters. Fix the request.
TEMPLATE_NOT_FOUND404No template with that name and language on the number. The names are in GET /templates.
TEMPLATE_NOT_APPROVED409The template is in review, rejected or paused; the state is in template_status.
BAD_VALUES422Values that do not fit the template; the detail is in problems.
OPTED_OUT409The customer turned off marketing messages in WhatsApp, so no marketing template reaches them. Do not retry.
META_REFUSED422WhatsApp refused the message; its code is in meta_code and its text in meta_message.
TRY_AGAIN503WhatsApp is busy or the message could not be recorded for a moment. Repeat the same request with the same reference after a minute.
UNCERTAIN202WhatsApp stopped answering after the send and the message may have arrived. Ask with GET /messages/{id} before you repeat.
NOT_FOUND404No message with that id on the account.
BAD_JSON · METHOD · NO_SUCH_ENDPOINT400 · 405 · 404A body that is not valid JSON, an address that takes POST, or an address that does not exist.
SERVER500A 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 limitThe rule
Requests600 requests a minute per key; beyond that the answer is 429 with a Retry-After header
The number's paceA number's messages leave at the pace WhatsApp accepts; the excess waits in the queue as queued
WhatsApp refusing for throughputWe send it again automatically under the first message id
Free text4,096 characters, and inside the 24-hour window
The referenceUp 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:

Frequently asked questions

1

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.

2

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.

3

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.

4

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.

5

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».

The ArabyBot teamOfficial Meta business partner in the Middle East 239 guides Figures from our platform All guides

How we write these guides Figures come from our platform and Meta's actual invoices, dated with their sample; we describe what works today, not what we plan, and say what we do not do and when someone else is the better choice. Reviewed by the ArabyBot team on 15 November 2026.

Share this guide
And you run all of it from your phoneEverything on this page is also run from the ArabyBot mobile app — replies, orders, campaigns and AI reports. Not a web dashboard only.

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.