Skip to content
Menu

Search the site

Type to search guides, blog, API and product.

↑ ↓ to move · Enter to open · Esc to close

API Reference

API

SMS and calls

Send SMS and request AI calls from your agent's phone line

View as Markdown

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.

MethodPathDescription
POST/v1/smsSend an SMS
POST/v1/callsHave 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).

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
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);
Response
{
  "id": "40319a3e-7e2c-4f4e-9b0e-2c1d5f8a9b10",
  "from": "+17869572575",
  "to": "+573001234567",
  "parts": 1,
  "energy": 3,
  "contact_id": "6ac9f1e6af6d42a269f21b15",
  "message_id": "6ac9f2a1af6d42a269f21c02"
}
CaseEnergy per part
SMS sent to a +1 number1 (needs 10DLC)
SMS sent to any other country3
SMS received1

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
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);
Response
{
  "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.

StatusCodeDescription
409NO_PHONE_LINEThe agent has no active phone line
422DESTINATION_NOT_ALLOWEDThe destination is not enabled yet (+1 needs 10DLC)
402INSUFFICIENT_ENERGYNot enough energy; nothing was sent or called
502PROVIDER_ERRORThe carrier rejected the SMS or the call; message carries its reason