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:
-
In the CCAI Platform portal, click Settings > Developer Settings. If you don't see the Settingsmenu, click Menu.
-
In the Session Data Exportpane, click Manage Data Export Settings. The Session Data Exportpage appears.
-
Go to the External Session Eventspane, and then click the toggle to the on position.
-
Do one or both of the following:
-
To configure external call session events, do the following:
-
Select the Call events - Send call sessions eventcheckbox.
-
In the API Endpointfield, enter the full HTTPS URL of your target API.
-
Enter the username and password. The platform uses these for basic authentication.
-
-
To configure external chat session events, do the following:
-
Select the Chat events - Send chat sessions eventcheckbox.
-
In the API Endpointfield, enter the full HTTPS URL of your target API.
-
Enter the username and password. The platform uses these for basic authentication.
-
-
-
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_atandends_at: ISO 8601 timestamps for the session duration. -
initiator: Identifies the entity that handled the state change—for example,virtual_agent_15oragent_1. -
dispositions: A nested object containingcode,custom_code_id, and any agentnote.
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 OKstatus 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"
}
}
]
}
}
]
}
