API
WhatsApp OTP
Send verification codes over WhatsApp with a Copy code button
# WhatsApp OTP > Send verification codes over WhatsApp with a Copy code button - Page: https://tbit.app/docs/api/otp - Base URL: `https://rest-api.tbit.app/v1` - Authentication: `X-API-Key` header with your key on every request (the examples read it from the `TBIT_API_KEY` environment variable) ## Overview TBit generates a numeric code, sends it over WhatsApp from your agent's line using an authentication template (Copy code button) and returns it in the response. You can validate it in your own system or let TBit validate it with /v1/otp/verify. OTPs are free and do not count against your template quota. ## Endpoints | Method | Path | Description | | --- | --- | --- | | `POST` | `/v1/otp/template` | Create the authentication template | | `GET` | `/v1/otp/template` | Status of the OTP templates | | `POST` | `/v1/otp/send` | Generate and send a code | | `POST` | `/v1/otp/verify` | Verify a code (optional) | ## Requirements You need a WhatsApp line connected to your agent. Meta only allows authentication templates for businesses verified in Meta Business (Business settings → Security center); without verification, creating the template returns META_ERROR with "does not have permission to create message template". The code is sent from the line of the agent that owns the API key. ## Create the template Once per language (it is named tbit_otp_<language>). Meta writes the text and it cannot be customized: the code, a security recommendation and the expiry in the footer. Optional fields: language (es by default), code_expiration_minutes (1 to 90, 10 by default) and channel_id if the agent has several lines. If the template already exists it returns created: false with its status. Meta usually approves it within seconds. `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 }' ``` Response: ```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" } } } ``` ## Template status Lists the agent's OTP templates. Those not yet approved are checked live with Meta: status is PENDING, APPROVED or REJECTED. `GET /v1/otp/template` ```bash curl "https://rest-api.tbit.app/v1/otp/template" \ -H "X-API-Key: $TBIT_API_KEY" ``` Response: ```json { "data": [ { "id": "6ac60aeaa2a9ed0cd9ca7fd4", "name": "tbit_otp_es", "language": "es", "status": "APPROVED", "rejected_reason": null, "code_expiration_minutes": 10, "channel_id": "691deef351c7513d0c6a2a6f" } ] } ``` ## Send a code to is the phone number with country code (spaces, dashes and + are accepted). length is 4 to 8 digits (6 by default) and language picks the template (es by default). The response includes the code for your system to use; the code is not stored in the chat history. `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 }' ``` Response: ```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" } } ``` ## Verify a code Optional: if you would rather not store the code, TBit validates it. Each code works once and expires with the template. After 5 failed attempts it is invalidated and a new one must be requested. reason can be invalid_code (with attempts_left), too_many_attempts or expired_or_not_found. A correct code returns { "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" }' ``` Response: ```json { "data": { "valid": false, "reason": "invalid_code", "attempts_left": 4 } } ``` ## Limits Per phone: one send every 30 seconds and 5 per hour. Beyond that it returns 429 OTP_RATE_LIMITED with a Retry-After header. The general limit of 100 requests per minute per API key also applies. ## Errors | Code | HTTP | When | | --- | --- | --- | | `TEMPLATE_NOT_APPROVED` | 409 | The OTP template for that language does not exist or Meta has not approved it yet | | `OTP_RATE_LIMITED` | 429 | Too many codes for that phone; retry after Retry-After | | `META_ERROR` | 422 | Meta rejected the template (for example, unverified business) | | `SEND_FAILED` | 422 | Meta did not accept the message | | `VALIDATION_ERROR` | 400 | Invalid body: phone, length, language or code | | `NOT_FOUND` | 404 | The WhatsApp line does not exist or does not belong to this agent |TBit generates a numeric code, sends it over WhatsApp from your agent's line using an authentication template (Copy code button) and returns it in the response. You can validate it in your own system or let TBit validate it with /v1/otp/verify. OTPs are free and do not count against your template quota.
| Method | Path | Description |
|---|---|---|
| POST | /v1/otp/template | Create the authentication template |
| GET | /v1/otp/template | Status of the OTP templates |
| POST | /v1/otp/send | Generate and send a code |
| POST | /v1/otp/verify | Verify a code (optional) |
You need a WhatsApp line connected to your agent. Meta only allows authentication templates for businesses verified in Meta Business (Business settings → Security center); without verification, creating the template returns META_ERROR with "does not have permission to create message template". The code is sent from the line of the agent that owns the API key.
Once per language (it is named tbit_otp_<language>). Meta writes the text and it cannot be customized: the code, a security recommendation and the expiry in the footer. Optional fields: language (es by default), code_expiration_minutes (1 to 90, 10 by default) and channel_id if the agent has several lines. If the template already exists it returns created: false with its status. Meta usually approves it within seconds.
/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"
}
}
}Lists the agent's OTP templates. Those not yet approved are checked live with Meta: status is PENDING, APPROVED or 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 is the phone number with country code (spaces, dashes and + are accepted). length is 4 to 8 digits (6 by default) and language picks the template (es by default). The response includes the code for your system to use; the code is not stored in the chat history.
/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"
}
}Optional: if you would rather not store the code, TBit validates it. Each code works once and expires with the template. After 5 failed attempts it is invalidated and a new one must be requested. reason can be invalid_code (with attempts_left), too_many_attempts or expired_or_not_found. A correct code returns { "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
}
}Per phone: one send every 30 seconds and 5 per hour. Beyond that it returns 429 OTP_RATE_LIMITED with a Retry-After header. The general limit of 100 requests per minute per API key also applies.
| Code | HTTP | When |
|---|---|---|
TEMPLATE_NOT_APPROVED | 409 | The OTP template for that language does not exist or Meta has not approved it yet |
OTP_RATE_LIMITED | 429 | Too many codes for that phone; retry after Retry-After |
META_ERROR | 422 | Meta rejected the template (for example, unverified business) |
SEND_FAILED | 422 | Meta did not accept the message |
VALIDATION_ERROR | 400 | Invalid body: phone, length, language or code |
NOT_FOUND | 404 | The WhatsApp line does not exist or does not belong to this agent |