Integrationen & API

Passt in die Werkzeuge, in denen Ihr Team bereits arbeitet.

CRM-Synchronisation, Webhooks und eine REST-API für Rufnummern, Anrufe und Analysen.

API mit Entwicklerfokus

Nummern bereitstellen, Gesundheitswerte lesen und CDRs abrufen — über eine dokumentierte REST-API.

Die API ist nach Ressourcen aufgebaut und antwortet in JSON. Zeitangaben sind UTC im ISO-8601-Format, Beträge in Cent als Ganzzahl. Es gibt keine SDK-Pflicht: Jeder HTTP-Client genügt.

curl "https://api.xetel.de/v1/rates/lookup?dst=4989" \
  -H "Authorization: Bearer xe_live_9f3a72c1" \
  -H "Accept: application/json"

Ressourcen

Was die API abdeckt.

Rufnummern

Bestand abfragen, Verfügbarkeit prüfen, Rufnummern zuteilen und wieder freigeben. Jede Rufnummer trägt ihren Zustand und ihren Gesundheitswert.

Anrufe

Anruf per Click-to-Call auslösen, laufende Anrufe abfragen, Anruf beenden. Der Aufbau erfolgt zuerst zum Arbeitsplatz, dann zum Ziel.

Verbindungsnachweise

Abgeschlossene Verbindungen mit Zeitpunkt, Richtung, angezeigter Rufnummer, Ziel, Dauer und Ergebnis. Seitenweise abrufbar für die Übernahme ins Data Warehouse.

Kennzahlen

Annahmequote und Gesundheitswert je Rufnummer und je Kampagne über einen Zeitraum — ohne die Einzelverbindungen selbst auswerten zu müssen.

Benutzer und Nebenstellen

Benutzer anlegen, Rollen und Teams setzen, Nebenstellen zuweisen. Geeignet für die Übernahme aus einem Identitätsverzeichnis.

Warteschlangen

Zustand einer Warteschlange abfragen: wartende Anrufe, längste Wartezeit, angemeldete Agenten. Grundlage für eigene Wallboards.

Webhooks

Ereignisse, statt zu pollen.

Statt die API im Sekundentakt abzufragen, hinterlegen Sie eine Adresse und erhalten Ereignisse, sobald sie eintreten.

Anruf begonnen

Wird ausgelöst, sobald eine Verbindung aufgebaut ist. Enthält Richtung, angezeigte Rufnummer und Ziel — geeignet, um im CRM den Datensatz zu öffnen.

Anruf beendet

Enthält Dauer, Ergebnis und die Kennung der Aufzeichnung, sofern aktiviert. Geeignet, um die Aktivität im CRM zu protokollieren.

Rufnummer markiert

Wird ausgelöst, wenn der Gesundheitswert einer Rufnummer unter die Schwelle fällt und die Nummer ruht. Geeignet für eine Meldung an Ihr Betriebsteam.

Voicemail eingegangen

Enthält Rufnummer, Zeitpunkt und die Kennung der Aufzeichnung. Geeignet, um im Service ein Ticket anzulegen.

Zustellung

Jede Zustellung ist signiert; prüfen Sie die Signatur, bevor Sie den Rumpf verarbeiten. Antwortet Ihr Endpunkt nicht mit 2xx, wiederholen wir die Zustellung mit wachsendem Abstand. Ereignisse können mehrfach ankommen — verarbeiten Sie sie anhand der Ereigniskennung idempotent.

CRM-Anbindung

Drei Muster, die in der Praxis genügen.

Fast jede CRM-Anbindung besteht aus einer Kombination dieser drei Muster. Fertige Anbindungen an Salesforce, HubSpot, Microsoft Dynamics und Zoho sowie kundenspezifische Systeme bieten wir als Professional Services an.

Klick zum Anrufen

Ein Klick auf die Rufnummer im CRM löst über die API einen Anruf aus. Zuerst klingelt der Arbeitsplatz des Agenten, dann wird das Ziel gerufen. Die angezeigte Rufnummer bestimmt die Kampagnenzuordnung.

Datensatz beim Klingeln öffnen

Das Ereignis „Anruf begonnen“ liefert die Rufnummer des Anrufers. Ihre Anwendung sucht den Datensatz und öffnet ihn am Arbeitsplatz des Agenten, bevor er abnimmt.

Aktivität zurückschreiben

Nach dem Ereignis „Anruf beendet“ legen Sie im CRM eine Aktivität mit Dauer, Ergebnis und Verweis auf die Aufzeichnung an. Damit stimmen Gesprächsberichte und CRM-Auswertung überein.

Authentifizierung und Grenzen

Zugriff, Fehler, Ratenbegrenzung.

Schlüssel im Header

Jede Anfrage trägt einen API-Schlüssel im Authorization-Header. Schlüssel werden im Portal erzeugt, in ihren Rechten eingeschränkt und einzeln widerrufen.

Getrennte Schlüssel je Zweck

Verwenden Sie je Integration einen eigenen Schlüssel. Bei einem Verdachtsfall widerrufen Sie nur diesen einen und legen nicht alle Anbindungen still.

Ratenbegrenzung

Anfragen sind pro Schlüssel begrenzt. Wird die Grenze überschritten, antwortet die API mit dem Status 429 und einem Hinweis, wann der nächste Versuch zulässig ist.

Fehlerformat

Fehler kommen mit passendem HTTP-Status und einem stabilen Fehlercode im Rumpf. Behandeln Sie den Code, nicht den Text.

Wiederholungen

Schreibende Anfragen nehmen einen Idempotenzschlüssel entgegen. Eine wiederholte Anfrage mit demselben Schlüssel löst keinen zweiten Anruf aus.

Nur über TLS

Die API ist ausschließlich über HTTPS erreichbar. Unverschlüsselte Anfragen werden abgewiesen, nicht umgeleitet.

Aus der Praxis

Was bei Anbindungen erfahrungsgemäß schiefgeht.

Die meisten Probleme bei Telefonie-Integrationen sind nicht spezifisch für XETEL. Sie treten in derselben Form bei jedem Anbieter auf.

Rufnummernformat

Behandeln Sie Rufnummern konsequent im Format E.164 mit führendem Pluszeichen. Wer Ortsvorwahlen ohne Länderkennung speichert, findet den Datensatz beim eingehenden Anruf nicht wieder.

Zeitzonen

Die API liefert Zeitangaben in UTC. Rechnen Sie erst bei der Anzeige um. Berichte, die lokale Zeit speichern, driften bei der Zeitumstellung auseinander.

Doppelte Aktivitäten

Webhooks können mehrfach ankommen. Ohne Prüfung auf die Ereigniskennung entstehen doppelte Aktivitäten im CRM — der häufigste Fehler bei der ersten Anbindung.

Synchrone Verarbeitung

Nehmen Sie das Ereignis an, bestätigen Sie mit 2xx und verarbeiten Sie es danach. Wer im Webhook-Handler auf das CRM wartet, produziert Zeitüberschreitungen und damit Wiederholungen.

Unterdrückte Rufnummer

Nicht jeder eingehende Anruf bringt eine Rufnummer mit. Ihr Bildschirmsprung braucht einen definierten Weg für den Fall ohne Rufnummer.

Schlüssel im Quelltext

API-Schlüssel gehören in die Konfiguration, nicht in das Repository. Ein Schlüssel je Integration hält den Schaden bei einem Vorfall klein.

Häufige Fragen

Gibt es fertige CRM-Anbindungen?

Die API und die Webhooks sind in der Plattform-Lizenz enthalten. Fertige Anbindungen an Salesforce, HubSpot, Microsoft Dynamics, Zoho und kundenspezifische Systeme sind Professional Services und werden individuell angeboten.

Brauche ich ein SDK?

Nein. Die API ist eine REST-Schnittstelle mit JSON. Jeder HTTP-Client genügt. Für den Einstieg reicht ein Aufruf mit curl.

Wie sichere ich Webhooks ab?

Jede Zustellung ist signiert. Prüfen Sie die Signatur, bevor Sie den Rumpf verarbeiten, und verarbeiten Sie Ereignisse anhand der Ereigniskennung idempotent, da eine Zustellung wiederholt werden kann.

Wie hoch ist die Ratenbegrenzung?

Die Grenze gilt pro API-Schlüssel und ist in der Dokumentation je Ressource ausgewiesen. Wird sie überschritten, antwortet die API mit dem Status 429 und einem Hinweis auf den frühesten nächsten Versuch.

Kann ich Verbindungsnachweise in mein Data Warehouse übernehmen?

Ja. Verbindungsnachweise sind seitenweise über einen Zeitraum abrufbar und enthalten Zeitpunkt, Richtung, angezeigte Rufnummer, Ziel, Dauer und Ergebnis.

Was passiert bei einem Ausfall unseres Webhook-Endpunkts?

Antwortet Ihr Endpunkt nicht mit einem 2xx-Status, wiederholen wir die Zustellung mit wachsendem Abstand. Für längere Ausfälle holen Sie die betroffenen Vorgänge anschließend über die API nach.