# SMS and calls

> Send SMS and request AI calls from your agent's phone line

- Page: https://tbit.app/docs/api/sms-calls
- Base URL: `https://rest-api.tbit.app/v1`
- Authentication: `X-API-Key` header with your key on every request (the examples read it from the `TBIT_API_KEY` environment variable)

## Overview

Both go out through your agent's phone line (the one you buy in Plugins › Phone line) and use energy from your plan. Every SMS you send is saved in the contact's thread in TBit (the contact is created if it doesn't exist), and SMS people send you show up in your inbox on the SMS channel.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/v1/sms` | Send an SMS |
| `POST` | `/v1/calls` | Have the AI call a number |

## Requirements

- An active phone line on the agent that owns the API key.
- Enough energy: it is checked before sending or calling, and nothing goes out if it doesn't cover it (402).
- SMS to +1 numbers (United States, Canada, Puerto Rico…) need the business's 10DLC registration; until then they return 422. Each number has its own capabilities: if the line can't send SMS to that destination, the response carries the carrier's reason (502).

## Send an SMS

Fields: to (number in E.164 format, with + and country code), text (up to 1,530 characters) and from (optional: one of the agent's lines in E.164, or an alphanumeric sender of 1 to 11 letters/numbers such as "MiTienda", which cannot receive replies and does not work for +1 numbers; without it, the oldest line). The response says how many parts it took and how much energy it used.

`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."
  }'
```

Response:

```json
{
  "id": "40319a3e-7e2c-4f4e-9b0e-2c1d5f8a9b10",
  "from": "+17869572575",
  "to": "+573001234567",
  "parts": 1,
  "energy": 3,
  "contact_id": "6ac9f1e6af6d42a269f21b15",
  "message_id": "6ac9f2a1af6d42a269f21c02"
}
```

## SMS energy

| Case | Energy per part |
| --- | --- |
| SMS sent to a +1 number | 1 (needs 10DLC) |
| SMS sent to any other country | `3` |
| SMS received | `1` |

A long SMS travels in several parts: up to 160 characters is one; with emoji or letters outside the GSM alphabet, up to 70. Beyond that, each part is charged.

## Request a call

Your agent's AI calls the number with the goal you give in reason (up to 2,000 characters). Fields: to (E.164), reason and contact_id (optional: the TBit contact; without it, the contact is looked up by number and created if missing). The response is 202: the call was requested. It costs 6 energy per minute, charged when it ends; for now only numbers in Colombia can be called.

Notice mode: if you send message (up to 1,000 characters) instead of reason, the call only informs. The AI says that text as is within seconds of answering (without waiting for the person to speak), says goodbye and hangs up; it does not converse or answer questions. With message, reason is optional and serves as context. The call goes out on your agent's line and is charged the same: 6 energy per started minute.

`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."
  }'
```

Response:

```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 you receive

SMS sent to your line appear in the TBit inbox as one conversation per SMS. The AI does not answer them. Each one uses 1 energy per part.

## Limits

In addition to the general limit of 100 requests per minute, each of these endpoints accepts up to 30 per minute per agent.

## Errors

| Status | Code | Description |
| --- | --- | --- |
| `409` | `NO_PHONE_LINE` | The agent does not have an active phone line |
| `422` | `DESTINATION_NOT_ALLOWED` | The destination is not enabled yet (+1 numbers require 10DLC) |
| `402` | `INSUFFICIENT_ENERGY` | Not enough energy; nothing was sent or called |
| `502` | `PROVIDER_ERROR` | The carrier rejected the send or the call; message contains its reason |
