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.
On this page 8
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.aroren. 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_idis the request's identifier; with it you verify the code, resend it and ask for its status.expires_inis in seconds, andexpires_atis in server time.
What we measured on this API
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; waitretry_afterseconds. - 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
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.
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.
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.