API
OTP par WhatsApp
Envoyez des codes de vérification par WhatsApp avec un bouton Copier le code
# OTP par WhatsApp > Envoyez des codes de vérification par WhatsApp avec un bouton Copier le code - Page: https://tbit.app/fr/docs/api/otp - URL de base: `https://rest-api.tbit.app/v1` - Authentification: en-tête `X-API-Key` avec votre clé dans chaque requête (les exemples la lisent depuis la variable d'environnement `TBIT_API_KEY`) ## Vue d'ensemble TBit génère un code numérique, l'envoie par WhatsApp depuis la ligne de votre agent avec un modèle d'authentification (bouton « Copier le code ») et vous le renvoie dans la réponse. Vous pouvez le valider dans votre système ou laisser TBit le valider avec /v1/otp/verify. Les OTP sont gratuits et ne consomment pas votre quota de modèles. ## Endpoints | Méthode | Chemin | Description | | --- | --- | --- | | `POST` | `/v1/otp/template` | Créer le modèle d'authentification | | `GET` | `/v1/otp/template` | État des modèles OTP | | `POST` | `/v1/otp/send` | Générer et envoyer un code | | `POST` | `/v1/otp/verify` | Vérifier un code (facultatif) | ## Prérequis Il vous faut une ligne WhatsApp connectée à votre agent. Meta n'autorise les modèles d'authentification qu'aux entreprises vérifiées dans Meta Business (Paramètres de l'entreprise → Centre de sécurité) ; sans vérification, la création du modèle renvoie META_ERROR avec « does not have permission to create message template ». Le code part du numéro de la ligne de l'agent propriétaire de la clé API. ## Créer le modèle Une fois par langue (il s'appelle tbit_otp_<langue>). Le texte est rédigé par Meta et ne peut pas être personnalisé : le code, une recommandation de sécurité et la validité en pied de message. Champs facultatifs : language (es par défaut), code_expiration_minutes (1 à 90, 10 par défaut) et channel_id si l'agent a plusieurs lignes. Si le modèle existe déjà, la réponse est created: false avec son état. Meta l'approuve généralement en quelques secondes. `POST /v1/otp/template` ```bash curl -X POST "https://rest-api.tbit.app/v1/otp/template" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "language": "es", "code_expiration_minutes": 10 }' ``` Réponse: ```json { "data": { "created": true, "template": { "id": "6ac60aeaa2a9ed0cd9ca7fd4", "name": "tbit_otp_es", "language": "es", "status": "PENDING", "rejected_reason": null, "code_expiration_minutes": 10, "channel_id": "691deef351c7513d0c6a2a6f" } } } ``` ## État du modèle Liste les modèles OTP de l'agent. Ceux qui ne sont pas encore approuvés sont vérifiés en direct auprès de Meta : status vaut PENDING, APPROVED ou REJECTED. `GET /v1/otp/template` ```bash curl "https://rest-api.tbit.app/v1/otp/template" \ -H "X-API-Key: $TBIT_API_KEY" ``` Réponse: ```json { "data": [ { "id": "6ac60aeaa2a9ed0cd9ca7fd4", "name": "tbit_otp_es", "language": "es", "status": "APPROVED", "rejected_reason": null, "code_expiration_minutes": 10, "channel_id": "691deef351c7513d0c6a2a6f" } ] } ``` ## Envoyer un code to est le numéro avec l'indicatif du pays (espaces, tirets et + acceptés). length va de 4 à 8 chiffres (6 par défaut) et language choisit le modèle (es par défaut). La réponse contient le code pour votre système ; le code n'est pas conservé dans l'historique du chat. `POST /v1/otp/send` ```bash curl -X POST "https://rest-api.tbit.app/v1/otp/send" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+57 300 123 4567", "length": 6 }' ``` Réponse: ```json { "data": { "request_id": "be4ffa6c-f45a-4410-b38a-882bd3edd9b3", "to": "573001234567", "code": "054381", "expires_in_minutes": 10, "expires_at": "2026-10-07T09:17:26.278Z" } } ``` ## Vérifier un code Facultatif : si vous préférez ne pas stocker le code, TBit le valide. Chaque code n'est valable qu'une fois et expire avec le modèle. Après 5 tentatives échouées il est invalidé et il faut en demander un autre. reason peut valoir invalid_code (avec attempts_left), too_many_attempts ou expired_or_not_found. Un code correct renvoie { "valid": true }. `POST /v1/otp/verify` ```bash curl -X POST "https://rest-api.tbit.app/v1/otp/verify" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "573001234567", "code": "054381" }' ``` Réponse: ```json { "data": { "valid": false, "reason": "invalid_code", "attempts_left": 4 } } ``` ## Limites Par téléphone : un envoi toutes les 30 secondes et 5 par heure. Au-delà, la réponse est 429 OTP_RATE_LIMITED avec l'en-tête Retry-After. La limite générale de 100 requêtes par minute et par clé API s'applique aussi. ## Erreurs | Code | HTTP | Quand | | --- | --- | --- | | `TEMPLATE_NOT_APPROVED` | 409 | Le modèle OTP de cette langue n'existe pas ou Meta ne l'a pas encore approuvé | | `OTP_RATE_LIMITED` | 429 | Trop de codes pour ce numéro ; réessayez selon Retry-After | | `META_ERROR` | 422 | Meta a refusé le modèle (par exemple, entreprise non vérifiée) | | `SEND_FAILED` | 422 | Meta n'a pas accepté l'envoi du message | | `VALIDATION_ERROR` | 400 | Corps invalide : téléphone, longueur, langue ou code | | `NOT_FOUND` | 404 | La ligne WhatsApp n'existe pas ou n'appartient pas à cet agent |TBit génère un code numérique, l'envoie par WhatsApp depuis la ligne de votre agent avec un modèle d'authentification (bouton « Copier le code ») et vous le renvoie dans la réponse. Vous pouvez le valider dans votre système ou laisser TBit le valider avec /v1/otp/verify. Les OTP sont gratuits et ne consomment pas votre quota de modèles.
| Méthode | Chemin | Description |
|---|---|---|
| POST | /v1/otp/template | Créer le modèle d'authentification |
| GET | /v1/otp/template | État des modèles OTP |
| POST | /v1/otp/send | Générer et envoyer un code |
| POST | /v1/otp/verify | Vérifier un code (facultatif) |
Il vous faut une ligne WhatsApp connectée à votre agent. Meta n'autorise les modèles d'authentification qu'aux entreprises vérifiées dans Meta Business (Paramètres de l'entreprise → Centre de sécurité) ; sans vérification, la création du modèle renvoie META_ERROR avec « does not have permission to create message template ». Le code part du numéro de la ligne de l'agent propriétaire de la clé API.
Une fois par langue (il s'appelle tbit_otp_<langue>). Le texte est rédigé par Meta et ne peut pas être personnalisé : le code, une recommandation de sécurité et la validité en pied de message. Champs facultatifs : language (es par défaut), code_expiration_minutes (1 à 90, 10 par défaut) et channel_id si l'agent a plusieurs lignes. Si le modèle existe déjà, la réponse est created: false avec son état. Meta l'approuve généralement en quelques secondes.
/v1/otp/templatecurl -X POST "https://rest-api.tbit.app/v1/otp/template" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"language": "es",
"code_expiration_minutes": 10
}'const response = await fetch('https://rest-api.tbit.app/v1/otp/template', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
language: 'es',
code_expiration_minutes: 10,
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/otp/template',
{
language: 'es',
code_expiration_minutes: 10,
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/otp/template',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'language': 'es',
'code_expiration_minutes': 10,
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/otp/template');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'language' => 'es',
'code_expiration_minutes' => 10,
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"created": true,
"template": {
"id": "6ac60aeaa2a9ed0cd9ca7fd4",
"name": "tbit_otp_es",
"language": "es",
"status": "PENDING",
"rejected_reason": null,
"code_expiration_minutes": 10,
"channel_id": "691deef351c7513d0c6a2a6f"
}
}
}Liste les modèles OTP de l'agent. Ceux qui ne sont pas encore approuvés sont vérifiés en direct auprès de Meta : status vaut PENDING, APPROVED ou REJECTED.
/v1/otp/templatecurl "https://rest-api.tbit.app/v1/otp/template" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/otp/template', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/otp/template',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/otp/template',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/otp/template');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": [
{
"id": "6ac60aeaa2a9ed0cd9ca7fd4",
"name": "tbit_otp_es",
"language": "es",
"status": "APPROVED",
"rejected_reason": null,
"code_expiration_minutes": 10,
"channel_id": "691deef351c7513d0c6a2a6f"
}
]
}to est le numéro avec l'indicatif du pays (espaces, tirets et + acceptés). length va de 4 à 8 chiffres (6 par défaut) et language choisit le modèle (es par défaut). La réponse contient le code pour votre système ; le code n'est pas conservé dans l'historique du chat.
/v1/otp/sendcurl -X POST "https://rest-api.tbit.app/v1/otp/send" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+57 300 123 4567",
"length": 6
}'const response = await fetch('https://rest-api.tbit.app/v1/otp/send', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+57 300 123 4567',
length: 6,
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/otp/send',
{
to: '+57 300 123 4567',
length: 6,
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/otp/send',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '+57 300 123 4567',
'length': 6,
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/otp/send');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '+57 300 123 4567',
'length' => 6,
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"request_id": "be4ffa6c-f45a-4410-b38a-882bd3edd9b3",
"to": "573001234567",
"code": "054381",
"expires_in_minutes": 10,
"expires_at": "2026-10-07T09:17:26.278Z"
}
}Facultatif : si vous préférez ne pas stocker le code, TBit le valide. Chaque code n'est valable qu'une fois et expire avec le modèle. Après 5 tentatives échouées il est invalidé et il faut en demander un autre. reason peut valoir invalid_code (avec attempts_left), too_many_attempts ou expired_or_not_found. Un code correct renvoie { "valid": true }.
/v1/otp/verifycurl -X POST "https://rest-api.tbit.app/v1/otp/verify" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "573001234567",
"code": "054381"
}'const response = await fetch('https://rest-api.tbit.app/v1/otp/verify', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '573001234567',
code: '054381',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/otp/verify',
{
to: '573001234567',
code: '054381',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/otp/verify',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '573001234567',
'code': '054381',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/otp/verify');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '573001234567',
'code' => '054381',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"valid": false,
"reason": "invalid_code",
"attempts_left": 4
}
}Par téléphone : un envoi toutes les 30 secondes et 5 par heure. Au-delà, la réponse est 429 OTP_RATE_LIMITED avec l'en-tête Retry-After. La limite générale de 100 requêtes par minute et par clé API s'applique aussi.
| Code | HTTP | Quand |
|---|---|---|
TEMPLATE_NOT_APPROVED | 409 | Le modèle OTP de cette langue n'existe pas ou Meta ne l'a pas encore approuvé |
OTP_RATE_LIMITED | 429 | Trop de codes pour ce numéro ; réessayez selon Retry-After |
META_ERROR | 422 | Meta a refusé le modèle (par exemple, entreprise non vérifiée) |
SEND_FAILED | 422 | Meta n'a pas accepté l'envoi du message |
VALIDATION_ERROR | 400 | Corps invalide : téléphone, longueur, langue ou code |
NOT_FOUND | 404 | La ligne WhatsApp n'existe pas ou n'appartient pas à cet agent |