3CX Call Control API

Was ist die Call Control API?

Die 3CX Call Control API ist ein einfaches und leistungsstarkes Tool, mit dem Sie Anrufe programmgesteuert verwalten können. Mithilfe der API können Sie die PBX-Anruffunktionalität jetzt direkt in Ihre Drittanbieteranwendungen integrieren. Beispiele für Apps, die Sie erstellen können, sind:

  • Externe Anrufsteuerung: Initiieren, beantworten, übertragen und beenden Sie Anrufe programmgesteuert aus Ihren eigenen Anwendungen.
  • CRM-Integration: Initiieren Sie Anrufe automatisch aus Ihrem CRM-System, protokollieren Sie Anrufdetails und optimieren Sie Kundeninteraktionen.
  • Outbound-Kampagnen: Richten Sie Ihre eigenen Outbound-Kampagnenskripte für komplexe Anrufzielstrategien ein und verbinden Sie sie.
  • KI-Integration: Verwenden Sie moderne Sprachmodelle wie Whisper API, um mit eingehenden Benutzersprachdaten zu arbeiten.
  • Helpdesk-Automatisierung: Verwalten Sie eingehende Supportanrufe, leiten Sie sie an die entsprechenden Agenten weiter und verfolgen Sie Anrufmetriken.

Konfigurieren der API-Integration

Gehen Sie in der Admin-Konsole im 3CX-Webclient zu Integrationen > API:

  1. Klicken Sie auf die Schaltfläche „Hinzufügen“, um eine neue Client-Anwendung zu erstellen.
  2. Geben Sie die Client-ID an (DN für den Zugriff auf den Routenpunkt, die auch für die Autorisierung benötigt wird).
  3. Wenn Sie den Call Control-Bereich verwenden, aktivieren Sie das Kontrollkästchen „3CX Call Control API-Zugriff“ für diese Anwendung.
  4. (Optional) Geben Sie DID-Nummern für den Routenpunkt an.
  5. (Optional) Geben Sie zusätzliche Nebenstellen an, die Sie mithilfe der API überwachen möchten.
  6. Nachdem Sie erfolgreich eine neue API-Instanz erstellt haben, erhalten Sie einen API-Schlüssel für Ihre Drittanbieteranwendungen. Dieser Schlüssel wird nur einmal angezeigt. Speichern Sie ihn daher unbedingt für die zukünftige Verwendung.

Das war’s! Sie haben die PBX-Konfiguration erfolgreich abgeschlossen.

Bitte beachten: Sie müssen über eine 8SC+ ENT/AI-Lizenz verfügen, um 3CX Call Control verwenden zu können.

Wie es funktioniert

RESTful API

Die Call Control API bietet einfache und anpassbare Endpunkte für die Durchführung von Anrufvorgängen. Diese Endpunkte sind auf Sicherheit ausgelegt, stören die Kernfunktionen der Telefonanlage nicht und verursachen auch keinen Schaden.

Weitere Informationen finden Sie unter “3CX Call Control API Endpoint Specification”

WebSocket

Die WebSocket-Integration in der PBX Call Control API dient als robuster Echtzeit-Kommunikationskanal zwischen externen Anwendungen und dem PBX-Server. Sie verbessert die Interaktion zwischen einer Anwendung und der PBX, insbesondere für die ereignisgesteuerte Anrufsteuerung und Statusverwaltung.

Gleichzeitige Nutzung von WebSocket und HTTP (GET/POST)

Flexible Kommunikation: WebSocket ersetzt keine herkömmlichen HTTP-Methoden. Stattdessen ergänzt es diese, indem es als dedizierter Kanal für die Ereignisübermittlung fungiert. Während Anwendungen weiterhin GET- und POST-Anfragen für bestimmte Daten oder Aktionen verwenden können, ist WebSocket für den Empfang von Echtzeitereignissen optimiert. Diese Flexibilität ermöglicht es einer Anwendung, je nach Anwendungsfall die beste Methode auszuwählen, z. B. die Verwendung von WebSocket für Echtzeitaktualisierungen und HTTP für direkte Anfragen.

Effizienter Event-only-Kanal: WebSocket kann ausschließlich für die Ereignisübermittlung eingesetzt werden und gewährleistet eine effiziente Kommunikation, bei der nur die notwendigen Echtzeit-Updates ohne große Nachrichtengrößen übertragen werden – angesichts der Beschränkung der Nachrichtengröße von WebSocket.

Technischer Überblick

Die WebSocket-Kommunikation in der PBX Call Control API folgt einem strukturierten Format für Anfragen und Antworten und gewährleistet so Klarheit und Konsistenz bei der Interaktion:

Anwendungsanforderung (WebSocketRequest):

  • Anwendungen können Echtzeitanforderungen über den WebSocket senden, indem sie eine WebSocketRequest-Nachricht senden.
  • Jede Anforderung enthält:
  • RequestID: Eine von der externen Anwendung bereitgestellte ID zum Verfolgen der Antwort.
  • Path: Der API-Pfad (ähnlich dem in HTTP-GET-Anfragen verwendeten), wie z. B. /callcontrol, /callcontrol/{dn}, or /callcontrol/{dn}/participants/{id}.
  • RequestData: Dies ist für Anrufsteuerungsaktionen wie make call oder divert erforderlich und für GET-Anfragen optional.

Server-Antwort (WebSocketResponse):

  • Der Server antwortet mit einer WebSocketResponse, die Folgendes enthält:
  • RequestID: Die ID der Anfrage, die sicherstellt, dass die externe Anwendung die Antwort auf die Anfrage zuordnen kann.
  • Path: Der Pfad der Anfrage (z.B. /callcontrol/100).
  • StatusCode: Der HTTP-Statuscode, der den Erfolg oder Misserfolg der Anforderung angibt.
  • Response: Der Inhalt der Antwort, der je nach Anforderungspfad variiert. 

WebSocket-Ereignisse (Benachrichtigungskanal)

In der PBX Call Control API sendet der Server Ereignisse über den WebSocket. Dieses Ereignis ist Teil des ExtenalCallFlowEventTypes.Response-Systems, das Antworten auf strukturierte und konsistente Weise an die externe Anwendung übermitteln soll. Hier ist eine Erklärung, wie das funktioniert:

Serverantwort mit ExternalCallFlowAppHookEvent

Wenn sich überwachte DNS-Zustände ändern, antwortet der Server schließlich mit einem Ereignis an eine externe Anwendung über WebSocket. Das Ereignis hat den folgenden Typ:

ExternalCallFlowAppHookEvent {

    EventType=0;

    Entity=<path as was specified in the request>;

    AttachedData=<WebSocketResponse>;

}

Felder erklärt:

  1. EventType=5 (ENUM): Das Feld EventType ist ein Zahlenwert (ENUM), der den Typ des mit dem Status verknüpften Ereignisses angibt. Es hilft der externen Anwendung, die Art des Ereignisses zu verstehen und entsprechend zu reagieren.

Enum Nummer

Beschreibung

0

Upsert

Die Entität wird entweder hinzugefügt oder aktualisiert

1

Remove

Die Entität wurde entfernt

2

DTMFstring

DTMF-Anbieter durch Gegenstelle

4

Response

Antwort auf die über WebSocket gesendete Anfrage

  1. Entity: Die Entität stellt den spezifischen Pfad der Anfrage dar, die die Anwendung ursprünglich gestellt hat. Dieser Pfad ist derselbe wie der in der ursprünglichen WebSocket-Anfrage angegebene. (z.B. /callcontrol, /callcontrol/{dn}, oder /callcontrol/{dn}/participants).

Dadurch erkennt die externe Anwendung, auf welchen Teil der API sich die Antwort bezieht.

  1. AttachedData: Die AttachedData enthalten die eigentliche WebSocketResponse vom Server. Dieses Objekt enthält wichtige Details wie die Anforderungs-ID, den HTTP-Statuscode und die Antwortdaten.

Externe Anwendungsbeispiele

Detaillierte Schritte zum Einrichten einer externen Call Flow-Anwendung mit der PBX Call Control API finden Sie im Dokument „Getting Started with External Call Flow Application Examples“. Es enthält:

  • PBX-Konfiguration: Anweisungen zum Hinzufügen einer Client-Anwendung im 3CX-Webclient, zum Konfigurieren der API und zum Abrufen des API-Schlüssels.
  • Einrichtung einer externen Webanwendung: Schritte zum Einrichten der externen Anwendung, einschließlich der Installation von Node.js, des Herunterladens der erforderlichen Dateien, des Ausführens von Beispielen (IVR, Outbound-Kampagne, Dialer) und des Konfigurierens der Anwendung in Ihrer lokalen Umgebung.

Dieses Dokument behandelt auch die Ausführung grundlegender Beispiele zur Anrufsteuerung sowie das Einrichten einer benutzerdefinierten IVR-, Dialer- und Outbound-Kampagne zur Integration in das 3CX-PBX-System.

Siehe auch

Letztes Update

Dieses Dokument wurde zuletzt am 24. Juni 2025 aktualisiert.

https://www.3cx.de/docs/call-control-api/