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"}`.