3CX Call Control API Endpoint Specification

/callcontrol

Description: This endpoint retrieves state of the specific entity (DN), including information about the participants and devices.

Endpoint URL:

GET /callcontrol

HTTP Method:

GET

Authentication Required:

Yes

Request Parameters

• No parameters required for this request.

Response

Success Response:

• Status Code: 200 OK
• Content Type: application/json

Response Body Example:

Error Responses:

• 401 Unauthorized:

• Content Type: application/json
• The request requires valid user authentication.

• 403 Forbidden:

• Content Type: application/json
• The server understood the request, but the user does not have the necessary permissions.

Notes

• Ensure that the authentication token is provided in the header when accessing this endpoint.

/callcontrol/ws

Description: This endpoint provides a WebSocket connection.

Endpoint URL:

GET /callcontrol/ws

HTTP Method:

GET

Authentication Required:

Yes

Request Parameters

• No parameters are required for this request.

Response

Success Response:

• Status Code: 200 OK
• Description: The request was successful, and the WebSocket connection is established.

Error Responses:

• 401 Unauthorized:

• The request requires valid user authentication.
• This error occurs if the API key or authentication token is missing or incorrect.

Notes

• Ensure that the authentication token is provided in the header when accessing this WebSocket endpoint.
• WebSocket is useful for real-time communication, in Call Control Applications you probably need to get information about call state updates (eg. participant updated, dtmf string received, etc.) For these purposes the websocket notification channel is the best way to achieve this communication.

By leveraging WebSocket for call control, developers can build responsive and feature-rich applications that provide users with a seamless and up-to-date call management experience.

/callcontrol/{dnnumber}

Description: This endpoint retrieves all connections of the specific entity (DN) based on dnnumber. The response provides details about the devices and participants associated with the call.

Endpoint URL:

GET /callcontrol/{dnnumber}

HTTP Method:

GET

Authentication Required:

Yes

Path Parameters

Response

Success Response:

• Status Code: 200 OK
• Content Type: application/json

Response Body Example:

Error Responses:

• 401 Unauthorized:

• The request requires valid user authentication.

• 403 Forbidden:

• The server understands the request, but the client does not have the necessary permissions to access this resource.

Notes

• Make sure to include the dnnumber in the path parameter to access the relevant call control information.
• Authentication is required for accessing this endpoint.

/callcontrol/{dnnumber}/devices

Description: This endpoint retrieves information about the devices associated with the provided dnnumber. The response includes device details like the Direct Number (DN), device ID, and user agent.

Endpoint URL:

GET /callcontrol/{dnnumber}/devices

HTTP Method:

GET

Authentication Required:

Yes

Path Parameters

Response

Success Response:

• Status Code: 200 OK
• Content Type: application/json

Response Body Example:

Error Responses:

• 401 Unauthorized:

• The request requires valid user authentication.

• 403 Forbidden:

• The server understands the request, but the client does not have the necessary permissions to access this resource.

Notes

• The dnnumber must be included as a path parameter to retrieve the associated devices.
• Authentication is required for accessing this endpoint.
• The response includes detailed information about the devices related to the specified dnnumber.

/callcontrol/{dnnumber}/devices/{deviceid}

Description: This endpoint retrieves details about a specific device associated with the provided dnnumber and deviceid. The response includes the device's Direct Number (DN), device ID, and user agent.

Endpoint URL:

GET /callcontrol/{dnnumber}/devices/{deviceid}

HTTP Method:

GET

Authentication Required:

Yes

Path Parameters

Response

Success Response:

• Status Code: 200 OK
• Content Type: application/json

Response Body Example:

Error Responses:

• 401 Unauthorized:

• The request requires valid user authentication.

• 403 Forbidden:

• The server understands the request, but the client does not have the necessary permissions to access this resource.

• 404 Not Found:

• The requested resource could not be found.

Notes

• The dnnumber and deviceid must be included as path parameters in the URL.
• Authentication is required for accessing this endpoint.
• The response includes detailed information about the specified device associated with the dnnumber.

API Endpoint: /callcontrol/{dnnumber}/participants

Description: This endpoint retrieves information about the participants associated with a specific dnnumber. The response includes details such as the participant’s status, Direct Number (DN), caller information, and call identifiers.

Endpoint URL:

GET /callcontrol/{dnnumber}/participants

HTTP Method:

GET

Authentication Required:

Yes

Path Parameters

Response

Success Response:

• Status Code: 200 OK
• Content Type: application/json

Response Body Example:

Error Responses:

• 401 Unauthorized:

• The request requires valid user authentication.

• 403 Forbidden:

• The server understands the request, but the client does not have the necessary permissions to access this resource.

Notes

• The dnnumber must be provided as a path parameter to retrieve the associated participants.
• Authentication is required for accessing this endpoint.
• The response includes detailed information about the participants involved in the specified calls.

API Endpoint: /callcontrol/{dnnumber}/participants/{id}

Description: This endpoint retrieves information about a specific participant associated with a given dnnumber and id. The response includes details such as the participant’s status, Direct Number (DN), caller information, and call identifiers.

Endpoint URL:

GET /callcontrol/{dnnumber}/participants/{id}

HTTP Method:

GET

Authentication Required:

Yes

Path Parameters

Response

Success Response:

• Status Code: 200 OK
• Content Type: application/json

Response Body Example:

Error Responses:

• 401 Unauthorized:

• The request requires valid user authentication.

• 403 Forbidden:

• The server understands the request, but the client does not have the necessary permissions to access this resource.

• 404 Not Found:

• The specified participant with the provided id could not be found.

Notes

• Both the dnnumber and id must be provided as path parameters to retrieve the specific participant's information.
• Authentication is required for accessing this endpoint.
• The response includes detailed information about the specific participant involved in the specified call.

/callcontrol/{dnnumber}/makecall

Description: Initiates call from the DN entity. In case if the DN has only a single appearance (only one registered device) the call is initiated from that device (see below). Otherwise, legacy MakeCall service is engaged and call initiation state should be discovered using analysis of the DN participant state. This form exists for backward compatibility and is not recommended for use.

Application should be sure that it will be able to monitor call source DN and be able to detect which of the participants appeared on the DN corresponds to the request.

Endpoint URL:

POST /callcontrol/{dnnumber}/makecall

HTTP Method:

POST

Authentication Required:

Yes

Path Parameters

Request Body

Request Body Example:

Response

Success Responses:

• 200 Accepted

• Content Type: application/json

• 202 Accepted

• Content Type: application/json
• Description: The request has been accepted for processing, but the processing has not been completed yet.

Response Body Example:

Error Responses:

• 401 Unauthorized:
  The request requires valid user authentication.
• 403 Forbidden:
  The server understands the request but refuses to authorize it.
• 422 Unprocessable Content:
  The server understands the request but cannot process it.
• 424 Failed Dependency:
  The request failed due to a failed dependency.

Notes

• Ensure that the dnnumber is provided in the path parameter to initiate the call.
• Authentication is required to use this endpoint.
• The request body should include the destination number and other relevant details for making the call.

/callcontrol/{dnnumber}/devices/{deviceid}/makecall

Description: Initiates call from the specific device (emulated or using uacsta).This form of call initiation request guarantees that the call initiator will be specified in the response.

Endpoint URL:

POST /callcontrol/{dnnumber}/devices/{deviceid}/makecall

HTTP Method:

POST

Authentication Required:

Yes

Path Parameters

Request Body

Request Body Example:

Response

Success Responses:

• 200 Accepted

• Content Type: application/json

• 202 Accepted

• Content Type: application/json
• Description: The request has been accepted for processing but is not yet completed.

Response Body Example:

Error Responses:

• 401 Unauthorized:
  The request requires valid user authentication.
• 403 Forbidden:
  The server understands the request but refuses to authorize it.
• 422 Unprocessable Content:
  The server understands the request but cannot process it.
• 424 Failed Dependency:
  The request failed due to a failed dependency.

Notes

• Make sure to include both the dnnumber and deviceid in the path parameters to initiate the call.
• Authentication is required to access this endpoint.
• The request body should include the destination number and relevant details for making the call.

/callcontrol/{dnnumber}/participants/{id}/stream

Description: This endpoint retrieves a raw audio stream (PCM 16-bit 8000Hz mono) for a specific participant associated with a given dnnumber and id.

Endpoint URL:

GET /callcontrol/{dnnumber}/participants/{id}/stream

HTTP Method:

GET

Authentication Required:

Yes

Path Parameters

Response

Error Responses:

• 401 Unauthorized:
  The request requires valid user authentication.
• 403 Forbidden:
  The server understands the request but refuses to authorize it.
• 404 Not Found:
  The requested resource (the specific participant with the provided id) could not be found.
• 424 Failed Dependency:
  The request failed due to a failed dependency.

Notes

• Both the dnnumber and id must be provided as path parameters to retrieve the stream data for the specified participant.
• Authentication is required for accessing this endpoint.

/callcontrol/{dnnumber}/participants/{id}/stream

Description: This endpoint initiates a stream for a specific participant associated with a given dnnumber and id. Application should post raw audio stream (PCM 16-bit 8000Hz mono) to the server. The content arrived on the server will be delivered to the party.

Endpoint URL:

POST /callcontrol/{dnnumber}/participants/{id}/stream

HTTP Method:

POST

Authentication Required:

Yes

Path Parameters

Response

Success Response:

• 200 OK

• Description: The stream has been successfully initiated.

Error Responses:

• 401 Unauthorized:
  The request requires valid user authentication.
• 403 Forbidden:
  The server understands the request but refuses to authorize it.
• 404 Not Found:
  The specified participant or resource could not be found.
• 424 Failed Dependency:
  The request failed due to a failed dependency.

Notes

• Authentication is required to access this endpoint.
• Both the dnnumber and id must be provided as path parameters to initiate the stream for the specified participant.
• Server uploads a party audio stream with 128kbps rate. (almost real time) External applications should also post the stream with an average 128kbps rate and should minimize jitter. Using streaming, the applications can engage any external services to implement voice interactions with the caller.

/callcontrol/{dnnumber}/participants/{id}/{action}

Description: This endpoint performs a specific action on a participant associated with a given dnnumber and id. The type of action is defined by the action parameter in the path.

Endpoint URL:

POST /callcontrol/{dnnumber}/participants/{id}/{action}

HTTP Method:

POST

Authentication Required:

Yes

Path Parameters

Request Body

Available Action Types

Applicable Reason Values

Request Body Example:

Response

Success Responses:

• 200 Accepted

• Content Type: application/json

• 202 Accepted

• Content Type: application/json
• Description: The request has been accepted for processing but has not been completed yet.

Error Responses:

• 401 Unauthorized:
  The request requires valid user authentication.
• 403 Forbidden:
  The server understands the request but refuses to authorize it.
• 404 Not Found:
  The specified participant or resource could not be found.
• 422 Unprocessable Content:
  The server understands the request but cannot process it.
• 424 Failed Dependency:
  The request failed due to a failed dependency.

Notes

• The dnnumber, id, and action must be provided as path parameters to perform the specified action on the participant.
• Authentication is required to access this endpoint.

Last updated

This document was last updated 19 March 2025

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