API
Sms en oproepen
Verstuur sms en laat de AI bellen via de telefoonlijn van je agent
# 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 |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.
| Methode | Pad | Beschrijving |
|---|---|---|
| POST | /v1/sms | Een sms versturen |
| POST | /v1/calls | De AI een nummer laten bellen |
- 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).
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.
/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"
}| 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.
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.
/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);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.
Naast de algemene limiet van 100 verzoeken per minuut accepteert elk van deze endpoints tot 30 per minuut per agent.
| 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 |