Vai al contenuto
Menu

Cerca nel sito

Scrivi per cercare tra guide, blog, API e prodotto.

↑ ↓ per spostarti · Invio per aprire · Esc per chiudere

Riferimento dell'API

API

OTP su WhatsApp

Invia codici di verifica su WhatsApp con il pulsante Copia codice

Vedi come Markdown

TBit genera un codice numerico, lo invia su WhatsApp dalla linea del tuo agente con un modello di autenticazione (pulsante «Copia codice») e te lo restituisce nella risposta. Puoi convalidarlo nel tuo sistema o chiedere a TBit di farlo con /v1/otp/verify. Gli OTP sono gratuiti e non consumano la tua quota di modelli.

MetodoPercorsoDescrizione
POST/v1/otp/templateCreare il modello di autenticazione
GET/v1/otp/templateStato dei modelli OTP
POST/v1/otp/sendGenerare e inviare un codice
POST/v1/otp/verifyVerificare un codice (facoltativo)

Serve una linea WhatsApp collegata al tuo agente. Meta consente i modelli di autenticazione solo alle aziende verificate in Meta Business (Impostazioni aziendali → Centro sicurezza); senza verifica, la creazione del modello risponde META_ERROR con «does not have permission to create message template». Il codice parte dal numero della linea dell'agente proprietario della chiave API.

Creare il modello

Una volta per lingua (si chiama tbit_otp_<lingua>). Il testo lo scrive Meta e non si può personalizzare: il codice, una raccomandazione di sicurezza e la validità nel piè di pagina. Campi facoltativi: language (es di default), code_expiration_minutes (da 1 a 90, 10 di default) e channel_id se l'agente ha più linee. Se il modello esiste già risponde created: false con il suo stato. Meta di solito lo approva in pochi secondi.

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);
Risposta
{
  "data": {
    "created": true,
    "template": {
      "id": "6ac60aeaa2a9ed0cd9ca7fd4",
      "name": "tbit_otp_es",
      "language": "es",
      "status": "PENDING",
      "rejected_reason": null,
      "code_expiration_minutes": 10,
      "channel_id": "691deef351c7513d0c6a2a6f"
    }
  }
}

Stato del modello

Elenca i modelli OTP dell'agente. Quelli non ancora approvati vengono verificati in tempo reale con Meta: status è PENDING, APPROVED o 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);
Risposta
{
  "data": [
    {
      "id": "6ac60aeaa2a9ed0cd9ca7fd4",
      "name": "tbit_otp_es",
      "language": "es",
      "status": "APPROVED",
      "rejected_reason": null,
      "code_expiration_minutes": 10,
      "channel_id": "691deef351c7513d0c6a2a6f"
    }
  ]
}

Inviare un codice

to è il telefono con prefisso internazionale (spazi, trattini e + sono accettati). length va da 4 a 8 cifre (6 di default) e language sceglie il modello (es di default). La risposta contiene il codice per il tuo sistema; il codice non viene salvato nella cronologia della chat.

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);
Risposta
{
  "data": {
    "request_id": "be4ffa6c-f45a-4410-b38a-882bd3edd9b3",
    "to": "573001234567",
    "code": "054381",
    "expires_in_minutes": 10,
    "expires_at": "2026-10-07T09:17:26.278Z"
  }
}

Facoltativo: se non vuoi conservare il codice, lo convalida TBit. Ogni codice vale una sola volta e scade con il modello. Dopo 5 tentativi errati viene invalidato e bisogna richiederne un altro. reason può essere invalid_code (con attempts_left), too_many_attempts o expired_or_not_found. Un codice corretto risponde { "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);
Risposta
{
  "data": {
    "valid": false,
    "reason": "invalid_code",
    "attempts_left": 4
  }
}

Per telefono: un invio ogni 30 secondi e 5 all'ora. Oltre risponde 429 OTP_RATE_LIMITED con l'intestazione Retry-After. Vale anche il limite generale di 100 richieste al minuto per chiave API.

CodiceHTTPQuando
TEMPLATE_NOT_APPROVED409Il modello OTP di quella lingua non esiste o Meta non l'ha ancora approvato
OTP_RATE_LIMITED429Troppi codici per quel telefono; riprova secondo Retry-After
META_ERROR422Meta ha rifiutato il modello (ad esempio, azienda non verificata)
SEND_FAILED422Meta non ha accettato l'invio del messaggio
VALIDATION_ERROR400Corpo non valido: telefono, lunghezza, lingua o codice
NOT_FOUND404La linea WhatsApp non esiste o non appartiene a questo agente