API
WhatsApp-OTP
Verstuur verificatiecodes via WhatsApp met een knop Code kopiëren
# WhatsApp-OTP > Verstuur verificatiecodes via WhatsApp met een knop Code kopiëren - Pagina: https://tbit.app/nl/docs/api/otp - Basis-URL: `https://rest-api.tbit.app/v1` - Authenticatie: header `X-API-Key` met je sleutel bij elk verzoek (de voorbeelden lezen hem uit de omgevingsvariabele `TBIT_API_KEY`) ## Overzicht TBit genereert een numerieke code, verstuurt die via WhatsApp vanaf de lijn van je agent met een authenticatiesjabloon (knop „Code kopiëren”) en geeft hem terug in het antwoord. Je kunt hem in je eigen systeem controleren of TBit laten controleren met /v1/otp/verify. OTP's zijn gratis en tellen niet mee voor je sjablonenquotum. ## Endpoints | Methode | Pad | Beschrijving | | --- | --- | --- | | `POST` | `/v1/otp/template` | Het authenticatiesjabloon aanmaken | | `GET` | `/v1/otp/template` | Status van de OTP-sjablonen | | `POST` | `/v1/otp/send` | Een code genereren en versturen | | `POST` | `/v1/otp/verify` | Een code controleren (optioneel) | ## Vereisten Je hebt een WhatsApp-lijn nodig die aan je agent is gekoppeld. Meta staat authenticatiesjablonen alleen toe voor bedrijven die in Meta Business zijn geverifieerd (Bedrijfsinstellingen → Beveiligingscentrum); zonder verificatie geeft het aanmaken META_ERROR met „does not have permission to create message template”. De code wordt verstuurd vanaf het nummer van de lijn van de agent van wie de API-sleutel is. ## Het sjabloon aanmaken Eén keer per taal (het heet tbit_otp_<taal>). Meta schrijft de tekst en die is niet aan te passen: de code, een veiligheidsadvies en de geldigheid in de voettekst. Optionele velden: language (standaard es), code_expiration_minutes (1 tot 90, standaard 10) en channel_id als de agent meerdere lijnen heeft. Bestaat het sjabloon al, dan komt created: false met de status terug. Meta keurt het meestal binnen seconden goed. `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" } } } ``` ## Status van het sjabloon Geeft de OTP-sjablonen van de agent. Sjablonen die nog niet zijn goedgekeurd worden live bij Meta opgevraagd: status is PENDING, APPROVED of 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" } ] } ``` ## Een code versturen to is het telefoonnummer met landcode (spaties, streepjes en + zijn toegestaan). length is 4 tot 8 cijfers (standaard 6) en language kiest het sjabloon (standaard es). Het antwoord bevat de code voor je systeem; de code wordt niet in de chatgeschiedenis bewaard. `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" } } ``` ## Een code controleren Optioneel: wil je de code niet zelf bewaren, dan controleert TBit hem. Elke code werkt één keer en verloopt met het sjabloon. Na 5 mislukte pogingen wordt hij ongeldig en moet je een nieuwe aanvragen. reason kan invalid_code (met attempts_left), too_many_attempts of expired_or_not_found zijn. Een juiste code geeft { "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 } } ``` ## Limieten Per telefoon: één verzending per 30 seconden en 5 per uur. Daarboven komt 429 OTP_RATE_LIMITED met de header Retry-After. De algemene limiet van 100 verzoeken per minuut per API-sleutel geldt ook. ## Fouten | Code | HTTP | Wanneer | | --- | --- | --- | | `TEMPLATE_NOT_APPROVED` | 409 | Het OTP-sjabloon voor die taal bestaat niet of is nog niet door Meta goedgekeurd | | `OTP_RATE_LIMITED` | 429 | Te veel codes voor dat nummer; probeer opnieuw na Retry-After | | `META_ERROR` | 422 | Meta heeft het sjabloon afgewezen (bijvoorbeeld niet-geverifieerd bedrijf) | | `SEND_FAILED` | 422 | Meta heeft het bericht niet geaccepteerd | | `VALIDATION_ERROR` | 400 | Ongeldige body: telefoon, lengte, taal of code | | `NOT_FOUND` | 404 | De WhatsApp-lijn bestaat niet of hoort niet bij deze agent |TBit genereert een numerieke code, verstuurt die via WhatsApp vanaf de lijn van je agent met een authenticatiesjabloon (knop „Code kopiëren”) en geeft hem terug in het antwoord. Je kunt hem in je eigen systeem controleren of TBit laten controleren met /v1/otp/verify. OTP's zijn gratis en tellen niet mee voor je sjablonenquotum.
| Methode | Pad | Beschrijving |
|---|---|---|
| POST | /v1/otp/template | Het authenticatiesjabloon aanmaken |
| GET | /v1/otp/template | Status van de OTP-sjablonen |
| POST | /v1/otp/send | Een code genereren en versturen |
| POST | /v1/otp/verify | Een code controleren (optioneel) |
Je hebt een WhatsApp-lijn nodig die aan je agent is gekoppeld. Meta staat authenticatiesjablonen alleen toe voor bedrijven die in Meta Business zijn geverifieerd (Bedrijfsinstellingen → Beveiligingscentrum); zonder verificatie geeft het aanmaken META_ERROR met „does not have permission to create message template”. De code wordt verstuurd vanaf het nummer van de lijn van de agent van wie de API-sleutel is.
Eén keer per taal (het heet tbit_otp_<taal>). Meta schrijft de tekst en die is niet aan te passen: de code, een veiligheidsadvies en de geldigheid in de voettekst. Optionele velden: language (standaard es), code_expiration_minutes (1 tot 90, standaard 10) en channel_id als de agent meerdere lijnen heeft. Bestaat het sjabloon al, dan komt created: false met de status terug. Meta keurt het meestal binnen seconden goed.
/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"
}
}
}Geeft de OTP-sjablonen van de agent. Sjablonen die nog niet zijn goedgekeurd worden live bij Meta opgevraagd: status is PENDING, APPROVED of 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 het telefoonnummer met landcode (spaties, streepjes en + zijn toegestaan). length is 4 tot 8 cijfers (standaard 6) en language kiest het sjabloon (standaard es). Het antwoord bevat de code voor je systeem; de code wordt niet in de chatgeschiedenis bewaard.
/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"
}
}Optioneel: wil je de code niet zelf bewaren, dan controleert TBit hem. Elke code werkt één keer en verloopt met het sjabloon. Na 5 mislukte pogingen wordt hij ongeldig en moet je een nieuwe aanvragen. reason kan invalid_code (met attempts_left), too_many_attempts of expired_or_not_found zijn. Een juiste code geeft { "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 telefoon: één verzending per 30 seconden en 5 per uur. Daarboven komt 429 OTP_RATE_LIMITED met de header Retry-After. De algemene limiet van 100 verzoeken per minuut per API-sleutel geldt ook.
| Code | HTTP | Wanneer |
|---|---|---|
TEMPLATE_NOT_APPROVED | 409 | Het OTP-sjabloon voor die taal bestaat niet of is nog niet door Meta goedgekeurd |
OTP_RATE_LIMITED | 429 | Te veel codes voor dat nummer; probeer opnieuw na Retry-After |
META_ERROR | 422 | Meta heeft het sjabloon afgewezen (bijvoorbeeld niet-geverifieerd bedrijf) |
SEND_FAILED | 422 | Meta heeft het bericht niet geaccepteerd |
VALIDATION_ERROR | 400 | Ongeldige body: telefoon, lengte, taal of code |
NOT_FOUND | 404 | De WhatsApp-lijn bestaat niet of hoort niet bij deze agent |