API
SMS e chiamate
Invia SMS e chiedi chiamate dell'IA dalla linea telefonica del tuo agente
# SMS e chiamate > Invia SMS e chiedi chiamate dell'IA dalla linea telefonica del tuo agente - Pagina: https://tbit.app/it/docs/api/sms-calls - URL base: `https://rest-api.tbit.app/v1` - Autenticazione: header `X-API-Key` con la tua chiave in ogni richiesta (gli esempi la leggono dalla variabile d'ambiente `TBIT_API_KEY`) ## Panoramica Entrambi passano dalla linea telefonica del tuo agente (quella che acquisti in Plugins › Linea telefonica) e usano energia del tuo piano. Ogni SMS inviato resta nella conversazione del contatto su TBit (se il contatto non esiste, viene creato) e gli SMS che ricevi compaiono nella tua casella sul canale SMS. ## Endpoint | Metodo | Percorso | Descrizione | | --- | --- | --- | | `POST` | `/v1/sms` | Inviare un SMS | | `POST` | `/v1/calls` | Far chiamare un numero dall'IA | ## Requisiti - Una linea telefonica attiva sull'agente proprietario della chiave API. - Energia sufficiente: viene verificata prima di inviare o chiamare e, se non basta, non parte nulla (402). - Gli SMS verso numeri +1 (Stati Uniti, Canada, Porto Rico…) richiedono la registrazione 10DLC dell'azienda; fino ad allora rispondono 422. Ogni numero ha le sue capacità: se la linea non invia SMS verso quella destinazione, la risposta riporta il motivo dell'operatore (502). ## Inviare un SMS Campi: to (numero in formato E.164, con + e codice paese), text (fino a 1.530 caratteri) e from (opzionale: una delle linee dell'agente in E.164, oppure un mittente alfanumerico da 1 a 11 lettere/numeri come "MiTienda", a cui non si può rispondere e che non è valido per i numeri +1; senza di esso, la linea più vecchia). La risposta indica quante parti ha occupato e quanta energia ha consumato. `POST /v1/sms` ```bash curl -X POST "https://rest-api.tbit.app/v1/sms" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+573001234567", "text": "Hola Ana, tu pedido #1042 sale hoy." }' ``` Risposta: ```json { "id": "40319a3e-7e2c-4f4e-9b0e-2c1d5f8a9b10", "from": "+17869572575", "to": "+573001234567", "parts": 1, "energy": 3, "contact_id": "6ac9f1e6af6d42a269f21b15", "message_id": "6ac9f2a1af6d42a269f21c02" } ``` ## Energia degli SMS | Caso | Energia per parte | | --- | --- | | SMS inviato a un numero +1 | 1 (richiede 10DLC) | | SMS inviato a qualsiasi altro paese | `3` | | SMS ricevuto | `1` | Un SMS lungo viaggia in più parti: fino a 160 caratteri è una sola; con emoji o lettere fuori dall'alfabeto GSM, fino a 70. Oltre, ogni parte viene addebitata. ## Chiedere una chiamata L'IA del tuo agente chiama il numero con l'obiettivo che indichi in reason (fino a 2.000 caratteri). Campi: to (E.164), reason e contact_id (facoltativo: il contatto TBit; senza, il contatto viene cercato per numero e, se non esiste, creato). La risposta è 202: la chiamata è stata richiesta. Costa 6 di energia al minuto, addebitati alla fine; per ora si possono chiamare solo numeri della Colombia. Modalità avviso: se invii message (fino a 1.000 caratteri) invece di reason, la chiamata si limita a informare. L'IA dice quel testo così com'è pochi secondi dopo la risposta (senza aspettare che la persona parli), saluta e riaggancia; non conversa né risponde alle domande. Con message, reason è facoltativo e serve come contesto. La chiamata parte dalla linea del tuo agente e si addebita allo stesso modo: 6 di energia per minuto iniziato. `POST /v1/calls` ```bash curl -X POST "https://rest-api.tbit.app/v1/calls" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+573001234567", "reason": "Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede." }' ``` Risposta: ```json { "call_id": "6ac9f3b7af6d42a269f21c10", "provider_call_id": "conv_8f2k1x", "from": "+576019190351", "to": "+573001234567", "contact_id": "6ac9f1e6af6d42a269f21b15", "status": "requested" } ``` `POST /v1/calls` ```bash curl -X POST "https://rest-api.tbit.app/v1/calls" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+573001234567", "message": "Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta." }' ``` ## SMS che ricevi Gli SMS che scrivono alla tua linea compaiono nella casella di TBit come una conversazione via SMS. L'IA non li risponde. Ognuno consuma 1 di energia per parte. ## Limiti Oltre al limite generale di 100 richieste al minuto, ciascuno di questi endpoint accetta fino a 30 al minuto per agente. ## Errori | Stato | Codice | Descrizione | | --- | --- | --- | | `409` | `NO_PHONE_LINE` | L'agente non ha una linea telefonica attiva | | `422` | `DESTINATION_NOT_ALLOWED` | La destinazione non è ancora abilitata (i +1 richiedono 10DLC) | | `402` | `INSUFFICIENT_ENERGY` | L'energia non basta; non è stato inviato né chiamato | | `502` | `PROVIDER_ERROR` | L'operatore ha rifiutato l'invio o la chiamata; message riporta il motivo |Entrambi passano dalla linea telefonica del tuo agente (quella che acquisti in Plugins › Linea telefonica) e usano energia del tuo piano. Ogni SMS inviato resta nella conversazione del contatto su TBit (se il contatto non esiste, viene creato) e gli SMS che ricevi compaiono nella tua casella sul canale SMS.
| Metodo | Percorso | Descrizione |
|---|---|---|
| POST | /v1/sms | Inviare un SMS |
| POST | /v1/calls | Far chiamare un numero dall'IA |
- Una linea telefonica attiva sull'agente proprietario della chiave API.
- Energia sufficiente: viene verificata prima di inviare o chiamare e, se non basta, non parte nulla (402).
- Gli SMS verso numeri +1 (Stati Uniti, Canada, Porto Rico…) richiedono la registrazione 10DLC dell'azienda; fino ad allora rispondono 422. Ogni numero ha le sue capacità: se la linea non invia SMS verso quella destinazione, la risposta riporta il motivo dell'operatore (502).
Campi: to (numero in formato E.164, con + e codice paese), text (fino a 1.530 caratteri) e from (opzionale: una delle linee dell'agente in E.164, oppure un mittente alfanumerico da 1 a 11 lettere/numeri come "MiTienda", a cui non si può rispondere e che non è valido per i numeri +1; senza di esso, la linea più vecchia). La risposta indica quante parti ha occupato e quanta energia ha consumato.
/v1/smscurl -X POST "https://rest-api.tbit.app/v1/sms" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+573001234567",
"text": "Hola Ana, tu pedido #1042 sale hoy."
}'const response = await fetch('https://rest-api.tbit.app/v1/sms', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+573001234567',
text: 'Hola Ana, tu pedido #1042 sale hoy.',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/sms',
{
to: '+573001234567',
text: 'Hola Ana, tu pedido #1042 sale hoy.',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/sms',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '+573001234567',
'text': 'Hola Ana, tu pedido #1042 sale hoy.',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/sms');
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',
'text' => 'Hola Ana, tu pedido #1042 sale hoy.',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"id": "40319a3e-7e2c-4f4e-9b0e-2c1d5f8a9b10",
"from": "+17869572575",
"to": "+573001234567",
"parts": 1,
"energy": 3,
"contact_id": "6ac9f1e6af6d42a269f21b15",
"message_id": "6ac9f2a1af6d42a269f21c02"
}| Caso | Energia per parte |
|---|---|
| SMS inviato a un numero +1 | 1 (richiede 10DLC) |
| SMS inviato a qualsiasi altro paese | 3 |
| SMS ricevuto | 1 |
Un SMS lungo viaggia in più parti: fino a 160 caratteri è una sola; con emoji o lettere fuori dall'alfabeto GSM, fino a 70. Oltre, ogni parte viene addebitata.
L'IA del tuo agente chiama il numero con l'obiettivo che indichi in reason (fino a 2.000 caratteri). Campi: to (E.164), reason e contact_id (facoltativo: il contatto TBit; senza, il contatto viene cercato per numero e, se non esiste, creato). La risposta è 202: la chiamata è stata richiesta. Costa 6 di energia al minuto, addebitati alla fine; per ora si possono chiamare solo numeri della Colombia.
Modalità avviso: se invii message (fino a 1.000 caratteri) invece di reason, la chiamata si limita a informare. L'IA dice quel testo così com'è pochi secondi dopo la risposta (senza aspettare che la persona parli), saluta e riaggancia; non conversa né risponde alle domande. Con message, reason è facoltativo e serve come contesto. La chiamata parte dalla linea del tuo agente e si addebita allo stesso modo: 6 di energia per minuto iniziato.
/v1/callscurl -X POST "https://rest-api.tbit.app/v1/calls" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+573001234567",
"reason": "Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede."
}'const response = await fetch('https://rest-api.tbit.app/v1/calls', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+573001234567',
reason: 'Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede.',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/calls',
{
to: '+573001234567',
reason: 'Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede.',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/calls',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '+573001234567',
'reason': 'Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede.',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/calls');
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',
'reason' => 'Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede.',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"call_id": "6ac9f3b7af6d42a269f21c10",
"provider_call_id": "conv_8f2k1x",
"from": "+576019190351",
"to": "+573001234567",
"contact_id": "6ac9f1e6af6d42a269f21b15",
"status": "requested"
}/v1/callscurl -X POST "https://rest-api.tbit.app/v1/calls" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+573001234567",
"message": "Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta."
}'const response = await fetch('https://rest-api.tbit.app/v1/calls', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+573001234567',
message: 'Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta.',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/calls',
{
to: '+573001234567',
message: 'Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta.',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/calls',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '+573001234567',
'message': 'Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta.',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/calls');
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',
'message' => 'Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta.',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);Gli SMS che scrivono alla tua linea compaiono nella casella di TBit come una conversazione via SMS. L'IA non li risponde. Ognuno consuma 1 di energia per parte.
Oltre al limite generale di 100 richieste al minuto, ciascuno di questi endpoint accetta fino a 30 al minuto per agente.
| Stato | Codice | Descrizione |
|---|---|---|
409 | NO_PHONE_LINE | L'agente non ha una linea telefonica attiva |
422 | DESTINATION_NOT_ALLOWED | La destinazione non è ancora abilitata (i +1 richiedono 10DLC) |
402 | INSUFFICIENT_ENERGY | L'energia non basta; non è stato inviato né chiamato |
502 | PROVIDER_ERROR | L'operatore ha rifiutato l'invio o la chiamata; message riporta il motivo |