API
SMS et appels
Envoyez des SMS et demandez des appels de l'IA depuis la ligne téléphonique de votre agent
# 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 |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.
| Méthode | Chemin | Description |
|---|---|---|
| POST | /v1/sms | Envoyer un SMS |
| POST | /v1/calls | Faire appeler un numéro par l'IA |
- 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).
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.
/v1/smscurl -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."
}'const response = await fetch('https://rest-api.tbit.app/v1/sms', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+573001234567',
text: 'Hola Ana, tu pedido #1042 sale hoy.',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/sms',
{
to: '+573001234567',
text: 'Hola Ana, tu pedido #1042 sale hoy.',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/sms',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '+573001234567',
'text': 'Hola Ana, tu pedido #1042 sale hoy.',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/sms');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '+573001234567',
'text' => 'Hola Ana, tu pedido #1042 sale hoy.',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"id": "40319a3e-7e2c-4f4e-9b0e-2c1d5f8a9b10",
"from": "+17869572575",
"to": "+573001234567",
"parts": 1,
"energy": 3,
"contact_id": "6ac9f1e6af6d42a269f21b15",
"message_id": "6ac9f2a1af6d42a269f21c02"
}| 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.
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.
/v1/callscurl -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."
}'const response = await fetch('https://rest-api.tbit.app/v1/calls', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+573001234567',
reason: 'Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede.',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/calls',
{
to: '+573001234567',
reason: 'Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede.',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/calls',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '+573001234567',
'reason': 'Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede.',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/calls');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '+573001234567',
'reason' => 'Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede.',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"call_id": "6ac9f3b7af6d42a269f21c10",
"provider_call_id": "conv_8f2k1x",
"from": "+576019190351",
"to": "+573001234567",
"contact_id": "6ac9f1e6af6d42a269f21b15",
"status": "requested"
}/v1/callscurl -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."
}'const response = await fetch('https://rest-api.tbit.app/v1/calls', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+573001234567',
message: 'Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta.',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/calls',
{
to: '+573001234567',
message: 'Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta.',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/calls',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '+573001234567',
'message': 'Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta.',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/calls');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '+573001234567',
'message' => 'Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta.',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);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.
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.
| 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 |