L'API OTP WhatsApp pour les développeurs en 2026 — envoyer et vérifier un code, avec des exemples PHP, Laravel, Node.js et Python

Avant la première ligne de code : une application OTP et deux clés

1. Créez une application OTP dans le tableau de bord

   Depuis OTP dans le tableau de bord d'ArabyBot : le nom de l'application, le nom affiché dans le message, puis l'expéditeur — le numéro partagé prêt à l'emploi, ou un numéro WhatsApp connecté à votre compte. Vous fixez aussi la longueur du code, sa durée de validité et le nombre de tentatives de vérification autorisées.

2. Récupérez la clé publique et le secret

   La clé publique commence par ab_otp_ et voyage dans l'en-tête X-Public-Key à chaque appel. Le secret commence par sk_otp_ et n'est affiché qu'une fois à la création : gardez-le dans les variables d'environnement de votre serveur — c'est avec lui que vous signez les requêtes et que vous vérifiez notre signature sur les rappels.

3. Choisissez ce que vous verrouillez

   Trois réglages facultatifs sur l'application : la signature des requêtes (tout appel sans X-Signature valide est refusé), les domaines autorisés pour les appels du navigateur, et les adresses IP de vos serveurs. Activez le premier et le troisième si l'appel passe par votre serveur.

Cinq points d'accès — tout le contrat

Le téléphone est au format international, chiffres uniquement ou précédés d'un + : 966501234567. Chaque erreur revient sous une seule forme : {"success":false,"error_code":"…","message":"…"} : construisez donc votre logique sur error_code, pas sur le texte du message.

L'essai le plus rapide : curl

# 1) send the code
curl -X POST https://app.arabybot.com/wa_otp_api/send \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: ab_otp_…" \
  -d '{"phone":"966501234567","lang":"ar"}'

{"success":true,"request_id":"3f6c2a9e-41b7-4c0d-9a51-7e2b8d4f1c60",
 "expires_in":300,"expires_at":"2026-10-01 14:05:00"}

# 2) verify what the user typed
curl -X POST https://app.arabybot.com/wa_otp_api/verify \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: ab_otp_…" \
  -d '{"request_id":"3f6c2a9e-41b7-4c0d-9a51-7e2b8d4f1c60","code":"482913"}'

{"success":true,"request_id":"3f6c2a9e-…","phone":"966501234567",
 "verified_at":"2026-10-01 14:01:12"}

PHP — une seule fonction pour chaque appel

Le cURL intégré de PHP suffit, sans bibliothèque. Gardez le request_id dans la session de l'utilisateur côté serveur, pas dans la page.

<?php
// One helper for every call. Keys come from the environment, never from the page.
function arabybot_otp(string $action, array $body): array
{
    $raw     = json_encode($body);
    $headers = [
        'Content-Type: application/json',
        'X-Public-Key: ' . getenv('ARABYBOT_OTP_PUBLIC_KEY'),
    ];
    if ($secret = getenv('ARABYBOT_OTP_SECRET')) {   // only if request signing is on
        $headers[] = 'X-Signature: sha256=' . hash_hmac('sha256', $raw, $secret);
    }
    $ch = curl_init('https://app.arabybot.com/wa_otp_api/' . $action);
    curl_setopt_array($ch, [
        CURLOPT_POST => true, CURLOPT_POSTFIELDS => $raw, CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15,
    ]);
    $res = json_decode((string) curl_exec($ch), true);
    curl_close($ch);

    return is_array($res) ? $res : ['success' => false, 'error_code' => 'network'];
}

session_start();
$sent = arabybot_otp('send', ['phone' => '201001234567', 'lang' => 'ar']);
$_SESSION['otp_request'] = $sent['request_id'] ?? null;

// …later, when the user submits the code
$check = arabybot_otp('verify', ['request_id' => $_SESSION['otp_request'], 'code' => $_POST['code']]);
if (! empty($check['success'])) {
    // the number is verified
}

Laravel — via Http

Le client Http de Laravel écrit la requête en quelques lignes. Si vous activez la signature des requêtes, signez exactement les octets que vous envoyez : construisez le JSON vous-même et envoyez-le avec withBody, car ->post() réencode le tableau.

use Illuminate\Support\Facades\Http;

// config/services.php → 'arabybot' => ['otp_key' => env('ARABYBOT_OTP_PUBLIC_KEY')]
$otp = Http::withHeaders(['X-Public-Key' => config('services.arabybot.otp_key')])
    ->baseUrl('https://app.arabybot.com/wa_otp_api')
    ->timeout(15);

$sent = $otp->post('/send', ['phone' => $request->phone, 'lang' => 'ar'])->json();
session(['otp_request' => $sent['request_id'] ?? null]);

$check = $otp->post('/verify', [
    'request_id' => session('otp_request'),
    'code'       => $request->code,
])->json();

if ($check['success'] ?? false) {
    // verified
}

// With request signing on, sign the exact bytes you send:
// $raw = json_encode($body);
// Http::withHeaders([... 'X-Signature' => 'sha256='.hash_hmac('sha256', $raw, $secret)])
//     ->withBody($raw, 'application/json')->post('https://app.arabybot.com/wa_otp_api/send');

Node.js — fetch, sans bibliothèque

import crypto from 'node:crypto';

// Node 18+ (built-in fetch). Keys from the environment.
async function otp(action, body) {
  const raw = JSON.stringify(body);
  const headers = {
    'Content-Type': 'application/json',
    'X-Public-Key': process.env.ARABYBOT_OTP_PUBLIC_KEY,
  };
  if (process.env.ARABYBOT_OTP_SECRET) {            // only if request signing is on
    headers['X-Signature'] = 'sha256=' + crypto
      .createHmac('sha256', process.env.ARABYBOT_OTP_SECRET).update(raw).digest('hex');
  }
  const res = await fetch(`https://app.arabybot.com/wa_otp_api/${action}`,
    { method: 'POST', headers, body: raw });
  return res.json();
}

const sent  = await otp('send', { phone: '971501234567', lang: 'ar' });
const check = await otp('verify', { request_id: sent.request_id, code: '482913' });
console.log(check.success ? 'verified' : check.error_code);

Python — requests

import hashlib, hmac, json, os
import requests

def otp(action, body):
    raw = json.dumps(body)
    headers = {"Content-Type": "application/json",
               "X-Public-Key": os.environ["ARABYBOT_OTP_PUBLIC_KEY"]}
    secret = os.environ.get("ARABYBOT_OTP_SECRET")
    if secret:  # only if request signing is on
        headers["X-Signature"] = "sha256=" + hmac.new(
            secret.encode(), raw.encode(), hashlib.sha256).hexdigest()
    return requests.post(f"https://app.arabybot.com/wa_otp_api/{action}",
                         data=raw, headers=headers, timeout=15).json()

sent = otp("send", {"phone": "9647701234567", "lang": "ar"})
check = otp("verify", {"request_id": sent["request_id"], "code": "482913"})
print("verified" if check.get("success") else check.get("error_code"))

Erreurs et limites — et que faire pour chacune

Le rappel de vérification vers votre serveur

Si vous définissez une URL de rappel sur l'application, un événement otp.verified vous parvient dès qu'un code est vérifié, signé avec votre secret. Calculez le HMAC-SHA256 du corps tel que reçu et comparez-le à l'en-tête avant de lui faire confiance.

// The callback your server receives when a code is verified (if you set a callback URL)
POST https://your-site.example/otp-callback
X-ArabyBot-Event: otp.verified
X-ArabyBot-Signature: sha256=<HMAC-SHA256 of the raw body, keyed with your sk_otp_ secret>

{"event":"otp.verified","app_id":"12","request_id":"3f6c2a9e-…",
 "phone":"966501234567","verified_at":"2026-10-01T14:01:12+00:00"}

Ce que vous payez

Sur votre propre numéro, le code part sous forme de modèle d'authentification approuvé et Meta facture le tarif du pays du destinataire : 0,0036 $ vers un numéro égyptien et 0,0107 $ vers un numéro saoudien, mesuré sur 1 147 codes. Sur le numéro partagé, c'est un prix fixe par code prélevé sur votre portefeuille (0,0300 $), sans compte Meta. Le tableau pour chaque pays arabe se trouve dans le prix du code de vérification dans chaque pays arabe.

Questions des développeurs