3CX 呼叫控制 API 端点规范

/callcontrol

描述：此端点检索特定实体（DN）的状态，包括有关参与者和设备的信息。

端点 URL:

GET /callcontrol

HTTP 方式:

GET

需要身份验证:

Yes

请求参数

• 此请求无需参数。

响应

成功响应：

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

响应主体示例：

错误响应：

• 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.

注意事项

• 访问此端点时，请确保在标头中提供身份验证令牌。

/callcontrol/ws

描述：此端点提供 WebSocket 连接。

端点 URL:

GET /callcontrol/ws

HTTP 方式:

GET

需要身份验证:

Yes

请求参数

• 此请求无需参数。

响应

成功响应：

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

错误响应：

• 401 Unauthorized:

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

注意事项

• 访问此 WebSocket 端点时，请确保在标头中提供身份验证令牌。
• WebSocket 适用于实时通信，在呼叫控制应用程序中，您可能需要获取有关呼叫状态更新的信息（例如，参与者已更新、已接收 dtmf 字符串等）。为此，WebSocket 通知通道是实现此类通信的最佳方式。

通过利用 WebSocket 进行呼叫控制，开发者可以构建响应迅速且功能丰富的应用程序，为用户提供无缝且最新的呼叫管理体验。

/callcontrol/{dnnumber}

描述：此端点根据 DN Number 检索特定实体 (DN) 的所有连接。响应提供与通话关联的设备和参与者的详细信息。

端点 URL:

GET /callcontrol/{dnnumber}

HTTP 方式:

GET

需要身份验证:

Yes

路径参数

响应

成功响应：

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

响应主体示例：

错误响应：

• 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.

注意事项

• 请确保在路径参数中包含 dnnumber，以便访问相关的呼叫控制信息。
• 访问此端点需要身份验证。

/callcontrol/{dnnumber}/devices

描述：此端点检索与所提供 dnnumber 关联的设备信息。响应包含设备详细信息，例如直接号码 (DN)、deviceid 和用户代理。

端点 URL:

GET /callcontrol/{dnnumber}/devices

HTTP 方式:

GET

需要身份验证:

Yes

路径参数

响应

成功响应：

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

响应主体示例：

错误响应：

• 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.

注意事项

• 必须将 dnnumber 作为路径参数包含在内才能检索关联设备。
• 访问此端点需要身份验证。
• 响应包含与指定dnnumber 相关的设备的详细信息。

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

描述：此端点检索与提供的 dnnumber 和 deviceid 关联的特定设备的详细信息。响应包含设备的直接号码 (DN)、设备 ID 和用户代理。

端点 URL:

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

HTTP 方式:

GET

需要身份验证:

Yes

路径参数

响应

成功响应：

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

响应主体示例：

错误响应：

• 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.

注意事项

• dnnumber 和 deviceid 必须作为路径参数包含在 URL 中。
• 访问此端点需要身份验证。
• 响应包含与 dnnumber 关联的指定设备的详细信息。

API Endpoint: /callcontrol/{dnnumber}/participants

描述：此端点检索与特定dnnumber 关联的参与者信息。响应包含参与者状态、直拨号码 (DN)、呼叫者信息和呼叫标识符等详细信息。

端点 URL:

GET /callcontrol/{dnnumber}/participants

HTTP 方式:

GET

需要身份验证:

Yes

路径参数

响应

成功响应：

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

响应主体示例：

错误响应：

• 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.

注意事项

• 必须提供 dnnumber 作为路径参数才能检索关联的参与者。
• 访问此端点需要身份验证。
• 响应包含指定呼叫中涉及的参与者的详细信息。

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

描述：此端点检索与给定 dnnumber 和  id 关联的特定参与者的信息。响应包含参与者状态、直拨号码 (DN)、呼叫者信息和呼叫标识符等详细信息。

端点 URL:

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

HTTP 方式:

GET

需要身份验证:

Yes

路径参数

响应

成功响应：

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

响应主体示例：

错误响应：

• 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.

注意事项

• 必须同时提供 dnnumber 和 id 作为路径参数才能检索特定参与者的信息。
• 访问此端点需要身份验证。
• 响应包含指定通话中涉及的特定参与者的详细信息。

/callcontrol/{dnnumber}/makecall

描述：从 DN 实体发起呼叫。如果 DN 只有一个外观（只有一个注册设备），则呼叫将从该设备发起（见下文）。否则，将启用旧式 MakeCall 服务，并应通过分析 DN 参与者状态来发现呼叫发起状态。此形式是为了向后兼容而存在的，不建议使用。

应用程序应确保能够监控呼叫源 DN，并能够检测 DN 上出现的哪些参与者与请求相对应。

端点 URL:

POST /callcontrol/{dnnumber}/makecall

HTTP 方式:

POST

需要身份验证:

Yes

路径参数

请求主体

响应主体示例：

响应

成功响应：

• 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.

响应主体示例：

错误响应：

• 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.

注意事项

• 请确保在路径参数中提供 dnnumber 才能发起呼叫。
• 使用此端点需要身份验证。
• 请求正文应包含目标号码以及其他与呼叫相关的详细信息。

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

描述：从特定设备（模拟或使用 uacsta）发起呼叫。这种形式的呼叫发起请求保证在响应中指定呼叫发起者。

端点 URL:

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

HTTP 方式:

POST

需要身份验证:

Yes

路径参数

请求主体

请求主体示例：

响应

成功响应：

• 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.

响应主体示例：

错误响应：

• 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.

注意事项

• 请确保在路径参数中同时包含 dnnumber 和 deviceid 以发起呼叫。
• 访问此端点需要身份验证。
• 请求正文应包含目标号码以及发起呼叫的相关详细信息。

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

描述：此端点检索与给定 dnnumber 和 id 关联的特定参与者的原始音频流（PCM 16 位 8000Hz 单声道）。

端点 URL:

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

HTTP 方式:

GET

需要身份验证:

Yes

路径参数

响应

错误响应：

• 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.

注意事项

• 必须同时提供 dnnumber 和 id 作为路径参数，才能检索指定参与者的流数据。
• 访问此端点需要身份验证。

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

描述：此端点为与给定 dnnumber 和 id 关联的特定参与者发起流。应用程序应将原始音频流（PCM 16 位 8000Hz 单声道）发送到服务器。服务器收到的内容将传送给该参与者。

端点 URL:

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

HTTP 方式:

POST

需要身份验证:

Yes

路径参数

响应

成功响应：

• 200 OK

• Description: The stream has been successfully initiated.

错误响应：

• 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.

注意事项

• 访问此端点需要身份验证。
• 必须同时提供 dnnumber 和 id 作为路径参数，才能为指定参与者发起音频流。
• 服务器以 128kbps 的速率上传一方音频流（几乎实时）。外部应用程序也应以平均 128kbps 的速率发布音频流，并尽量减少抖动。使用流媒体，应用程序可以与任何外部服务交互，以实现与呼叫者的语音交互。

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

描述：此端点对与给定 dnnumber 和 id 关联的参与者执行特定操作。操作类型由路径中的 action 参数定义。

端点 URL:

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

HTTP 方式:

POST

需要身份验证:

Yes

路径参数

请求主体

可用的操作类型

适用的原因值

请求主体示例：

响应

成功响应：

• 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.

错误响应：

• 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.

注意事项

• 必须提供 dnnumber、id 和 action 作为路径参数，才能对参与者执行指定的操作。
• 访问此端点需要身份验证。

最后更新

本文档最后更新日期为 2025 年 3 月 12 日

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