Skip to content
Menu

Search the site

Type to search guides, blog, API and product.

↑ ↓ to move · Enter to open · Esc to close

API Reference

API

WhatsApp OTP

Send verification codes over WhatsApp with a Copy code button

View as Markdown

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.

MethodPathDescription
POST/v1/otp/templateCreate the authentication template
GET/v1/otp/templateStatus of the OTP templates
POST/v1/otp/sendGenerate and send a code
POST/v1/otp/verifyVerify 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.

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);
Response
{
  "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
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);
Response
{
  "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
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);
Response
{
  "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
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);
Response
{
  "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.

CodeHTTPWhen
TEMPLATE_NOT_APPROVED409The OTP template for that language does not exist or Meta has not approved it yet
OTP_RATE_LIMITED429Too many codes for that phone; retry after Retry-After
META_ERROR422Meta rejected the template (for example, unverified business)
SEND_FAILED422Meta did not accept the message
VALIDATION_ERROR400Invalid body: phone, length, language or code
NOT_FOUND404The WhatsApp line does not exist or does not belong to this agent