3CX Call Control API

Was ist die Call Control API?

Die 3CX Call Control API ist ein einfaches und leistungsstarkes Werkzeug, das die programmgesteuerte Verwaltung von Anrufen ermöglicht. Mithilfe der API können Sie die PBX-Anruffunktionalität direkt in Ihre Drittanbieter-Anwendungen integrieren. Beispiele für Anwendungen, die Sie erstellen können, sind unter anderem:

  • Externe Anrufsteuerung: Anrufe programmgesteuert über Ihre eigenen Anwendungen einleiten, entgegennehmen, vermitteln und beenden.
  • CRM-Integration: Anrufe automatisch aus Ihrem CRM-System heraus starten, Anrufdetails protokollieren und die Kundeninteraktionen optimieren.
  • Outbound-Kampagnen: Eigene Skripte für Outbound-Kampagnen einrichten und anbinden, um komplexe Anruf-Zielgruppenstrategien umzusetzen.
  • KI-Integration: Moderne Sprachmodelle wie die Whisper API nutzen, um mit eingehenden Sprachdaten von Nutzern zu arbeiten.
  • Helpdesk-Automatisierung: Eingehende Support-Anrufe verwalten, an die passenden Agenten weiterleiten und Anrufmetriken nachverfolgen.

Konfigurieren der API-Integration

Gehen Sie in der Verwaltungskonsole 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 (DN für den Zugriff auf den Routenpunkt, die auch für die Autorisierung benötigt wird) an.
  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 über die API überwachen möchten.
  6. Nach der erfolgreichen Erstellung einer neuen API-Instanz erhalten Sie einen API-Schlüssel für Ihre Drittanbieter-Anwendungen. Dieser Schlüssel wird nur einmal angezeigt; speichern Sie ihn daher für die spätere Verwendung gut ab.

Das ist alles! Sie haben die Konfiguration der Telefonanlage erfolgreich abgeschlossen.

Bitte beachten Sie: Sie benötigen eine 8SC+ AI-Lizenz, um 3CX Call Control nutzen zu können.

Wie es funktioniert

RESTful API

Die Call Control API stellt Endpunkte bereit, die sowohl einfach als auch anpassungsfähig für die Durchführung von Anrufoperationen sind. Diese Endpunkte sind sicher konzipiert und beeinträchtigen weder die Kernfunktionen der PBX noch verursachen sie Schäden.

Weitere Informationen finden Sie unter „3CX Call Control API Endpunkt-Spezifikation“

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 ereignisgesteuerte Anrufsteuerung und Zustandsverwaltung.

Gleichzeitige Nutzung von WebSocket und HTTP (GET/POST)

Flexible Kommunikation: WebSocket ersetzt keine traditionellen HTTP-Methoden. Stattdessen ergänzt es diese, indem es als dedizierter Kanal für die Ereigniszustellung fungiert. Während Anwendungen weiterhin GET- und POST-Anfragen für spezifische Daten oder Aktionen verwenden können, ist WebSocket für den Empfang von Echtzeit-Ereignissen optimiert. Diese Flexibilität ermöglicht es einer Anwendung, je nach Anwendungsfall die beste Methode zu wählen – beispielsweise WebSocket für Echtzeit-Updates und HTTP für direkte Anfragen.

Effizienter reine Ereignis-Kanal: WebSocket kann ausschließlich für die Ereigniszustellung eingesetzt werden. Dies gewährleistet eine effiziente Kommunikation, bei der nur die notwendigen Echtzeit-Updates ohne große Nachrichtengrößen übertragen werden – unter Berücksichtigung der Beschränkung von WebSocket hinsichtlich der Nachrichtengröße.

Technischer Überblick

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

Anwendungsanforderung (WebSocketRequest):

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

Server-Antwort (WebSocketResponse):

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

WebSocket-Ereignisse (Benachrichtigungskanal)

In der PBX Call Control API sendet der Server Ereignisse über WebSocket. Dieses Ereignis ist Teil des Systems ExtenalCallFlowEventTypes.Response, das dazu dient, Antworten an die externe Anwendung strukturiert und konsistent zu übermitteln. So funktioniert es:

Server Response with ExternalCallFlowAppHookEvent

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

ExternalCallFlowAppHookEvent {

    EventType=0;

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

    AttachedData=<WebSocketResponse>;

}

Erläuterung der Felder:

  1. EventType=5 (ENUM): Das Feld EventType ist ein Aufzählungswert (ENUM), der den Typ des zustandsbezogenen Ereignisses angibt. Es hilft der externen Anwendung, die Art des Ereignisses zu verstehen und entsprechend zu reagieren.

Enum Number

Beschreibung

0

Upsert

Die Entität wird entweder hinzugefügt oder aktualisiert

1

Remove

Die Entität wurde entfernt

2

DTMFstring

DTMF von Gegenstelle bereitgestellt.

HINWEIS: Das DTMFString-Ereignis ist Teil der Mediensteuerungsfunktionalität. Die Anwendung kann DTMF-Ereignisse nur empfangen, wenn sie zu der Anwendung selbst gehören (d. h. zwischen der Anwendungs-DN und ihrer Gegenstelle).

4

Response

Antwort auf die über WebSocket gesendete Anfrage

  1. Entity: Die Entity repräsentiert den spezifischen Pfad der Anfrage, die die Anwendung ursprünglich gestellt hat. Dieser Pfad entspricht dem in der ursprünglichen WebSocket-Anfrage angegebenen Pfad (z. B. /callcontrol, /callcontrol/{dn} oder /callcontrol/{dn}/participants).

Dies hilft der externen Anwendung zu erkennen, 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 Anfrage-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 „Erste Schritte mit Beispielen für externe Call-Flow-Anwendungen“. Es umfasst:

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

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

Siehe auch

Letztes Update

Dieses Dokument wurde zuletzt am 21. September 2026 aktualisiert.

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