API
OTP pelo WhatsApp
Envie códigos de verificação pelo WhatsApp com o botão Copiar código
# OTP pelo WhatsApp > Envie códigos de verificação pelo WhatsApp com o botão Copiar código - Página: https://tbit.app/pt/docs/api/otp - URL base: `https://rest-api.tbit.app/v1` - Autenticação: cabeçalho `X-API-Key` com a sua chave em cada requisição (os exemplos a leem da variável de ambiente `TBIT_API_KEY`) ## Visão geral A TBit gera um código numérico, envia pelo WhatsApp a partir da linha do seu agente com um modelo de autenticação (botão «Copiar código») e o devolve na resposta. Você pode validá-lo no seu sistema ou pedir à TBit que o valide com /v1/otp/verify. Os OTP são gratuitos e não consomem sua cota de modelos. ## Endpoints | Método | Rota | Descrição | | --- | --- | --- | | `POST` | `/v1/otp/template` | Criar o modelo de autenticação | | `GET` | `/v1/otp/template` | Status dos modelos OTP | | `POST` | `/v1/otp/send` | Gerar e enviar um código | | `POST` | `/v1/otp/verify` | Verificar um código (opcional) | ## Requisitos Você precisa de uma linha de WhatsApp conectada ao seu agente. A Meta só permite modelos de autenticação para empresas verificadas no Meta Business (Configurações do negócio → Central de segurança); sem verificação, criar o modelo responde META_ERROR com «does not have permission to create message template». O código sai do número da linha do agente dono da chave de API. ## Criar o modelo Uma vez por idioma (chama-se tbit_otp_<idioma>). O texto é escrito pela Meta e não pode ser personalizado: o código, uma recomendação de segurança e a validade no rodapé. Campos opcionais: language (es por padrão), code_expiration_minutes (1 a 90, 10 por padrão) e channel_id se o agente tiver várias linhas. Se o modelo já existir, responde created: false com seu status. A Meta costuma aprová-lo em 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 }' ``` Resposta: ```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" } } } ``` ## Status do modelo Lista os modelos OTP do agente. Os que ainda não foram aprovados são consultados ao vivo na Meta: status é 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" ``` Resposta: ```json { "data": [ { "id": "6ac60aeaa2a9ed0cd9ca7fd4", "name": "tbit_otp_es", "language": "es", "status": "APPROVED", "rejected_reason": null, "code_expiration_minutes": 10, "channel_id": "691deef351c7513d0c6a2a6f" } ] } ``` ## Enviar um código to é o telefone com código do país (espaços, hífens e + são aceitos). length vai de 4 a 8 dígitos (6 por padrão) e language escolhe o modelo (es por padrão). A resposta traz o código para o seu sistema usar; o código não fica salvo no histórico do 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 }' ``` Resposta: ```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 um código Opcional: se não quiser guardar o código, a TBit o valida. Cada código vale uma única vez e expira com o modelo. Após 5 tentativas erradas ele é invalidado e é preciso pedir outro. reason pode ser invalid_code (com attempts_left), too_many_attempts ou expired_or_not_found. Um código correto 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" }' ``` Resposta: ```json { "data": { "valid": false, "reason": "invalid_code", "attempts_left": 4 } } ``` ## Limites Por telefone: um envio a cada 30 segundos e 5 por hora. Acima disso responde 429 OTP_RATE_LIMITED com o cabeçalho Retry-After. Também vale o limite geral de 100 solicitações por minuto por chave de API. ## Erros | Código | HTTP | Quando | | --- | --- | --- | | `TEMPLATE_NOT_APPROVED` | 409 | O modelo OTP desse idioma não existe ou a Meta ainda não o aprovou | | `OTP_RATE_LIMITED` | 429 | Códigos demais para esse telefone; tente de novo conforme Retry-After | | `META_ERROR` | 422 | A Meta rejeitou o modelo (por exemplo, empresa não verificada) | | `SEND_FAILED` | 422 | A Meta não aceitou o envio da mensagem | | `VALIDATION_ERROR` | 400 | Corpo inválido: telefone, tamanho, idioma ou código | | `NOT_FOUND` | 404 | A linha de WhatsApp não existe ou não é deste agente |A TBit gera um código numérico, envia pelo WhatsApp a partir da linha do seu agente com um modelo de autenticação (botão «Copiar código») e o devolve na resposta. Você pode validá-lo no seu sistema ou pedir à TBit que o valide com /v1/otp/verify. Os OTP são gratuitos e não consomem sua cota de modelos.
| Método | Rota | Descrição |
|---|---|---|
| POST | /v1/otp/template | Criar o modelo de autenticação |
| GET | /v1/otp/template | Status dos modelos OTP |
| POST | /v1/otp/send | Gerar e enviar um código |
| POST | /v1/otp/verify | Verificar um código (opcional) |
Você precisa de uma linha de WhatsApp conectada ao seu agente. A Meta só permite modelos de autenticação para empresas verificadas no Meta Business (Configurações do negócio → Central de segurança); sem verificação, criar o modelo responde META_ERROR com «does not have permission to create message template». O código sai do número da linha do agente dono da chave de API.
Uma vez por idioma (chama-se tbit_otp_<idioma>). O texto é escrito pela Meta e não pode ser personalizado: o código, uma recomendação de segurança e a validade no rodapé. Campos opcionais: language (es por padrão), code_expiration_minutes (1 a 90, 10 por padrão) e channel_id se o agente tiver várias linhas. Se o modelo já existir, responde created: false com seu status. A Meta costuma aprová-lo em 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 os modelos OTP do agente. Os que ainda não foram aprovados são consultados ao vivo na Meta: status é 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 é o telefone com código do país (espaços, hífens e + são aceitos). length vai de 4 a 8 dígitos (6 por padrão) e language escolhe o modelo (es por padrão). A resposta traz o código para o seu sistema usar; o código não fica salvo no histórico do 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: se não quiser guardar o código, a TBit o valida. Cada código vale uma única vez e expira com o modelo. Após 5 tentativas erradas ele é invalidado e é preciso pedir outro. reason pode ser invalid_code (com attempts_left), too_many_attempts ou expired_or_not_found. Um código correto 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 telefone: um envio a cada 30 segundos e 5 por hora. Acima disso responde 429 OTP_RATE_LIMITED com o cabeçalho Retry-After. Também vale o limite geral de 100 solicitações por minuto por chave de API.
| Código | HTTP | Quando |
|---|---|---|
TEMPLATE_NOT_APPROVED | 409 | O modelo OTP desse idioma não existe ou a Meta ainda não o aprovou |
OTP_RATE_LIMITED | 429 | Códigos demais para esse telefone; tente de novo conforme Retry-After |
META_ERROR | 422 | A Meta rejeitou o modelo (por exemplo, empresa não verificada) |
SEND_FAILED | 422 | A Meta não aceitou o envio da mensagem |
VALIDATION_ERROR | 400 | Corpo inválido: telefone, tamanho, idioma ou código |
NOT_FOUND | 404 | A linha de WhatsApp não existe ou não é deste agente |