# SMS und Anrufe

> Senden Sie SMS und lassen Sie die KI über die Telefonleitung Ihres Agenten anrufen

- Seite: https://tbit.app/de/docs/api/sms-calls
- Basis-URL: `https://rest-api.tbit.app/v1`
- Authentifizierung: Header `X-API-Key` mit deinem Schlüssel in jeder Anfrage (die Beispiele lesen ihn aus der Umgebungsvariable `TBIT_API_KEY`)

## Überblick

Beides läuft über die Telefonleitung Ihres Agenten (die Sie unter Plugins › Telefonleitung kaufen) und verbraucht Energie aus Ihrem Plan. Jede gesendete SMS wird im Verlauf des Kontakts in TBit gespeichert (der Kontakt wird angelegt, falls er fehlt), und SMS, die Sie erhalten, erscheinen in Ihrem Posteingang im SMS-Kanal.

## Endpunkte

| Methode | Pfad | Beschreibung |
| --- | --- | --- |
| `POST` | `/v1/sms` | Eine SMS senden |
| `POST` | `/v1/calls` | Die KI eine Nummer anrufen lassen |

## Voraussetzungen

- Eine aktive Telefonleitung beim Agenten, dem der API-Schlüssel gehört.
- Genug Energie: Sie wird vor dem Senden oder Anrufen geprüft; reicht sie nicht, geht nichts raus (402).
- SMS an +1-Nummern (USA, Kanada, Puerto Rico…) brauchen die 10DLC-Registrierung des Unternehmens; bis dahin antworten sie mit 422. Jede Nummer hat eigene Fähigkeiten: Kann die Leitung keine SMS an dieses Ziel senden, enthält die Antwort den Grund des Netzbetreibers (502).

## Eine SMS senden

Felder: to (Nummer im E.164-Format, mit + und Ländercode), text (bis zu 1.530 Zeichen) und from (optional: eine der Leitungen des Agenten in E.164, oder ein alphanumerischer Absender mit 1 bis 11 Buchstaben/Ziffern wie "MiTienda", auf den nicht geantwortet werden kann und der nicht für +1-Nummern funktioniert; ohne ihn die älteste Leitung). Die Antwort sagt, wie viele Teile belegt wurden und wie viel Energie verbraucht wurde.

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

Antwort:

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

## Energie für SMS

| Fall | Energie pro Teil |
| --- | --- |
| SMS an eine +1-Nummer | 1 (braucht 10DLC) |
| SMS in jedes andere Land | `3` |
| Empfangene SMS | `1` |

Eine lange SMS wird in mehreren Teilen übertragen: bis 160 Zeichen ist es einer; mit Emojis oder Buchstaben außerhalb des GSM-Alphabets bis 70. Darüber wird jeder Teil berechnet.

## Einen Anruf anfordern

Die KI Ihres Agenten ruft die Nummer mit dem Ziel an, das Sie in reason angeben (bis zu 2.000 Zeichen). Felder: to (E.164), reason und contact_id (optional: der TBit-Kontakt; ohne Angabe wird der Kontakt über die Nummer gesucht und bei Bedarf angelegt). Die Antwort ist 202: Der Anruf wurde angefordert. Er kostet 6 Energie pro Minute, berechnet am Ende; derzeit können nur Nummern in Kolumbien angerufen werden.

Hinweis-Modus: Wenn du statt reason eine message (bis zu 1.000 Zeichen) sendest, informiert der Anruf nur. Die KI sagt diesen Text wenige Sekunden nach dem Abheben wörtlich auf (ohne zu warten, bis die Person spricht), verabschiedet sich und legt auf; sie führt kein Gespräch und beantwortet keine Fragen. Bei message ist reason optional und dient als Kontext. Der Anruf geht über die Leitung deines Agenten und wird gleich berechnet: 6 Energie pro angefangene 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."
  }'
```

Antwort:

```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 du erhältst

SMS, die an deine Leitung geschrieben werden, erscheinen im TBit-Posteingang als SMS-Konversation. Die KI beantwortet sie nicht. Jede kostet 1 Energie pro Teil.

## Limits

Zusätzlich zum allgemeinen Limit von 100 Anfragen pro Minute akzeptiert jeder dieser Endpunkte bis zu 30 pro Minute pro Agent.

## Fehler

| Status | Code | Beschreibung |
| --- | --- | --- |
| `409` | `NO_PHONE_LINE` | Der Agent hat keine aktive Telefonleitung |
| `422` | `DESTINATION_NOT_ALLOWED` | Das Ziel ist noch nicht freigeschaltet (+1 benötigen 10DLC) |
| `402` | `INSUFFICIENT_ENERGY` | Nicht genug Energie; weder gesendet noch angerufen |
| `502` | `PROVIDER_ERROR` | Der Anbieter hat den Versand oder den Anruf abgelehnt; message enthält den Grund |
