API
SMS and calls
Send SMS and request AI calls from your agent's phone line
# SMS and calls > Send SMS and request AI calls from your agent's phone line - Page: https://tbit.app/docs/api/sms-calls - Base URL: `https://rest-api.tbit.app/v1` - Authentication: `X-API-Key` header with your key on every request (the examples read it from the `TBIT_API_KEY` environment variable) ## Overview Both go out through your agent's phone line (the one you buy in Plugins › Phone line) and use energy from your plan. Every SMS you send is saved in the contact's thread in TBit (the contact is created if it doesn't exist), and SMS people send you show up in your inbox on the SMS channel. ## Endpoints | Method | Path | Description | | --- | --- | --- | | `POST` | `/v1/sms` | Send an SMS | | `POST` | `/v1/calls` | Have the AI call a number | ## Requirements - An active phone line on the agent that owns the API key. - Enough energy: it is checked before sending or calling, and nothing goes out if it doesn't cover it (402). - SMS to +1 numbers (United States, Canada, Puerto Rico…) need the business's 10DLC registration; until then they return 422. Each number has its own capabilities: if the line can't send SMS to that destination, the response carries the carrier's reason (502). ## Send an SMS Fields: to (number in E.164 format, with + and country code), text (up to 1,530 characters) and from (optional: one of the agent's lines in E.164, or an alphanumeric sender of 1 to 11 letters/numbers such as "MiTienda", which cannot receive replies and does not work for +1 numbers; without it, the oldest line). The response says how many parts it took and how much energy it used. `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" } ``` ## SMS energy | Case | Energy per part | | --- | --- | | SMS sent to a +1 number | 1 (needs 10DLC) | | SMS sent to any other country | `3` | | SMS received | `1` | A long SMS travels in several parts: up to 160 characters is one; with emoji or letters outside the GSM alphabet, up to 70. Beyond that, each part is charged. ## Request a call Your agent's AI calls the number with the goal you give in reason (up to 2,000 characters). Fields: to (E.164), reason and contact_id (optional: the TBit contact; without it, the contact is looked up by number and created if missing). The response is 202: the call was requested. It costs 6 energy per minute, charged when it ends; for now only numbers in Colombia can be called. `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" } ``` ## SMS you receive SMS sent to the line show up in the TBit inbox as an SMS conversation. The AI does not reply to them. Each one uses 1 energy per part. ## Limits On top of the general limit of 100 requests per minute, each of these endpoints accepts up to 30 per minute per agent. ## Errors | Status | Code | Description | | --- | --- | --- | | `409` | `NO_PHONE_LINE` | The agent has no active phone line | | `422` | `DESTINATION_NOT_ALLOWED` | The destination is not enabled yet (+1 needs 10DLC) | | `402` | `INSUFFICIENT_ENERGY` | Not enough energy; nothing was sent or called | | `502` | `PROVIDER_ERROR` | The carrier rejected the SMS or the call; message carries its reason |Both go out through your agent's phone line (the one you buy in Plugins › Phone line) and use energy from your plan. Every SMS you send is saved in the contact's thread in TBit (the contact is created if it doesn't exist), and SMS people send you show up in your inbox on the SMS channel.
| Method | Path | Description |
|---|---|---|
| POST | /v1/sms | Send an SMS |
| POST | /v1/calls | Have the AI call a number |
- An active phone line on the agent that owns the API key.
- Enough energy: it is checked before sending or calling, and nothing goes out if it doesn't cover it (402).
- SMS to +1 numbers (United States, Canada, Puerto Rico…) need the business's 10DLC registration; until then they return 422. Each number has its own capabilities: if the line can't send SMS to that destination, the response carries the carrier's reason (502).
Fields: to (number in E.164 format, with + and country code), text (up to 1,530 characters) and from (optional: one of the agent's lines in E.164, or an alphanumeric sender of 1 to 11 letters/numbers such as "MiTienda", which cannot receive replies and does not work for +1 numbers; without it, the oldest line). The response says how many parts it took and how much energy it used.
/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"
}| Case | Energy per part |
|---|---|
| SMS sent to a +1 number | 1 (needs 10DLC) |
| SMS sent to any other country | 3 |
| SMS received | 1 |
A long SMS travels in several parts: up to 160 characters is one; with emoji or letters outside the GSM alphabet, up to 70. Beyond that, each part is charged.
Your agent's AI calls the number with the goal you give in reason (up to 2,000 characters). Fields: to (E.164), reason and contact_id (optional: the TBit contact; without it, the contact is looked up by number and created if missing). The response is 202: the call was requested. It costs 6 energy per minute, charged when it ends; for now only numbers in Colombia can be called.
/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"
}SMS sent to the line show up in the TBit inbox as an SMS conversation. The AI does not reply to them. Each one uses 1 energy per part.
On top of the general limit of 100 requests per minute, each of these endpoints accepts up to 30 per minute per agent.
| Status | Code | Description |
|---|---|---|
409 | NO_PHONE_LINE | The agent has no active phone line |
422 | DESTINATION_NOT_ALLOWED | The destination is not enabled yet (+1 needs 10DLC) |
402 | INSUFFICIENT_ENERGY | Not enough energy; nothing was sent or called |
502 | PROVIDER_ERROR | The carrier rejected the SMS or the call; message carries its reason |