Naar de inhoud
Menu

Zoeken op de site

Typ om te zoeken in handleidingen, blog, API en product.

↑ ↓ om te bewegen · Enter om te openen · Esc om te sluiten

API-referentie

API

Sms en oproepen

Verstuur sms en laat de AI bellen via de telefoonlijn van je agent

Bekijken als Markdown

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.

MethodePadBeschrijving
POST/v1/smsEen sms versturen
POST/v1/callsDe 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).

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
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"
}
GevalEnergie per deel
Sms naar een +1-nummer1 (vereist 10DLC)
Sms naar elk ander land3
Ontvangen sms1

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
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"
}
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);

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.

StatusCodeBeschrijving
409NO_PHONE_LINEDe agent heeft geen actieve telefoonlijn
422DESTINATION_NOT_ALLOWEDHet doel is nog niet ingeschakeld (de +1-nummers vragen om 10DLC)
402INSUFFICIENT_ENERGYNiet genoeg energie; er is niets verzonden en niet gebeld
502PROVIDER_ERRORDe operator weigerde het verzenden of het gesprek; message bevat de reden