# Sms en oproepen

> Verstuur sms en laat de AI bellen via de telefoonlijn van je agent

- Pagina: https://tbit.app/nl/docs/api/sms-calls
- Basis-URL: `https://rest-api.tbit.app/v1`
- Authenticatie: header `X-API-Key` met je sleutel bij elk verzoek (de voorbeelden lezen hem uit de omgevingsvariabele `TBIT_API_KEY`)

## Overzicht

Beide gaan via de telefoonlijn van je agent (die je koopt in Plugins › Telefoonlijn) en gebruiken energie van je abonnement. Elke verstuurde sms komt in het gesprek van het contact in TBit (het contact wordt aangemaakt als het niet bestaat) en sms die je ontvangt verschijnen in je inbox via het sms-kanaal.

## Endpoints

| Methode | Pad | Beschrijving |
| --- | --- | --- |
| `POST` | `/v1/sms` | Een sms versturen |
| `POST` | `/v1/calls` | De AI een nummer laten bellen |

## Vereisten

- Een actieve telefoonlijn op de agent die eigenaar is van de API-sleutel.
- Genoeg energie: dit wordt gecontroleerd vóór het versturen of bellen, en als het niet genoeg is, gaat er niets uit (402).
- Sms naar +1-nummers (Verenigde Staten, Canada, Puerto Rico…) vereisen de 10DLC-registratie van het bedrijf; tot die tijd geven ze 422. Elk nummer heeft eigen mogelijkheden: als de lijn geen sms naar die bestemming kan sturen, geeft het antwoord de reden van de provider (502).

## Een sms versturen

Velden: to (nummer in E.164-formaat, met + en landcode), text (tot 1.530 tekens) en from (optioneel: een van de lijnen van de agent in E.164, of een alfanumerieke afzender van 1 tot 11 letters/cijfers zoals "MiTienda", die niet beantwoord kan worden en niet werkt voor +1-nummers; zonder dit veld wordt de oudste lijn gebruikt). Het antwoord zegt hoeveel delen er gebruikt zijn en hoeveel energie er verbruikt is.

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

## Energie voor sms

| Geval | Energie per deel |
| --- | --- |
| Sms naar een +1-nummer | 1 (vereist 10DLC) |
| Sms naar elk ander land | `3` |
| Ontvangen sms | `1` |

Een lange sms gaat in meerdere delen: tot 160 tekens is het er één; met emoji of letters buiten het GSM-alfabet tot 70. Daarboven wordt elk deel gerekend.

## Een oproep aanvragen

De AI van je agent belt het nummer met het doel dat je in reason opgeeft (tot 2.000 tekens). Velden: to (E.164), reason en contact_id (optioneel: het TBit-contact; zonder dit wordt het contact op nummer gezocht en zo nodig aangemaakt). Het antwoord is 202: de oproep is aangevraagd. Het kost 6 energie per minuut, gerekend aan het einde; voorlopig kunnen alleen nummers in Colombia gebeld worden.

Meldingsmodus: als je message (tot 1.000 tekens) meestuurt in plaats van reason, doet de oproep alleen een melding. De AI zegt die tekst letterlijk een paar seconden na het opnemen (zonder te wachten tot de persoon praat), neemt afscheid en hangt op; er wordt niet gesproken en er worden geen vragen beantwoord. Met message is reason optioneel en dient het als context. De oproep gaat via de lijn van je agent en wordt hetzelfde gefactureerd: 6 energie per begonnen minuut.

`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 die je ontvangt

Sms'jes die je naar de lijn stuurt, verschijnen in de inbox van TBit als een gesprek per sms. De AI beantwoordt ze niet. Elk bericht kost 1 energie per deel.

## Limieten

Naast de algemene limiet van 100 verzoeken per minuut accepteert elk van deze endpoints tot 30 per minuut per agent.

## Fouten

| Status | Code | Beschrijving |
| --- | --- | --- |
| `409` | `NO_PHONE_LINE` | De agent heeft geen actieve telefoonlijn |
| `422` | `DESTINATION_NOT_ALLOWED` | Het doel is nog niet ingeschakeld (de +1-nummers vragen om 10DLC) |
| `402` | `INSUFFICIENT_ENERGY` | Niet genoeg energie; er is niets verzonden en niet gebeld |
| `502` | `PROVIDER_ERROR` | De operator weigerde het verzenden of het gesprek; message bevat de reden |
