API versie 1 · bijgewerkt 25 oktober 2026
Met de API en webhooks komen de gesprekken die BelBuddy aanneemt automatisch in uw eigen software: CRM, ticketsysteem of planning. Sleutels en webhooks maakt de klant zelf aan op de computer: log in op app.belbuddy.eu en kies Instellingen › Koppelingen met uw software. De API hoort bij het pakket Team; webhooks bij Zakelijk (€ 19 per maand extra) en Team.
Stuur de sleutel mee in de kop Authorization. Een sleutel hoort bij één bedrijf en geeft alleen leestoegang tot de gesprekken van dat bedrijf.
curl https://app.belbuddy.eu/api/v1/gesprekken \ -H "Authorization: Bearer bb_live_..."
Maximaal 600 verzoeken per minuut per sleutel. Een ingetrokken sleutel werkt direct niet meer.
| Verzoek | Wat u krijgt |
|---|---|
GET /api/v1/bedrijf | Naam, nummer en openingstijden |
GET /api/v1/gesprekken | De nieuwste gesprekken (zonder gesprekstekst). Filters: sinds (unix-tijd), uitkomst (afspraak, terugbellen, beantwoord), limiet (1–200) |
GET /api/v1/gesprekken/{id} | Eén gesprek, met de volledige gesprekstekst |
{
"id": "conv_...",
"gestart": "2026-10-25T10:42:00+02:00",
"duur_seconden": 74,
"beller": "+31611223344",
"uitkomst": "terugbellen",
"titel": "Graag terugbellen: Ali Yilmaz",
"notitie": {
"naam": "Ali Yilmaz", "telefoon": "06 11 22 33 44",
"wilde": "Afspraak van donderdag verzetten",
"samenvatting": "...",
"afspraak": null,
"terugbellen": {"naam": "Ali Yilmaz", "telefoon": "06 11 22 33 44", "onderwerp": "afspraak verzetten"}
},
"transcript": [{"wie": "BelBuddy", "sec": 0, "tekst": "..."}, {"wie": "Beller", "sec": 3, "tekst": "..."}]
}
Na elk afgerond gesprek stuurt BelBuddy binnen enkele seconden een POST naar uw adres (alleen https) met gebeurtenis gesprek.afgerond. Het gesprek staat in data.gesprek, in hetzelfde formaat als hierboven.
POST https://uw-systeem.nl/belbuddy
BelBuddy-Event: gesprek.afgerond
BelBuddy-Signature: t=1792900000,v1=5f2b...
{"id": "evt_...", "type": "gesprek.afgerond", "gemaakt": "...", "klant": "...", "data": {"gesprek": {...}}}
Controleer de handtekening. Bereken HMAC-SHA256 met het geheim van de webhook (begint met whsec_) over t + "." + de ruwe body, en vergelijk met v1. Weiger berichten waarvan t ouder is dan vijf minuten.
# Python
import hmac, hashlib, time
def echt(geheim, kop, body):
d = dict(p.split("=", 1) for p in kop.split(","))
if abs(time.time() - int(d["t"])) > 300:
return False
verwacht = hmac.new(geheim.encode(), f"{d['t']}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(verwacht, d["v1"])
Antwoord met een 2xx-status. Lukt de aflevering niet, dan proberen we het opnieuw na 1 minuut, 10 minuten en 1 uur. Het logboek staat in de app. Met de knop Test stuurt u een proefbericht met type test.
Mail naar [email protected].