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