The OTP API

Send a verification code on WhatsApp through the API: the address, the fields and the response

The reference for the send-code address of ArabyBot's OTP API: the request fields, an example and response, every refusal with its code, and which number the code leaves from and how it is billed.

5 min read Updated 16 November 2026 ArabyBot team
The ArabyBot teamOfficial Meta partner · written from our own platform data
On this page 8
  1. The address and authentication
  2. The fields
  3. An example request
  4. The response
  5. What we measured on this API
  6. The refusals
  7. The limits
  8. Frequently asked questions

The short answer

With a POST request to the send address of the OTP API, carrying the phone number in international format, with the app's public key in the header. The system generates a numeric code and sends it on WhatsApp in a Meta-approved authentication template, and the response returns the request id and how long the code stays valid. Keep the request id: you verify against it later, never against the phone number.

Also asked as: «ابعت كود تحقق على الواتساب من موقعي ازاي» · «otp واتساب api» · «ارسال رمز التحقق واتساب برمجيا» · «send otp via whatsapp api» · «whatsapp verification code api»

The address and authentication

POST https://app.arabybot.com/wa_otp_api/send

Send the OTP app's public key in the header X-Public-Key: ab_otp_…. You create the app in the OTP section of the dashboard, which gives you the public key and a secret shown once. If you switched request signing on for the app, add the header X-Signature: sha256=…, an HMAC-SHA256 of the raw request body keyed with the app secret.

The fields

  • phone (required) The number in international format, digits only or with a leading +, e.g. 966501234567. Egyptian local numbers starting with 01 are also accepted.
  • lang (optional) The template language, e.g. ar or en. Defaults to the app's language.
  • length (optional) The code length. Never shorter than the app's own setting.
  • expiry_seconds (optional) How long the code stays valid, in seconds. Defaults to the app's setting.
  • metadata (optional) Your own keys and values, stored with the request.

An example request

cURL

curl -X POST https://app.arabybot.com/wa_otp_api/send \
  -H "X-Public-Key: ab_otp_YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "966501234567", "lang": "ar", "length": 6, "expiry_seconds": 300,
        "metadata": { "user_id": "u_1042" } }'

PHP

$ch = curl_init('https://app.arabybot.com/wa_otp_api/send');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['X-Public-Key: ab_otp_YOUR_PUBLIC_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'phone' => '966501234567',
        'lang' => 'ar',
        'length' => 6,
        'expiry_seconds' => 300,
        'metadata' => [
            'user_id' => 'u_1042',
        ],
    ]),
]);
$answer = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

Python

import requests

r = requests.post(
    'https://app.arabybot.com/wa_otp_api/send',
    headers={
        "X-Public-Key": "ab_otp_YOUR_PUBLIC_KEY",
    },
    json={
        "phone": "966501234567",
        "lang": "ar",
        "length": 6,
        "expiry_seconds": 300,
        "metadata": {
            "user_id": "u_1042",
        },
    },
    timeout=30,
)
print(r.status_code, r.json())

Node.js

// Node.js 18+
const r = await fetch('https://app.arabybot.com/wa_otp_api/send', {
  method: 'POST',
  headers: {"X-Public-Key": "ab_otp_YOUR_PUBLIC_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({
    "phone": "966501234567",
    "lang": "ar",
    "length": 6,
    "expiry_seconds": 300,
    "metadata": {
      "user_id": "u_1042"
    }
  }),
});
console.log(r.status, await r.json());

The response

200
{ "success": true, "request_id": "3f6c2a9e-41b7-4c0d-9a51-7e2b8d4f1c60",
  "expires_in": 300, "expires_at": "2026-11-16 18:09:10" }
  • request_id is the request's identifier; with it you verify the code, resend it and ask for its status.
  • expires_in is in seconds, and expires_at is in server time.
ArabyBot's API as it runs today, read from the system itselfmeasured 16 November 2026

What we measured on this API

17 secondsmedian from sending the code to typing it correctly
98%of those who verified typed the code right on the first try
1 secondmedian response time of the send address
ArabyBot's measurement on the OTP API: 169 verified codes between 9 and 16 Nov 2026, and 4,159 successful sends since 25 Aug 2026measured 16 November 2026

Half of the users typed the code within 13 to 25 seconds, and nine in ten within 46 seconds; so a validity of a few minutes is enough. Of every hundred codes sent, about 75 were verified. The limit of this measurement is that one app carries 91% of the sends; these are these apps' figures, not a general average.

The refusals

Every refusal comes back as JSON with "success": false, an error_code and a message, plus retry_after in seconds when the cause is a rate limit:

  • 401 missing_key / invalid_key: The public key is missing or wrong.
  • 401 missing_signature / bad_signature: The app requires request signing and the signature is missing or does not match.
  • 402 package_expired / subscription_expired / module_not_entitled: The subscription has ended or the plan does not include OTP.
  • 402 quota_exceeded / insufficient_balance: The quota is used up, or the wallet balance is not enough when sending from the shared number.
  • 403 origin_blocked / ip_blocked / pool_access_denied: The request's origin or address is not allowed in the app's settings, or the shared number is not available to the account.
  • 422 missing_phone / invalid_phone: The number is missing or not valid.
  • 429 rate_limit_phone / cooldown / rate_limit_app / rate_limit_app_day: A rate limit for the phone or the app; wait retry_after seconds.
  • 429 pool_daily_cap / pool_min_gap: The shared number's daily cap or the gap between two of its messages.
  • 502 wa_send_failed: WhatsApp refused the send; a shared-number charge is refunded.
  • 503 pool_unavailable / pool_disabled: The shared number is not available right now.

The limits

Every code is a paid WhatsApp message at Meta's authentication rate for the recipient's country. For protection there are limits on requests per phone number and per app, per minute and per day; passing them returns status 429 with retry_after in seconds.

The OTP API guide · All APIs for developers

Frequently asked questions

1

Which number does the verification code leave from?

From your own WhatsApp number if you connected one, or from ArabyBot's shared sender number with the message charged to your wallet. Either way the code goes out in a Meta-approved authentication template.

2

Do I verify the code against the phone number?

No. You verify against the request_id returned when you sent it, never against the phone number. Keep it in the user's session on your server.

The ArabyBot teamOfficial Meta business partner in the Middle East 264 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 16 November 2026.

Share this guide

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.

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.