Aller au contenu
Menu

Rechercher sur le site

Tape pour chercher dans les guides, le blog, l'API et le produit.

↑ ↓ pour naviguer · Entrée pour ouvrir · Échap pour fermer

Référence de l'API

API

OTP par WhatsApp

Envoyez des codes de vérification par WhatsApp avec un bouton Copier le code

Voir en Markdown

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éthodeCheminDescription
POST/v1/otp/templateCréer le modèle d'authentification
GET/v1/otp/templateÉtat des modèles OTP
POST/v1/otp/sendGénérer et envoyer un code
POST/v1/otp/verifyVé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.

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
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
  }'
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);
Réponse
{
  "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
curl "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);
Réponse
{
  "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
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
  }'
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);
Réponse
{
  "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
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"
  }'
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);
Réponse
{
  "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.

CodeHTTPQuand
TEMPLATE_NOT_APPROVED409Le modèle OTP de cette langue n'existe pas ou Meta ne l'a pas encore approuvé
OTP_RATE_LIMITED429Trop de codes pour ce numéro ; réessayez selon Retry-After
META_ERROR422Meta a refusé le modèle (par exemple, entreprise non vérifiée)
SEND_FAILED422Meta n'a pas accepté l'envoi du message
VALIDATION_ERROR400Corps invalide : téléphone, longueur, langue ou code
NOT_FOUND404La ligne WhatsApp n'existe pas ou n'appartient pas à cet agent