3CX Call Control API

What is the Call Control API?

3CX Call control API is a simple and powerful tool, which allows managing calls programmatically. Utilizing API you can now integrate PBX call functionality directly to your 3rd party applications. Examples of apps that you can build include:

  • External Call Control: Initiate, answer, transfer, terminate calls programmatically from your own applications.
  • CRM Integration: Automatically initiate calls from your CRM system, log call details, and streamline customer interactions.
  • Outbound Campaigns: Setup and connect your own outbound campaign scripts for complex call targeting strategies.
  • AI Integration: Use modern language models, like Whisper API to work with incoming user voice data.
  • Help Desk Automation: Manage incoming support calls, route them to the appropriate agents, and track call metrics.

Configuring the API Integration

From the Admin Console in the 3CX Web Client, go to Integrations > API:

  1. Press the Add button to create a new client application.
  2. Specify the Client ID (DN for accessing the route point, which is also needed for authorization).If using the Call Control scope, check the 3CX Call Control API Access checkbox for this application.(Optional) Specify DID numbers for the Route Point.(Optional) Specify additional extensions you want to monitor using the API.After successfully creating a new API instance, you will receive an API key for your third-party applications. This key will be shown only once, so be sure to save it for future use.That's it! You've successfully completed the PBX configuration.Please note: You must have an 8SC+ Enterprise license to use 3CX Call Control.How it WorksRESTful APICall Control API provides endpoints that are both simple and adaptable for carrying out call operations. These endpoints are designed to be secure and will not disrupt core PBX functions or cause any damage. For more information check “3CX Call Control API Endpoint Specification”WebSocketThe WebSocket integration in the PBX Call Control API serves as a robust, real-time communication channel between external applications and the PBX server. It enhances the interaction between an application and the PBX, particularly for event-driven call control and state management. Simultaneous Usage of WebSocket and HTTP (GET/POST)

    Flexible Communication: WebSocket doesn’t replace traditional HTTP methods. Instead, it complements them by acting as a dedicated channel for event delivery. While applications can still use GET and POST requests for specific data or actions, WebSocket is optimized for receiving real-time events. This flexibility allows an application to choose the best method depending upon the use case, such as using WebSocket for real-time updates and HTTP for direct requests.

    Efficient Event-Only Channel: WebSocket can be employed solely for event delivery, ensuring efficient communication where only the necessary real-time updates are transmitted without large message sizes - given WebSocket's limitation on message size.

    Technical Overview

    The WebSocket communication in the PBX Call Control API follows a structured format for requests and responses, ensuring clarity and consistency in interaction:

    Application Request (WebSocketRequest):

    • Applications can send real-time requests through the WebSocket by sending a WebSocketRequest message.
    • Each request includes:
    • RequestID: An ID provided by the external application to track the response.
    • Path: The API path (similar to the one used in HTTP GET requests), such as /callcontrol, /callcontrol/{dn}, or /callcontrol/{dn}/participants/{id}.
    • RequestData: This is required for call control actions like makecall or divert and is optional for GET requests.

    Server Response (WebSocketResponse):

    • The server responds with a WebSocketResponse, which includes:
    • RequestID: The ID of the request, ensuring the external application can match the response to the request.
    • Path: The path of the request (e.g., /callcontrol/100).
    • StatusCode: The HTTP status code, indicating the success or failure of the request.
    • Response: The content of the response, which varies depending upon the request path.

    WebSocket Events (Notification Channel)

    In the PBX Call Control API, the server sends events through the WebSocket. This event is part of the ExtenalCallFlowEventTypes.Response system, designed to convey responses to the external application in a structured and consistent way. Here’s an explanation of how this works:

    Server Response with ExternalCallFlowAppHookEvent

    When monitored DNS states are changing, the server eventually responds with an event to an external application through WebSocket. The event has the following type:

    ExternalCallFlowAppHookEvent {

        EventType=0;

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

        AttachedData=<WebSocketResponse>;

    }

    Fields Explained:

    1. EventType=5 (ENUM): The EventType field is an enumerated value (ENUM) that indicates the type of event related to state. It helps the external application understand the nature of the event and respond accordingly.

    Enum Number

    Description

    0

    Upsert

    The entity is either added or updated

    1

    Remove

    The entity has been removed

    2

    DTMFstring

    DTMF provider by remote party.

    NOTE: The DTMFString event is part of the media control functionality. The application can receive DTMF events only if they belong to the application itself (i.e., between the Application DN and its remote party).

    4

    Response

    Response to the request sent over WebSocket

    1. Entity: The Entity represents the specific path of the request that the application originally made. This path is the same as the one specified in the original WebSocket request (e.g., /callcontrol, /callcontrol/{dn}, or /callcontrol/{dn}/participants).

    This helps the external application know which part of the API the response relates to.

    1. AttachedData: The AttachedData contains the actual WebSocketResponse from the server. This object includes crucial details like the request ID, the HTTP status code, and the response data.

    External Application Examples

    For detailed steps on setting up an external call flow application with the PBX Call Control API, please refer to the "Getting Started with External Call Flow Application Examples" document. It includes:

    • PBX Configuration: Instructions for adding a client application in the 3CX Web Client, configuring the API, and obtaining the API key.
    • External Web Application Setup: Steps for setting up the external application, including installing Node.js, downloading the necessary files, running examples (IVR, Outbound Campaign, Dialer), and configuring the application on your local environment.

    This document also covers running basic examples for call control, and setting up a custom IVR, dialer, and outbound campaign for integration with the 3CX PBX system.

    See also

    Last updated

    This document was last updated 13 May 2025

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