Saltar al contenido
Menú

Buscar en el sitio

Escribe para buscar en guías, blog, API y producto.

↑ ↓ para moverte · Enter para abrir · Esc para cerrar

Referencia de la API

API

SMS y llamadas

Manda SMS y pide llamadas de la IA desde la línea telefónica de tu agente

Ver como Markdown

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étodoRutaDescripción
POST/v1/smsEnviar un SMS
POST/v1/callsPedir 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).

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
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."
  }'
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);
Respuesta
{
  "id": "40319a3e-7e2c-4f4e-9b0e-2c1d5f8a9b10",
  "from": "+17869572575",
  "to": "+573001234567",
  "parts": 1,
  "energy": 3,
  "contact_id": "6ac9f1e6af6d42a269f21b15",
  "message_id": "6ac9f2a1af6d42a269f21c02"
}
CasoEnergía por parte
SMS enviado a un número +11 (requiere 10DLC)
SMS enviado a cualquier otro país3
SMS recibido1

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.

POST/v1/calls
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."
  }'
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);
Respuesta
{
  "call_id": "6ac9f3b7af6d42a269f21c10",
  "provider_call_id": "conv_8f2k1x",
  "from": "+576019190351",
  "to": "+573001234567",
  "contact_id": "6ac9f1e6af6d42a269f21b15",
  "status": "requested"
}

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.

EstadoCódigoDescripción
409NO_PHONE_LINEEl agente no tiene una línea telefónica activa
422DESTINATION_NOT_ALLOWEDEl destino todavía no está habilitado (los +1 piden 10DLC)
402INSUFFICIENT_ENERGYNo alcanza la energía; no se envió ni se llamó
502PROVIDER_ERROREl operador rechazó el envío o la llamada; message trae su motivo