API
OTP por WhatsApp
Envía códigos de verificación por WhatsApp con el botón Copiar código
# OTP por WhatsApp > Envía códigos de verificación por WhatsApp con el botón Copiar código - Página: https://tbit.app/es/docs/api/otp - URL base: `https://rest-api.tbit.app/v1` - Autenticación: encabezado `X-API-Key` con tu clave en cada solicitud (los ejemplos la leen de la variable de entorno `TBIT_API_KEY`) ## Descripción general TBit genera un código numérico, lo envía por WhatsApp desde la línea de tu agente con una plantilla de autenticación (botón «Copiar código») y te lo devuelve en la respuesta. Puedes validarlo en tu sistema o pedirle a TBit que lo valide con /v1/otp/verify. Los OTP no se cobran ni consumen tu cupo de plantillas. ## Endpoints | Método | Ruta | Descripción | | --- | --- | --- | | `POST` | `/v1/otp/template` | Crear la plantilla de autenticación | | `GET` | `/v1/otp/template` | Estado de las plantillas OTP | | `POST` | `/v1/otp/send` | Generar y enviar un código | | `POST` | `/v1/otp/verify` | Verificar un código (opcional) | ## Requisitos Necesitas una línea de WhatsApp conectada a tu agente. Meta solo permite plantillas de autenticación a negocios verificados en Meta Business (Configuración del negocio → Centro de seguridad); sin verificación, crear la plantilla responde META_ERROR con «does not have permission to create message template». El código sale desde el número de la línea del agente dueño de la clave API. ## Crear la plantilla Una vez por idioma (se llama tbit_otp_<idioma>). El texto lo pone Meta y no se puede personalizar: el código, una recomendación de seguridad y la vigencia en el pie. Campos opcionales: language (es por defecto), code_expiration_minutes (1 a 90, 10 por defecto) y channel_id si el agente tiene varias líneas. Si la plantilla ya existe responde created: false con su estado. Meta suele aprobarla en segundos. `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 }' ``` Respuesta: ```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" } } } ``` ## Estado de la plantilla Lista las plantillas OTP del agente. Las que no están aprobadas se consultan en vivo con Meta: status es PENDING, APPROVED o REJECTED. `GET /v1/otp/template` ```bash curl "https://rest-api.tbit.app/v1/otp/template" \ -H "X-API-Key: $TBIT_API_KEY" ``` Respuesta: ```json { "data": [ { "id": "6ac60aeaa2a9ed0cd9ca7fd4", "name": "tbit_otp_es", "language": "es", "status": "APPROVED", "rejected_reason": null, "code_expiration_minutes": 10, "channel_id": "691deef351c7513d0c6a2a6f" } ] } ``` ## Enviar un código to es el teléfono con código de país (se aceptan espacios, guiones y +). length va de 4 a 8 dígitos (6 por defecto) y language elige la plantilla (es por defecto). La respuesta trae el código para que tu sistema lo use; el código no queda guardado en el historial del 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 }' ``` Respuesta: ```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" } } ``` ## Verificar un código Opcional: si no quieres guardar el código, TBit lo valida. Cada código sirve una sola vez y vence con la plantilla. Tras 5 intentos fallidos se invalida y hay que pedir otro. reason puede ser invalid_code (con attempts_left), too_many_attempts o expired_or_not_found. Un código correcto responde { "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" }' ``` Respuesta: ```json { "data": { "valid": false, "reason": "invalid_code", "attempts_left": 4 } } ``` ## Límites Por teléfono: un envío cada 30 segundos y 5 por hora. Si se supera, responde 429 OTP_RATE_LIMITED con el encabezado Retry-After. Aplica además el límite general de 100 solicitudes por minuto por clave API. ## Errores | Código | HTTP | Cuándo | | --- | --- | --- | | `TEMPLATE_NOT_APPROVED` | 409 | La plantilla OTP de ese idioma no existe o Meta aún no la aprueba | | `OTP_RATE_LIMITED` | 429 | Demasiados códigos para ese teléfono; reintenta según Retry-After | | `META_ERROR` | 422 | Meta rechazó la plantilla (por ejemplo, negocio sin verificar) | | `SEND_FAILED` | 422 | Meta no aceptó el envío del mensaje | | `VALIDATION_ERROR` | 400 | Cuerpo inválido: teléfono, longitud, idioma o código | | `NOT_FOUND` | 404 | La línea de WhatsApp no existe o no es de este agente |TBit genera un código numérico, lo envía por WhatsApp desde la línea de tu agente con una plantilla de autenticación (botón «Copiar código») y te lo devuelve en la respuesta. Puedes validarlo en tu sistema o pedirle a TBit que lo valide con /v1/otp/verify. Los OTP no se cobran ni consumen tu cupo de plantillas.
| Método | Ruta | Descripción |
|---|---|---|
| POST | /v1/otp/template | Crear la plantilla de autenticación |
| GET | /v1/otp/template | Estado de las plantillas OTP |
| POST | /v1/otp/send | Generar y enviar un código |
| POST | /v1/otp/verify | Verificar un código (opcional) |
Necesitas una línea de WhatsApp conectada a tu agente. Meta solo permite plantillas de autenticación a negocios verificados en Meta Business (Configuración del negocio → Centro de seguridad); sin verificación, crear la plantilla responde META_ERROR con «does not have permission to create message template». El código sale desde el número de la línea del agente dueño de la clave API.
Una vez por idioma (se llama tbit_otp_<idioma>). El texto lo pone Meta y no se puede personalizar: el código, una recomendación de seguridad y la vigencia en el pie. Campos opcionales: language (es por defecto), code_expiration_minutes (1 a 90, 10 por defecto) y channel_id si el agente tiene varias líneas. Si la plantilla ya existe responde created: false con su estado. Meta suele aprobarla en segundos.
/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"
}
}
}Lista las plantillas OTP del agente. Las que no están aprobadas se consultan en vivo con Meta: status es PENDING, APPROVED o 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 es el teléfono con código de país (se aceptan espacios, guiones y +). length va de 4 a 8 dígitos (6 por defecto) y language elige la plantilla (es por defecto). La respuesta trae el código para que tu sistema lo use; el código no queda guardado en el historial del 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"
}
}Opcional: si no quieres guardar el código, TBit lo valida. Cada código sirve una sola vez y vence con la plantilla. Tras 5 intentos fallidos se invalida y hay que pedir otro. reason puede ser invalid_code (con attempts_left), too_many_attempts o expired_or_not_found. Un código correcto responde { "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
}
}Por teléfono: un envío cada 30 segundos y 5 por hora. Si se supera, responde 429 OTP_RATE_LIMITED con el encabezado Retry-After. Aplica además el límite general de 100 solicitudes por minuto por clave API.
| Código | HTTP | Cuándo |
|---|---|---|
TEMPLATE_NOT_APPROVED | 409 | La plantilla OTP de ese idioma no existe o Meta aún no la aprueba |
OTP_RATE_LIMITED | 429 | Demasiados códigos para ese teléfono; reintenta según Retry-After |
META_ERROR | 422 | Meta rechazó la plantilla (por ejemplo, negocio sin verificar) |
SEND_FAILED | 422 | Meta no aceptó el envío del mensaje |
VALIDATION_ERROR | 400 | Cuerpo inválido: teléfono, longitud, idioma o código |
NOT_FOUND | 404 | La línea de WhatsApp no existe o no es de este agente |