# SMS et appels

> Envoyez des SMS et demandez des appels de l'IA depuis la ligne téléphonique de votre agent

- Page: https://tbit.app/fr/docs/api/sms-calls
- URL de base: `https://rest-api.tbit.app/v1`
- Authentification: en-tête `X-API-Key` avec votre clé dans chaque requête (les exemples la lisent depuis la variable d'environnement `TBIT_API_KEY`)

## Vue d'ensemble

Les deux passent par la ligne téléphonique de votre agent (celle que vous achetez dans Plugins › Ligne téléphonique) et consomment l'énergie de votre forfait. Chaque SMS envoyé est enregistré dans la conversation du contact sur TBit (le contact est créé s'il n'existe pas), et les SMS que l'on vous envoie arrivent dans votre boîte de réception sur le canal SMS.

## Endpoints

| Méthode | Chemin | Description |
| --- | --- | --- |
| `POST` | `/v1/sms` | Envoyer un SMS |
| `POST` | `/v1/calls` | Faire appeler un numéro par l'IA |

## Prérequis

- Une ligne téléphonique active sur l'agent propriétaire de la clé API.
- Assez d'énergie : elle est vérifiée avant d'envoyer ou d'appeler, et rien ne part si elle ne suffit pas (402).
- Les SMS vers des numéros +1 (États-Unis, Canada, Porto Rico…) exigent l'enregistrement 10DLC de l'entreprise ; d'ici là, ils répondent 422. Chaque numéro a ses capacités : si la ligne n'envoie pas de SMS vers cette destination, la réponse donne le motif de l'opérateur (502).

## Envoyer un SMS

Champs : to (numéro au format E.164, avec + et indicatif pays), text (jusqu'à 1 530 caractères) et from (facultatif : une des lignes de l'agent en E.164, ou un expéditeur alphanumérique de 1 à 11 lettres/chiffres comme "MiTienda", auquel on ne peut pas répondre et qui ne fonctionne pas pour les numéros +1 ; sans lui, la ligne la plus ancienne). La réponse indique combien de parties ont été utilisées et combien d'énergie a été consommée.

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

Réponse:

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

## Énergie des SMS

| Cas | Énergie par partie |
| --- | --- |
| SMS envoyé vers un numéro +1 | 1 (exige 10DLC) |
| SMS envoyé vers tout autre pays | `3` |
| SMS reçu | `1` |

Un SMS long voyage en plusieurs parties : jusqu'à 160 caractères, c'est une seule ; avec des emojis ou des lettres hors de l'alphabet GSM, jusqu'à 70. Au-delà, chaque partie est facturée.

## Demander un appel

L'IA de votre agent appelle le numéro avec l'objectif indiqué dans reason (jusqu'à 2 000 caractères). Champs : to (E.164), reason et contact_id (facultatif : le contact TBit ; sans lui, le contact est cherché par numéro et créé s'il n'existe pas). La réponse est 202 : l'appel est demandé. Il coûte 6 d'énergie par minute, facturés à la fin ; pour l'instant, seuls les numéros de Colombie peuvent être appelés.

Mode avis : si vous envoyez message (jusqu'à 1 000 caractères) au lieu de reason, l'appel ne fait qu'informer. L'IA dit ce texte tel quel quelques secondes après avoir décroché (sans attendre que la personne parle), prend congé et raccroche ; elle ne converse pas et ne répond pas aux questions. Avec message, reason est facultatif et sert de contexte. L'appel sort par la ligne de votre agent et est facturé de la même façon : 6 d'énergie par minute entamée.

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

Réponse:

```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 vous recevez

Les SMS qu'on vous écrit sur la ligne apparaissent dans la boîte de réception de TBit comme une conversation par SMS. L'IA n'y répond pas. Chacun consomme 1 d'énergie par partie.

## Limites

En plus de la limite générale de 100 requêtes par minute, chacun de ces endpoints accepte jusqu'à 30 par minute par agent.

## Erreurs

| Statut | Code | Description |
| --- | --- | --- |
| `409` | `NO_PHONE_LINE` | L'agent n'a pas de ligne téléphonique active |
| `422` | `DESTINATION_NOT_ALLOWED` | Le destinataire n'est pas encore activé (les +1 exigent le 10DLC) |
| `402` | `INSUFFICIENT_ENERGY` | L'énergie est insuffisante ; rien n'a été envoyé ni appelé |
| `502` | `PROVIDER_ERROR` | L'opérateur a refusé l'envoi ou l'appel ; message en donne le motif |
