API
SMS y llamadas
Manda SMS y pide llamadas de la IA desde la línea telefónica de tu agente
# SMS y llamadas > Manda SMS y pide llamadas de la IA desde la línea telefónica de tu agente - Página: https://tbit.app/es/docs/api/sms-calls - URL base: `https://rest-api.tbit.app/v1` - Autenticación: encabezado `X-API-Key` con tu clave en cada solicitud (los ejemplos la leen de la variable de entorno `TBIT_API_KEY`) ## Descripción general Las dos salen por la línea telefónica de tu agente (la que compras en Plugins › Línea telefónica) y gastan energía de tu plan. Cada SMS enviado queda en el hilo del contacto en TBit (si el contacto no existe, se crea) y los SMS que te escriben aparecen en tu bandeja por el canal SMS. ## Endpoints | Método | Ruta | Descripción | | --- | --- | --- | | `POST` | `/v1/sms` | Enviar un SMS | | `POST` | `/v1/calls` | Pedir que la IA llame a un número | ## Requisitos - Una línea telefónica activa en el agente dueño de la clave API. - Energía suficiente: se revisa antes de enviar o llamar, y si no alcanza no sale nada (402). - Los SMS a números +1 (Estados Unidos, Canadá, Puerto Rico…) piden el registro 10DLC del negocio; hasta tenerlo, responden 422. Cada número tiene sus capacidades: si la línea no admite SMS hacia ese destino, la respuesta trae el motivo del operador (502). ## Enviar un SMS Campos: to (número en formato E.164, con + y código de país), text (hasta 1.530 caracteres) y from (opcional: una de las líneas del agente en E.164, o un remitente alfanumérico de 1 a 11 letras/números como "MiTienda", al que no se le puede responder y que no sirve para números +1; sin él, la línea más antigua). La respuesta dice cuántas partes ocupó y cuánta energía gastó. `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." }' ``` Respuesta: ```json { "id": "40319a3e-7e2c-4f4e-9b0e-2c1d5f8a9b10", "from": "+17869572575", "to": "+573001234567", "parts": 1, "energy": 3, "contact_id": "6ac9f1e6af6d42a269f21b15", "message_id": "6ac9f2a1af6d42a269f21c02" } ``` ## Energía de los SMS | Caso | Energía por parte | | --- | --- | | SMS enviado a un número +1 | 1 (requiere 10DLC) | | SMS enviado a cualquier otro país | `3` | | SMS recibido | `1` | Un SMS largo viaja en varias partes: hasta 160 caracteres es una sola; si tiene emojis o letras fuera del alfabeto GSM, hasta 70. Más que eso se cobra por cada parte. ## Pedir una llamada La IA de tu agente llama al número con el objetivo que le das en reason (hasta 2.000 caracteres). Campos: to (E.164), reason y contact_id (opcional: el contacto de TBit; sin él se busca por el número y, si no existe, se crea). La respuesta es 202: la llamada quedó pedida. Se cobran 6 de energía por minuto cuando termina; hoy solo se puede llamar a números de Colombia. Modo aviso: si mandas message (hasta 1.000 caracteres) en vez de reason, la llamada solo informa. La IA dice ese texto tal cual a los pocos segundos de contestar (sin esperar a que la persona hable), se despide y cuelga; no conversa ni responde preguntas. Con message, reason es opcional y sirve como contexto. La llamada sale por la línea de tu agente y se cobra igual: 6 de energía 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." }' ``` Respuesta: ```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 recibes Los SMS que te escriben a la línea aparecen en la bandeja de TBit como una conversación por SMS. La IA no los contesta. Cada uno gasta 1 de energía por parte. ## Límites Además del límite general de 100 solicitudes por minuto, cada uno de estos endpoints acepta hasta 30 por minuto por agente. ## Errores | Estado | Código | Descripción | | --- | --- | --- | | `409` | `NO_PHONE_LINE` | El agente no tiene una línea telefónica activa | | `422` | `DESTINATION_NOT_ALLOWED` | El destino todavía no está habilitado (los +1 piden 10DLC) | | `402` | `INSUFFICIENT_ENERGY` | No alcanza la energía; no se envió ni se llamó | | `502` | `PROVIDER_ERROR` | El operador rechazó el envío o la llamada; message trae su motivo |Las dos salen por la línea telefónica de tu agente (la que compras en Plugins › Línea telefónica) y gastan energía de tu plan. Cada SMS enviado queda en el hilo del contacto en TBit (si el contacto no existe, se crea) y los SMS que te escriben aparecen en tu bandeja por el canal SMS.
| Método | Ruta | Descripción |
|---|---|---|
| POST | /v1/sms | Enviar un SMS |
| POST | /v1/calls | Pedir que la IA llame a un número |
- Una línea telefónica activa en el agente dueño de la clave API.
- Energía suficiente: se revisa antes de enviar o llamar, y si no alcanza no sale nada (402).
- Los SMS a números +1 (Estados Unidos, Canadá, Puerto Rico…) piden el registro 10DLC del negocio; hasta tenerlo, responden 422. Cada número tiene sus capacidades: si la línea no admite SMS hacia ese destino, la respuesta trae el motivo del operador (502).
Campos: to (número en formato E.164, con + y código de país), text (hasta 1.530 caracteres) y from (opcional: una de las líneas del agente en E.164, o un remitente alfanumérico de 1 a 11 letras/números como "MiTienda", al que no se le puede responder y que no sirve para números +1; sin él, la línea más antigua). La respuesta dice cuántas partes ocupó y cuánta energía gastó.
/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 | Energía por parte |
|---|---|
| SMS enviado a un número +1 | 1 (requiere 10DLC) |
| SMS enviado a cualquier otro país | 3 |
| SMS recibido | 1 |
Un SMS largo viaja en varias partes: hasta 160 caracteres es una sola; si tiene emojis o letras fuera del alfabeto GSM, hasta 70. Más que eso se cobra por cada parte.
La IA de tu agente llama al número con el objetivo que le das en reason (hasta 2.000 caracteres). Campos: to (E.164), reason y contact_id (opcional: el contacto de TBit; sin él se busca por el número y, si no existe, se crea). La respuesta es 202: la llamada quedó pedida. Se cobran 6 de energía por minuto cuando termina; hoy solo se puede llamar a números de Colombia.
Modo aviso: si mandas message (hasta 1.000 caracteres) en vez de reason, la llamada solo informa. La IA dice ese texto tal cual a los pocos segundos de contestar (sin esperar a que la persona hable), se despide y cuelga; no conversa ni responde preguntas. Con message, reason es opcional y sirve como contexto. La llamada sale por la línea de tu agente y se cobra igual: 6 de energía 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);Los SMS que te escriben a la línea aparecen en la bandeja de TBit como una conversación por SMS. La IA no los contesta. Cada uno gasta 1 de energía por parte.
Además del límite general de 100 solicitudes por minuto, cada uno de estos endpoints acepta hasta 30 por minuto por agente.
| Estado | Código | Descripción |
|---|---|---|
409 | NO_PHONE_LINE | El agente no tiene una línea telefónica activa |
422 | DESTINATION_NOT_ALLOWED | El destino todavía no está habilitado (los +1 piden 10DLC) |
402 | INSUFFICIENT_ENERGY | No alcanza la energía; no se envió ni se llamó |
502 | PROVIDER_ERROR | El operador rechazó el envío o la llamada; message trae su motivo |