The external session events capability enables real-time data streaming from
the CCAI Platform to your external systems using webhooks. This provides
immediate visibility into session lifecycles for custom reporting, CRM record
updates, or automated post-interaction workflows.

External session events provide a push-based mechanism to notify your server
whenever a chat or voice call changes state. By providing an API endpoint, the
CCAI Platform will POST JSON-formatted event data to your infrastructure as
transitions occur---for example, call connected, agent assigned, session
disconnected.

## Configure external session events

To configure external session events, follow these steps:

1. In the CCAI Platform portal, click **Settings \> Developer Settings** .
   If you don't see the **Settings** menu, click **Menu**.

2. In the **Session Data Export** pane, click **Manage Data Export Settings** .
   The **Session Data Export** page appears.

3. Go to the **External Session Events** pane, and then click the toggle to the
   on position.

4. Do one or both of the following:

   - To configure external call session events, do the following:

     1. Select the **Call events - Send call sessions event** checkbox.

     2. In the **API Endpoint** field, enter the full HTTPS URL of your
        target API.

     3. Enter the username and password. The platform uses these for basic
        authentication.

   - To configure external chat session events, do the following:

     1. Select the **Chat events - Send chat sessions event** checkbox.

     2. In the **API Endpoint** field, enter the full HTTPS URL of your
        target API.

     3. Enter the username and password. The platform uses these for basic
        authentication.

5. Click **Save**.

## Event lifecycle and state logic

As a session progresses, CCAI Platform sends multiple updates. Each
update enriches the `item` object with more metadata as it becomes available.

### State progression table

| Event order | State | Participant status | Key data points added |
|---|---|---|---|
| **1. Start** | `connected` | External: `connected` | `call_id`, Customer `dn` (phone number). |
| **2. Routing** | `connected` | External: `connected` | `queue_path_names`, `initiator` (Virtual Agent). |
| **3. Assigned** | `connected` | Agent: `accepted` | Live agent name and ID are added. |
| **4. Active** | `connected` | Agent: `connected` | Media stream established (conversation starts). |
| **5. End** | `disconnected` | Both: `disconnected` | `ends_at` timestamp is populated. |
| **6. Final** | `disconnected` | Agent: `dispositionSubmitted` | `dispositions` object containing wrap-up codes. |

## Event data schema reference

Events are sent to the webhook in an object. Each webhook event has the same
structure, which is shown in the following table:

### Root object

| Field | Type | Description |
|---|---|---|
| `count` | Integer | Number of event objects in the current payload. |
| `events` | Array | A collection of event objects containing session details. |

### Key session fields

- **`event_id`**: A UUID for the event notification.
- **`timestamp`**: Epoch time in milliseconds for when the event was generated.
- **`connected_at`** and **`ends_at`**: ISO 8601 timestamps for the session duration.
- **`initiator`** : Identifies the entity that handled the state change---for example, `virtual_agent_15` or `agent_1`.
- **`dispositions`** : A nested object containing `code`, `custom_code_id`, and any agent `note`.

## Security

All requests are sent with a standard Authorization header:
`Authorization: Basic <base64_encoded_credentials>`

## Delivery requirements

- **Method:** `POST`
- **Content-Type:** `application/json`
- **Timeout:** Your server should respond within five seconds.
- **Acknowledgement:** Your endpoint must return a `200 OK` status code. The platform might use exponential backoff retries if a non-200 code is received.

## Sample payloads

The following are sample payloads received in event messages to the webhook.

### Active conversation (media connected)

    {
      "count": 1,
      "events": [
        {
          "event_id": "fc066edb-d99f-4db4-ba04-fb5dfea0e86a",
          "timestamp": 1767874769480,
          "type": "CallState",
          "item": {
            "call_id": 1395,
            "state": "connected",
            "queue_path_names": "Test/Talk to Andrew/English",
            "participants": [
              { "state": "connected", "type": "external", "dn": "+15555555555" },
              { "state": "connected", "type": "agent", "name": "Joe Smith", "agent_number": "528431" }
            ]
          }
        }
      ]
    }

### Final disposition (post-call work)

    {
      "count": 1,
      "events": [
        {
          "event_id": "479798ff-b1ed-4a5c-a910-17a7edb3f283",
          "timestamp": 1767874769480,
          "type": "CallState",
          "item": {
            "call_id": 1395,
            "state": "disconnected",
            "participants": [
              {
                "type": "agent",
                "state": "dispositionSubmitted",
                "dispositions": {
                  "code": "Call completed",
                  "custom_code_id": "callComplete",
                  "note": "none"
                }
              }
            ]
          }
        }
      ]
    }