# 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 |
