Overzicht
Met de Buluthat API integreert u uw bestaande software (CRM, ERP, e-commerce, helpdesk) met uw cloudtelefooncentrale: click-to-call, gespreksbesturing, wachtrijbeheer, zwarte lijst, geluidsbestanden, campagnes voor automatisch bellen, taken voor de spraakassistent en spraakverificatiecodes.
Alle endpoints draaien over gewone HTTP; antwoorden zijn JSON. Te gebruiken vanuit elke taal met een HTTP-client.
Basisadres: https://api.buluthat.com/api/
Authenticatie
Alle endpoints hetzelfde De API-sleutel gebruikt. De sleutel in het paneel Account en Support > API-sleutels op de pagina, door de accountbeheerder aangemaakt; bt_ begint met en wordt slechts eenmaal getoond, op het moment van aanmaken.
De sleutel wordt bij elk verzoek in de header meegestuurd:
Authorization: Bearer bt_xxxxxxxxAuthorization als de header niet kan worden ingesteld X-Api-Key: bt_xxxxxxxx wordt ook geaccepteerd. Sleutel in de URL (?key=) is voor nieuwe sleutels uitgeschakeld.
Elke sleutel is gekoppeld aan één klantaccount en heeft alleen toegang tot de gegevens van dat account. Bij de sleutel bereik is gedefinieerd:
| Bereik | Endpoints |
|---|---|
call | Gespreksbeheer, wachtrijen, medewerkerstatussen |
autocall | Automatisch bellen (opent ook de endpoints voor spraakassistent, spraak-OTP en oproepen voor compatibiliteit met oudere integraties) |
voicebot | Spraakassistent |
voice_otp | Spraakverificatiecode |
sms | SMS API |
Verzoek buiten het bereik 403 scope_denied, module uitgeschakeld in uw account 403 module_disabled geeft terug. Bij de sleutel lijst met toegestane IP's, vervaldatum en verplichte HMAC-verzoekhandtekening kan worden gedefinieerd; allemaal API-beveiliging op de pagina.
Gebruik uw sleutel niet aan de browserzijde (JavaScript); roep altijd aan vanaf uw eigen server. Vermoedt u een lek, kies dan in het paneel "Sleutel vernieuwen > Oude sleutel direct sluiten"; de oude is onmiddellijk ongeldig.
Verzoekformaat
- Leesbewerkingen
GET, handelingen die wijzigenPOST(bij audiobestandenPUT/DELETE). - POST-body
application/jsonofapplication/x-www-form-urlencodedkan zijn. - Handeling bij integratie-endpoints
actionwordt gekozen met de parameter (?action=create_campaign). - Tijdstempels zijn Turkse tijd (
2026-09-18 10:12:03). - Telefoonnummers
05xxxxxxxxx,5xxxxxxxxxof905xxxxxxxxxwordt geaccepteerd in het formaat; in antwoorden komt het genormaliseerd terug.
Antwoordformaat
De integratie-endpoints (autocall, voicebot, voice_otp) geven altijd een envelop terug:
{ "ok": true, "data": { } }{ "ok": false, "error": "Kampanya bulunamadı.", "code": "campaign_not_found" }De endpoints van de telefooncentrale (begin_call, queues, blocked_numbers…) spreken via HTTP-statuscodes: bij succes 200 OK en in de body het resultaat (JSON-array of platte tekst), bij een fout 4xx en in de body een Turks foutbericht.
Foutcodes
| HTTP | code | Betekenis |
|---|---|---|
| 400 | validation_failed | Veldvalidatie mislukt; het bericht geeft de reden |
| 401 | missing_token / invalid_token / token_expired | Sleutel ontbreekt, is ongeldig of verlopen |
| 401 | query_key_disabled / signature_* | De sleutel kwam in de URL of de handtekening kon niet worden geverifieerd (API-beveiliging) |
| 403 | module_disabled / scope_denied / ip_not_allowed | Module uitgeschakeld, bereik onvoldoende of IP niet toegestaan |
| 404 | *_not_found | Geen dossier of het hoort bij een andere klant |
| 405 | method_not_allowed | GET ontvangen voor een bewerking die POST vereist |
| 422 | (per eindpunt) | Weigering door bedrijfsregel: quota, duur, geen lijn enz. |
| 413 | payload_too_large | De verzoek-body overschrijdt 5 MB |
| 429 | rate_limited / ip_locked | Snelheidslimiet overschreden of IP tijdelijk geblokkeerd wegens te veel foutieve pogingen |
| 503 | db_unavailable | Tijdelijk servicprobleem; probeer het zo opnieuw |
Snelheidslimieten
| Limiet | Standaard |
|---|---|
| Per sleutel | 120 verzoeken per minuut (te verlagen in de sleutelinstellingen) |
| Totaal van alle sleutels van het account | 600 verzoeken per minuut |
| Medewerkerstatussen | bovendien 2 verzoeken per minuut (gebruik voor live status liever een webhook) |
Automatisch bellen add_leads | 5.000 records per verzoek |
In antwoorden X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers komen mee. Bij overschrijding 429 Too Many Requests en Retry-After header wordt teruggegeven. Elk antwoord heeft de X-Request-Id deel de waarde in supportverzoeken.
Testomgeving
Er is geen aparte sandbox; probeer het met een testtoestel en een kleine campagne in uw account. Campagnes voor automatisch bellen status: "draft" aangemaakt met en results/summary u kunt de endpoints ook aanroepen zonder dat er data binnenkomt. Verstuur bij de spraakverificatiecode naar uw eigen nummer; de tarifering verloopt volgens uw pakketregels.
Versie en wijzigingen
Endpoints blijven achterwaarts compatibel; nieuwe velden worden toegevoegd, de naam en het type van bestaande velden veranderen niet. Een veld dat vervalt wordt minstens 90 dagen van tevoren in het paneel en op deze pagina aangekondigd.
Help
Loopt u tijdens de integratie vast, open dan in het Helpcentrum van het paneel een melding met het onderwerp "Integratie / API"; voeg uw voorbeeldverzoek/-antwoord toe, dan kijken we samen.