API
SMS e chamadas
Envie SMS e peça chamadas da IA pela linha telefônica do seu agente
# SMS e chamadas > Envie SMS e peça chamadas da IA pela linha telefônica do seu agente - Página: https://tbit.app/pt/docs/api/sms-calls - URL base: `https://rest-api.tbit.app/v1` - Autenticação: cabeçalho `X-API-Key` com a sua chave em cada requisição (os exemplos a leem da variável de ambiente `TBIT_API_KEY`) ## Visão geral Os dois saem pela linha telefônica do seu agente (a que você compra em Plugins › Linha telefônica) e usam energia do seu plano. Cada SMS enviado fica na conversa do contato na TBit (se o contato não existir, ele é criado) e os SMS que você recebe aparecem na sua caixa de entrada pelo canal SMS. ## Endpoints | Método | Rota | Descrição | | --- | --- | --- | | `POST` | `/v1/sms` | Enviar um SMS | | `POST` | `/v1/calls` | Pedir que a IA ligue para um número | ## Requisitos - Uma linha telefônica ativa no agente dono da chave API. - Energia suficiente: é verificada antes de enviar ou ligar, e se não der, nada sai (402). - SMS para números +1 (Estados Unidos, Canadá, Porto Rico…) exigem o registro 10DLC da empresa; até lá, respondem 422. Cada número tem suas capacidades: se a linha não envia SMS para esse destino, a resposta traz o motivo da operadora (502). ## Enviar um SMS Campos: to (número no formato E.164, com + e código do país), text (até 1.530 caracteres) e from (opcional: uma das linhas do agente em E.164, ou um remetente alfanumérico de 1 a 11 letras/números como "MiTienda", ao qual não se pode responder e que não serve para números +1; sem ele, a linha mais antiga). A resposta diz quantas partes ocupou e quanta energia gastou. `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." }' ``` Resposta: ```json { "id": "40319a3e-7e2c-4f4e-9b0e-2c1d5f8a9b10", "from": "+17869572575", "to": "+573001234567", "parts": 1, "energy": 3, "contact_id": "6ac9f1e6af6d42a269f21b15", "message_id": "6ac9f2a1af6d42a269f21c02" } ``` ## Energia dos SMS | Caso | Energia por parte | | --- | --- | | SMS enviado para um número +1 | 1 (exige 10DLC) | | SMS enviado para qualquer outro país | `3` | | SMS recebido | `1` | Um SMS longo viaja em várias partes: até 160 caracteres é uma só; com emojis ou letras fora do alfabeto GSM, até 70. Acima disso, cada parte é cobrada. ## Pedir uma chamada A IA do seu agente liga para o número com o objetivo que você dá em reason (até 2.000 caracteres). Campos: to (E.164), reason e contact_id (opcional: o contato da TBit; sem ele, o contato é buscado pelo número e, se não existir, é criado). A resposta é 202: a chamada foi pedida. Custa 6 de energia por minuto, cobrados ao terminar; por enquanto só é possível ligar para números da Colômbia. Modo aviso: se você enviar message (até 1.000 caracteres) em vez de reason, a chamada apenas informa. A IA diz esse texto exatamente como está alguns segundos após atender (sem esperar a pessoa falar), se despede e desliga; não conversa nem responde perguntas. Com message, reason é opcional e serve como contexto. A chamada sai pela linha do seu agente e é cobrada igual: 6 de energia por minuto iniciado. `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." }' ``` Resposta: ```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 que você recebe Os SMS que escrevem para a sua linha aparecem na caixa de entrada do TBit como uma conversa por SMS. A IA não os responde. Cada um gasta 1 de energia por parte. ## Limites Além do limite geral de 100 requisições por minuto, cada um destes endpoints aceita até 30 por minuto por agente. ## Erros | Status | Código | Descrição | | --- | --- | --- | | `409` | `NO_PHONE_LINE` | O agente não tem uma linha telefônica ativa | | `422` | `DESTINATION_NOT_ALLOWED` | O destino ainda não está habilitado (os +1 pedem 10DLC) | | `402` | `INSUFFICIENT_ENERGY` | A energia não é suficiente; não foi enviado nem chamado | | `502` | `PROVIDER_ERROR` | A operadora rejeitou o envio ou a chamada; message traz o motivo |Os dois saem pela linha telefônica do seu agente (a que você compra em Plugins › Linha telefônica) e usam energia do seu plano. Cada SMS enviado fica na conversa do contato na TBit (se o contato não existir, ele é criado) e os SMS que você recebe aparecem na sua caixa de entrada pelo canal SMS.
| Método | Rota | Descrição |
|---|---|---|
| POST | /v1/sms | Enviar um SMS |
| POST | /v1/calls | Pedir que a IA ligue para um número |
- Uma linha telefônica ativa no agente dono da chave API.
- Energia suficiente: é verificada antes de enviar ou ligar, e se não der, nada sai (402).
- SMS para números +1 (Estados Unidos, Canadá, Porto Rico…) exigem o registro 10DLC da empresa; até lá, respondem 422. Cada número tem suas capacidades: se a linha não envia SMS para esse destino, a resposta traz o motivo da operadora (502).
Campos: to (número no formato E.164, com + e código do país), text (até 1.530 caracteres) e from (opcional: uma das linhas do agente em E.164, ou um remetente alfanumérico de 1 a 11 letras/números como "MiTienda", ao qual não se pode responder e que não serve para números +1; sem ele, a linha mais antiga). A resposta diz quantas partes ocupou e quanta energia gastou.
/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 por parte |
|---|---|
| SMS enviado para um número +1 | 1 (exige 10DLC) |
| SMS enviado para qualquer outro país | 3 |
| SMS recebido | 1 |
Um SMS longo viaja em várias partes: até 160 caracteres é uma só; com emojis ou letras fora do alfabeto GSM, até 70. Acima disso, cada parte é cobrada.
A IA do seu agente liga para o número com o objetivo que você dá em reason (até 2.000 caracteres). Campos: to (E.164), reason e contact_id (opcional: o contato da TBit; sem ele, o contato é buscado pelo número e, se não existir, é criado). A resposta é 202: a chamada foi pedida. Custa 6 de energia por minuto, cobrados ao terminar; por enquanto só é possível ligar para números da Colômbia.
Modo aviso: se você enviar message (até 1.000 caracteres) em vez de reason, a chamada apenas informa. A IA diz esse texto exatamente como está alguns segundos após atender (sem esperar a pessoa falar), se despede e desliga; não conversa nem responde perguntas. Com message, reason é opcional e serve como contexto. A chamada sai pela linha do seu agente e é cobrada igual: 6 de energia por minuto iniciado.
/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);Os SMS que escrevem para a sua linha aparecem na caixa de entrada do TBit como uma conversa por SMS. A IA não os responde. Cada um gasta 1 de energia por parte.
Além do limite geral de 100 requisições por minuto, cada um destes endpoints aceita até 30 por minuto por agente.
| Status | Código | Descrição |
|---|---|---|
409 | NO_PHONE_LINE | O agente não tem uma linha telefônica ativa |
422 | DESTINATION_NOT_ALLOWED | O destino ainda não está habilitado (os +1 pedem 10DLC) |
402 | INSUFFICIENT_ENERGY | A energia não é suficiente; não foi enviado nem chamado |
502 | PROVIDER_ERROR | A operadora rejeitou o envio ou a chamada; message traz o motivo |