Naar de inhoud
Menu

Zoeken op de site

Typ om te zoeken in handleidingen, blog, API en product.

↑ ↓ om te bewegen · Enter om te openen · Esc om te sluiten

API-referentie

API

WhatsApp-OTP

Verstuur verificatiecodes via WhatsApp met een knop Code kopiëren

Bekijken als Markdown

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.

MethodePadBeschrijving
POST/v1/otp/templateHet authenticatiesjabloon aanmaken
GET/v1/otp/templateStatus van de OTP-sjablonen
POST/v1/otp/sendEen code genereren en versturen
POST/v1/otp/verifyEen 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.

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
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"
    }
  }
}

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
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"
    }
  ]
}

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
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"
  }
}

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
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 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.

CodeHTTPWanneer
TEMPLATE_NOT_APPROVED409Het OTP-sjabloon voor die taal bestaat niet of is nog niet door Meta goedgekeurd
OTP_RATE_LIMITED429Te veel codes voor dat nummer; probeer opnieuw na Retry-After
META_ERROR422Meta heeft het sjabloon afgewezen (bijvoorbeeld niet-geverifieerd bedrijf)
SEND_FAILED422Meta heeft het bericht niet geaccepteerd
VALIDATION_ERROR400Ongeldige body: telefoon, lengte, taal of code
NOT_FOUND404De WhatsApp-lijn bestaat niet of hoort niet bij deze agent