Call nutzen

Call-API und Webhooks für Entwickler: Schlüssel, Scopes, Events

Ein Praxisüberblick über die REST-API von Call: API-Schlüssel und Scopes, Rate Limits, Fehlerbehandlung, signierte Webhooks und die Entwicklerseite.

Redaktion von Call · Veröffentlicht · 6 Min. Lesezeit

Früher oder später muss ein Telefonsystem mit etwas anderem sprechen: einem CRM, das einen Anruf anzeigen soll, sobald er endet, einem Abrechnungstool, das wissen will, wer angerufen hat, einem Skript, das einen Anruf startet, wenn ein Formular abgeschickt wird. Genau dafür hat Call eine REST-API und ausgehende Webhooks. Dieser Leitfaden erklärt, wie die Teile zusammenpassen, worum Sie bitten sollten, bevor Sie Code schreiben, und welche Fehler Entwickler am häufigsten einen Nachmittag kosten.

Ein Entwickler prüft neben einem Tischtelefon eine Integration auf dem Laptop
Symbolbild

Wenn Sie nur Kontakte in großen Mengen übertragen möchten, lesen Sie zuerst Kontakte in ein Telefonteam-CRM importieren; ein Import ist oft einfacher als eine Integration.

Wo Sie anfangen: die Referenz und die Entwicklerseite

Zwei Orte sollten Sie kennen. Die API-Referenz befindet sich unter „Einstellungen“ und zusätzlich im Menü „Ressourcen“ der Startseite. Sie ist ohne Anmeldung lesbar, was praktisch ist, wenn Sie Arbeit für einen Kunden einschätzen. Die Seite Entwickler, ebenfalls unter „Einstellungen“, gilt Ihrem eigenen Arbeitsbereich: Sie zeigt Ihre Organisations- und Agenten-IDs, Ihre Webhook-Endpunkte und eine schreibgeschützte Liste Ihrer Schlüssel.

Was Ihnen jeder Ort bietet

  • Erste SchritteBasis-URL und Konventionen, Authentifizierung mit einer Scope-Tabelle sowie Fehler mit Statuscodes.
  • EndpunkteJede Endpunkt-Karte nennt Scope, Parameter, Request-Body, Antwort und Fehler, mit kopierfertigen Anfragen in curl, JavaScript und Python.
  • SuchenDrücken Sie /, um zur Endpunktsuche zu springen, und filtern Sie nach Methode, Pfad, Scope oder Zusammenfassung.
  • OpenAPI JSONLädt die gesamte Spezifikation als einzelne Datei für Ihre eigenen Tools herunter.
  • Agenten-ID / APIIhre Organisations-ID und Ihr Slug, der API-Modus (Sandbox oder Live) und die ID des gewählten KI-Agenten, jeweils mit einer Schaltfläche „Kopieren“.
  • WebhooksIhre Endpunkte, die Events, die jeder empfängt, der letzte HTTP-Status und fehlgeschlagene Zustellungen.

Lesen Sie die Abschnitte zu Rate Limits und ausgehenden Webhooks, bevor Sie live gehen – nicht danach. Sie beschreiben Verhalten, das in einem schnellen Test leicht übersehen wird.

API-Schlüssel und Scopes

Jede Anfrage trägt einen Schlüssel als Bearer-Token im Authorization-Header. Schlüssel werden nicht in der App erstellt: Der Betreiber Ihres Arbeitsbereichs gibt sie aus und teilt Ihnen mit, welche Scopes sie haben. Der vollständige Schlüssel wird nur einmal bei der Ausgabe angezeigt, danach nur noch seine ersten Zeichen – legen Sie ihn also sofort in Ihrem eigenen Secret Store ab.

ScopeWas er erlaubt
readKontakte, Anrufe, Warteschlangen, Teammitglieder, Berichte und die Sperrliste lesen.
writeKontakte anlegen und aktualisieren, Anrufergebnisse erfassen, Nummern zur Sperrliste hinzufügen.
callsAnrufe tätigen und beenden.
adminWebhooks verwalten; darf außerdem jeden anderen Endpunkt aufrufen.

Fordern Sie die kleinste Menge an, die für die Aufgabe reicht. Ein Reporting-Skript braucht read und sonst nichts; ein Click-to-Call-Button braucht calls. Liefert eine Anfrage 403 mit dem Code insufficient_scope, fehlt dem Schlüssel der Scope, der auf der Karte des Endpunkts steht.

Sandbox und Live

Schlüssel können für eine Sandbox ausgegeben werden, die einen Simulator nutzt und keine echten Anrufe tätigt, oder für den Live-Betrieb. Betrachten Sie das Präfix eines Schlüssels nur als Bezeichnung: Ein als Test gekennzeichneter Schlüssel arbeitet auf denselben Daten und derselben Telefonverbindung wie ein Live-Schlüssel. Verlassen Sie sich also nicht auf das Präfix, um Experimente von echten Kunden fernzuhalten. Der auf der Entwicklerseite angezeigte API-Modus zeigt Ihnen, wo Sie stehen.

Anrufe über die API tätigen

Die öffentlichen Endpunkte decken die Grundlagen ab: einen Health Check, Anrufe auflisten, einen Anruf lesen, einen Anruf tätigen, auflegen, Webhooks verwalten und mit einem KI-Agenten chatten. Ein über die API getätigter ausgehender Anruf durchläuft dieselbe Compliance-Prüfung wie ein Anruf vom Arbeitsplatz aus. Eine Nummer auf der Sperrliste oder außerhalb der erlaubten Anrufzeiten wird also abgelehnt, genau wie bei einem Agenten. Behandeln Sie diese Ablehnung in Ihrem Code als normales Ergebnis, nicht als Bug.

Das ist wichtig für das Design. Schreiben Sie keine Schleife, die einen abgelehnten Anruf wiederholt, bis er klappt. Lesen Sie den Grund, protokollieren Sie ihn und machen Sie weiter. Die Regeln hinter diesen Ablehnungen finden Sie in Anrufzeitenschutz in Call und Die Sperrliste in Call.

Rate Limits und Fehler

Jeder Schlüssel hat ein eigenes Limit an Anfragen pro Minute, das bei der Ausgabe festgelegt wird; der Standard ist 120. Hat ein Schlüssel sein Minutenkontingent verbraucht, antwortet die API mit 429 und dem Code rate_limited und nennt im Header X-RateLimit-Reset, wie lange Sie warten sollen. Warten Sie so lange und fahren Sie dann fort. Ein höflicher Client bremst sich selbst, bevor er gegen die Wand fährt.

Eine fehlgeschlagene Anfrage behandeln

  1. Status lesenIst es ein Client-Fehler, den Sie beheben können, oder ein Server-Fehler, bei dem sich ein neuer Versuch lohnt?
  2. Code lesenVerzweigen Sie nach dem Code, nie nach dem Meldungstext.
  3. ZurückhaltenBei 429 auf den Reset-Header warten; bei Server-Fehlern einige Male mit wachsenden Abständen wiederholen.
  4. Details protokollierenHalten Sie Endpunkt, Code und Zeitpunkt fest, damit der Support nachverfolgen kann.
  5. Bei Ablehnungen aufhörenEine Compliance-Ablehnung ist eine Entscheidung, keine Störung; wiederholen Sie sie nicht in einer Schleife.

Webhooks: Events empfangen

Statt die API immer wieder zu fragen, ob etwas passiert ist, lassen Sie es sich von Call mitteilen. Klicken Sie auf der Entwicklerseite auf „Endpunkt hinzufügen“, geben Sie eine öffentliche https-Adresse ein und haken Sie die gewünschten Events an; keine Auswahl bedeutet alle Events. Das Signing Secret wird einmal angezeigt, wenn der Endpunkt hinzugefügt wird. Kopieren Sie es dann. Geht es verloren, löschen Sie den Endpunkt und fügen Sie ihn erneut hinzu, um ein neues zu erhalten.

Jede Zustellung ist signiert. Der Signatur-Header enthält ein HMAC-SHA256 aus Zeitstempel und Body, verbunden durch einen Punkt und berechnet mit Ihrem Signing Secret; ein separater Header trägt den Zeitstempel. Berechnen Sie den Wert auf Ihrer Seite neu und vergleichen Sie, bevor Sie der Nutzlast vertrauen. Die API-Referenz enthält dafür Beispielcode in Node.js und Python, und das Ablehnen alter Zeitstempel schützt Sie vor wiederholt eingespielten Anfragen.

Ein guter und ein schwacher Webhook-Empfänger

GutSchlecht
SignaturBei jeder Anfrage geprüftUngeprüft vertraut
Antwort2xx innerhalb von Sekunden, Arbeit für später eingereihtLangsame Verarbeitung vor der Antwort
DuplikateDasselbe Event zweimal zu empfangen ist unproblematischErzeugt zwei Datensätze
FehlerAlarmiert, wenn Zustellungen fehlschlagenStill, bis es jemand bemerkt

Ihr Endpunkt muss innerhalb von 10 Sekunden mit einem 2xx-Status antworten. Eine fehlgeschlagene Zustellung wird erneut versucht, insgesamt bis zu sechsmal, und ein Endpunkt, der 50-mal hintereinander fehlschlägt, wird abgeschaltet. Jede Zeile auf der Entwicklerseite zeigt den letzten HTTP-Status und wie viele Zustellungen fehlgeschlagen sind, und „Test senden“ löst ein signiertes Test-Event aus, damit Sie sehen, was Ihr Server antwortet.

Checkliste für den Go-live

Bevor Sie eine Integration einschalten

  • Sie wissen, welche Scopes der Schlüssel hat, und er hat nicht mehr als nötig
  • Der Schlüssel liegt in einem Secret Store, nicht im Quellcode
  • Webhook-Signaturen werden geprüft und alte Zeitstempel abgelehnt
  • Der Empfänger antwortet schnell und verarbeitet doppelte Events
  • Rate-Limit- und Ablehnungsantworten werden ohne enge Wiederholungsschleifen behandelt
  • Sie haben im Sandbox-Modus getestet und beim Endpunkt auf „Test senden“ geklickt
  • Eine benannte Person erhält eine Warnung, wenn Zustellungen zu scheitern beginnen

So geht es in Call

Öffnen Sie in Call „Einstellungen“, dann „API-Referenz“, um die Endpunkte zu studieren, und „Einstellungen“, dann „Entwickler“, um Ihre Organisations-ID zu kopieren, Ihre Schlüssel zu prüfen und einen Webhook hinzuzufügen. Inhaber, Admins und Manager können Endpunkte hinzufügen, testen und löschen; alle anderen sehen die Liste. Nutzen Sie auch die KI-Agenten-Funktionen, speist die Agenten-ID auf derselben Seite den Chat-Endpunkt. Für die Sprachseite des Produkts lesen Sie Einen KI-Agenten in Call einrichten.

Häufig gestellte Fragen

Wie erhalte ich einen API-Schlüssel?

Schlüssel werden vom Betreiber Ihres Arbeitsbereichs ausgegeben; in der App lassen sie sich nicht erstellen. Fragen Sie nach einem und nennen Sie die benötigten Scopes. Der vollständige Schlüssel wird bei der Ausgabe einmal angezeigt.

Was bedeutet eine 429-Antwort?

Der Schlüssel hat seine Anfragen für die aktuelle Minute verbraucht. Warten Sie die im Header X-RateLimit-Reset genannten Sekunden ab, versuchen Sie es dann erneut und verteilen Sie Massenarbeit über einen längeren Zeitraum.

Wie prüfe ich, dass ein Webhook wirklich von Call stammt?

Berechnen Sie mit Ihrem Signing Secret ein HMAC-SHA256 aus Zeitstempel und Body und vergleichen Sie es mit dem Signatur-Header. Die API-Referenz zeigt Beispiele in Node.js und Python.

Kann ich Webhooks an einen lokalen Entwicklungsserver senden?

Nicht direkt. Endpunkte müssen öffentliche https-Adressen sein; nutzen Sie daher ein Tunneling-Tool, das Ihren lokalen Server unter einer solchen Adresse erreichbar macht.

Warum wurde mein API-Aufruf zum Tätigen eines Anrufs abgelehnt?

Über die API getätigte Anrufe durchlaufen dieselbe Compliance-Prüfung wie Anrufe vom Arbeitsplatz. Eine Nummer auf der Sperrliste oder außerhalb der Anrufzeiten wird abgelehnt.

Wer kann Webhooks sehen und ändern?

Alle können die Liste lesen, aber nur Inhaber, Admins und Manager können Endpunkte hinzufügen, testen oder löschen.

Öffnen Sie die Call-API-Referenz und fügen Sie einen Webhook-Endpunkt hinzu

In der Demo-Konsole können Sie eingehende Anrufe in einer Simulation ausprobieren.

Verwandte Ratgeber