Add a third party to a call

This document explains how to use the /calls/CALL_ID/dial endpoint of the apps API to dial a third party and then add them to an ongoing call. When you make a request to this endpoint, the system automatically dials the third-party's phone number, and the agent's call adapter displays the Calling screen. Adding third parties to calls in this way works regardless of whether the call adapter is running in the agent desktop, in your CRM, or in the CCAI Platform portal. An agent must be on an active call for this endpoint to function.

Call the endpoint

To add a third party to a call, make a POST request to the following endpoint:

https://YOUR_CCAAS_HOST/apps/api/v1/calls/CALL_ID/dial

Replace CALL_ID with the call ID.

Request body

The following is an example of a request body:

{
  "agent_email": "AGENT_EMAIL",
  "phone_number": "PHONE_NUMBER"
}

Replace the following:

  • AGENT_EMAIL: The email address of the agent on the call.
  • PHONE_NUMBER: The phone number of the third party to be added to the call.

Response

The output is similar to the following.

Success response

{
    "message": "Third party dialing initiated",
    "participant": {
        "id": 54321,
        "type": "third_party",
        "status": "connecting"
    }
}

Error responses

  • 400 Bad Request - phone_number or agent_email is missing or empty. Body: {"message": "param is missing or the value is empty: <name>"}.
  • 400 Bad Request - agent_email does not match a known user. Body: {"message": "Invalid agent_email"}.
  • 401 Unauthorized - authentication failed. Body: {"message": "Not Authorized"}.
  • 404 Not Found - no call exists with the supplied call_id. Body: {"message": "Not Found"}.
  • 422 Unprocessable Entity - the agent identified by agent_email is not connected to the call. Body: {"message": "Agent is not connected to the call"}.
  • 422 Unprocessable Entity - the dial couldn't be initiated; covers phone-number normalization failures and provider dial-initiation errors. Body: {"message": "Error dialing third party"}.
  • 500 Internal Server Error - unexpected failure during dial. Body: {"message": "Unexpected error dialing third party"}.