Call gebruiken

De Call-API en webhooks voor ontwikkelaars: sleutels, scopes, events

Een praktische rondgang door de REST-API van Call: API-sleutels en scopes, rate limits, foutafhandeling, ondertekende webhooks en de pagina Ontwikkelaars.

Redactie van Call · Gepubliceerd · 6 min leestijd

Vroeg of laat moet een telefoonsysteem met iets anders praten: een CRM dat een gesprek moet tonen zodra het eindigt, een facturatietool die wil weten wie er belde, een script dat een gesprek start als een formulier wordt verzonden. Call heeft daarvoor een REST-API en uitgaande webhooks. Deze gids legt uit hoe de onderdelen samenhangen, waar u om moet vragen voordat u code schrijft, en welke fouten een ontwikkelaar het vaakst een middag kosten.

Een ontwikkelaar bekijkt een integratie op een laptop naast een bureautelefoon
Illustratieve afbeelding

Wilt u alleen contacten in bulk verplaatsen, lees dan eerst Contacten importeren in een CRM voor telefoonteams; een import is vaak eenvoudiger dan een integratie.

Waar te beginnen: de referentie en de pagina Ontwikkelaars

Er zijn twee plekken die u moet kennen. De API-referentie staat onder Instellingen, en ook in het menu Resources op de homepage. U kunt die lezen zonder in te loggen, wat handig is als u werk voor een klant inschat. De pagina Ontwikkelaars, ook onder Instellingen, is voor uw eigen werkruimte: die toont de ID's van uw organisatie en agents, uw webhookendpoints en een alleen-lezenlijst van uw sleutels.

Wat elke plek u biedt

  • Begin hierBasis-URL en conventies, authenticatie met een tabel van scopes, en fouten met statuscodes.
  • EndpointsElke endpointkaart vermeldt de scope, parameters, request body, response en fouten, met kant-en-klare verzoeken in curl, JavaScript en Python.
  • ZoekenDruk op / om naar Endpoints zoeken te gaan en te filteren op methode, pad, scope of samenvatting.
  • OpenAPI JSONDownloadt de volledige specificatie als één bestand voor uw eigen tools.
  • Agent-ID / APIUw organisatie-ID en slug, de API-modus (Sandbox of Live) en de ID van de AI-agent die u kiest, elk met een knop Kopiëren.
  • WebhooksUw endpoints, de events die elk ontvangt, de laatste HTTP-status en eventuele mislukte afleveringen.

Lees de onderdelen over rate limits en uitgaande webhooks vóór de livegang, niet erna. Ze beschrijven gedrag dat bij een snelle test makkelijk over het hoofd wordt gezien.

API-sleutels en scopes

Elk verzoek bevat een sleutel in een Authorization-header als bearer token. Sleutels worden niet in de app aangemaakt: de beheerder van uw werkruimte geeft ze uit en vertelt u welke scopes ze hebben. De volledige sleutel wordt één keer getoond, op het moment van uitgifte, en daarna zijn alleen de eerste tekens zichtbaar, dus bewaar hem direct in uw eigen geheimenkluis.

ScopeWat het toestaat
readContacten, gesprekken, wachtrijen, teamleden, rapportages en de bel-me-niet-lijst lezen.
writeContacten aanmaken en bijwerken, gespreksuitkomsten vastleggen, nummers aan de bel-me-niet-lijst toevoegen.
callsGesprekken starten en beëindigen.
adminWebhooks beheren; mag ook elk ander endpoint aanroepen.

Vraag om de kleinste set die het werk doet. Een rapportagescript heeft alleen read nodig; een klik-om-te-bellenknop heeft calls nodig. Geeft een verzoek een 403 met de code insufficient_scope, dan mist de sleutel de scope die op de kaart van dat endpoint staat.

Sandbox en live

Sleutels kunnen worden uitgegeven voor een sandbox, die een simulator gebruikt en geen echte gesprekken voert, of voor live gebruik. Zie het voorvoegsel van een sleutel alleen als label: een sleutel met een testlabel werkt op dezelfde gegevens en dezelfde telefoonverbinding als een live sleutel, dus vertrouw niet op het voorvoegsel om experimenten bij echte klanten weg te houden. Gebruik de API-modus op de pagina Ontwikkelaars om te weten waar u staat.

Gesprekken starten via de API

De openbare endpoints dekken de basis: een statuscontrole, gesprekken opvragen, één gesprek lezen, een gesprek starten, ophangen, webhooks beheren en chatten met een AI-agent. Een uitgaand gesprek via de API doorloopt dezelfde compliancecontrole als een gesprek vanaf de werkplek, dus een nummer op de bel-me-niet-lijst of buiten de toegestane beltijden wordt geweigerd, precies zoals bij een medewerker. Bouw uw code zo dat die weigering als normale uitkomst wordt afgehandeld, niet als bug.

Dat is belangrijk voor het ontwerp. Schrijf geen lus die een geweigerd gesprek blijft herhalen totdat het lukt. Lees de reden, log die en ga verder. Voor de regels achter die weigeringen, zie Bewaking van beltijden in Call en De bel-me-niet-lijst in Call.

Rate limits en fouten

Elke sleutel heeft een eigen limiet aan verzoeken per minuut, ingesteld bij de uitgifte; de standaard is 120. Heeft een sleutel de minuut opgebruikt, dan antwoordt de API met 429 en de code rate_limited, en vertelt de header X-RateLimit-Reset hoe lang u moet wachten. Wacht zo lang en ga dan verder. Een beleefde client remt zichzelf af voordat die tegen de muur loopt.

Een mislukt verzoek afhandelen

  1. Lees de statusIs het een clientfout die u kunt oplossen, of een serverfout die een nieuwe poging waard is?
  2. Lees de codeVertak op de code, nooit op de tekst van de melding.
  3. Wacht afWacht bij 429 op de reset-header; probeer het bij serverfouten een paar keer opnieuw met oplopende pauzes.
  4. Log de detailsBewaar het endpoint, de code en het tijdstip, zodat support het kan nagaan.
  5. Stop bij weigeringenEen complianceweigering is een beslissing, geen storing; ga er niet in een lus op door.

Webhooks: events ontvangen

In plaats van de API steeds opnieuw te vragen of er iets is gebeurd, laat u Call het u vertellen. Klik op de pagina Ontwikkelaars op Endpoint toevoegen, vul een openbaar https-adres in en vink de events aan die u wilt ontvangen; niets aanvinken betekent alle events. Het ondertekeningsgeheim wordt één keer getoond, bij het toevoegen van het endpoint. Kopieer het dan. Raakt het kwijt, verwijder het endpoint dan en voeg het opnieuw toe om een nieuw geheim te krijgen.

Elke aflevering is ondertekend. De handtekeningheader bevat een HMAC-SHA256 van het tijdstempel en de body, samengevoegd met een punt, berekend met uw ondertekeningsgeheim, en een aparte header bevat het tijdstempel. Bereken die aan uw kant opnieuw en vergelijk voordat u de payload vertrouwt. De API-referentie bevat hiervoor voorbeeldcode in Node.js en Python, en het weigeren van oude tijdstempels beschermt u tegen herhaalde verzoeken.

Een goede en een slechte webhookontvanger

GoedSlecht
HandtekeningBij elk verzoek geverifieerdZonder controle vertrouwd
AntwoordBinnen enkele seconden 2xx, werk in een wachtrij voor laterTrage verwerking vóór het antwoord
DuplicatenHetzelfde event twee keer ontvangen is veiligMaakt twee records aan
FoutenWaarschuwt als afleveringen mislukkenStil totdat iemand het merkt

Uw endpoint moet binnen 10 seconden antwoorden met een 2xx-status. Een mislukte aflevering wordt opnieuw geprobeerd, tot zes pogingen in totaal, en een endpoint dat 50 keer achter elkaar faalt, wordt uitgeschakeld. Elke rij op de pagina Ontwikkelaars toont de laatste HTTP-status en hoeveel afleveringen mislukten, en Test versturen stuurt één ondertekend testevent zodat u ziet wat uw server antwoordt.

Een checklist voor de livegang

Voordat u een integratie inschakelt

  • U weet welke scopes de sleutel heeft, en het zijn er niet meer dan nodig
  • De sleutel staat in een geheimenkluis, niet in de broncode
  • Webhookhandtekeningen worden geverifieerd en oude tijdstempels geweigerd
  • De ontvanger antwoordt snel en kan dubbele events aan
  • Rate-limit- en weigeringsantwoorden worden afgehandeld zonder strakke herhaallussen
  • U hebt in sandboxmodus getest en op het endpoint op Test versturen geklikt
  • Er is iemand aangewezen die een melding krijgt als afleveringen gaan mislukken

Zo doet u het in Call

Open in Call Instellingen, dan API-referentie om de endpoints te bestuderen, en Instellingen, dan Ontwikkelaars om uw organisatie-ID te kopiëren, uw sleutels te controleren en een webhook toe te voegen. Eigenaren, beheerders en managers kunnen endpoints toevoegen, testen en verwijderen; alle anderen zien de lijst. Gebruikt u ook de functies voor AI-agents, dan voedt de agent-ID op dezelfde pagina het chat-endpoint. Voor de spraakkant van het product, zie Een AI-agent instellen in Call.

Veelgestelde vragen

Hoe krijg ik een API-sleutel?

Sleutels worden uitgegeven door de beheerder van uw werkruimte; ze kunnen niet in de app worden aangemaakt. Vraag er een aan en geef aan welke scopes die nodig heeft. De volledige sleutel wordt één keer getoond bij de uitgifte.

Wat betekent een 429-antwoord?

De sleutel heeft de verzoeken voor de huidige minuut opgebruikt. Wacht het aantal seconden uit de header X-RateLimit-Reset af, probeer het dan opnieuw en spreid bulkwerk over een langere periode.

Hoe controleer ik of een webhook echt van Call komt?

Bereken een HMAC-SHA256 van het tijdstempel en de body met uw ondertekeningsgeheim en vergelijk die met de handtekeningheader. De API-referentie toont voorbeelden in Node.js en Python.

Kan ik webhooks naar een lokale ontwikkelserver sturen?

Niet rechtstreeks. Endpoints moeten openbare https-adressen zijn, dus gebruik een tunneltool die uw lokale server op zo'n adres beschikbaar maakt.

Waarom werd mijn API-verzoek om een gesprek te starten geweigerd?

Gesprekken via de API doorlopen dezelfde compliancecontrole als gesprekken vanaf de werkplek. Een nummer op de bel-me-niet-lijst of buiten de beltijden wordt geweigerd.

Wie kan webhooks zien en wijzigen?

Iedereen kan de lijst lezen, maar alleen eigenaren, beheerders en managers kunnen endpoints toevoegen, testen of verwijderen.

Open de API-referentie van Call en voeg een webhookendpoint toe

In de democonsole probeert u inkomende gesprekken uit in een simulatie.

Gerelateerde gidsen