Aller au contenu
Menu

Rechercher sur le site

Tape pour chercher dans les guides, le blog, l'API et le produit.

↑ ↓ pour naviguer · Entrée pour ouvrir · Échap pour fermer

Référence de l'API

API

SMS et appels

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

Voir en Markdown

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éthodeCheminDescription
POST/v1/smsEnvoyer un SMS
POST/v1/callsFaire 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).

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
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."
  }'
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);
Réponse
{
  "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 +11 (exige 10DLC)
SMS envoyé vers tout autre pays3
SMS reçu1

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
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."
  }'
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);
Réponse
{
  "call_id": "6ac9f3b7af6d42a269f21c10",
  "provider_call_id": "conv_8f2k1x",
  "from": "+576019190351",
  "to": "+573001234567",
  "contact_id": "6ac9f1e6af6d42a269f21b15",
  "status": "requested"
}
POST/v1/calls
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."
  }'
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.

StatutCodeDescription
409NO_PHONE_LINEL'agent n'a pas de ligne téléphonique active
422DESTINATION_NOT_ALLOWEDLe destinataire n'est pas encore activé (les +1 exigent le 10DLC)
402INSUFFICIENT_ENERGYL'énergie est insuffisante ; rien n'a été envoyé ni appelé
502PROVIDER_ERRORL'opérateur a refusé l'envoi ou l'appel ; message en donne le motif