Webhook Events Reference
Here you’ll find details about each event our system emits, including attributes, examples, and usage notes. These events are typically sent to your configured webhook endpoint whenever relevant actions occur in a call’s lifecycle.
Overview
Our platform uses a series of events to convey real-time updates about call statuses, transcripts, variable resolution, tool usage, and more. Each event has a consistent JSON structure and includes:
-
A
typefield, e.g.,event_call_status_updated -
A
timestamp(Unix time) -
A unique
call_idto identify the call -
Event-specific attributes
Below is a breakdown of each event type, detailing its attributes and when it’s fired. Click an event name to jump directly to its details.
Event List
A. event_call_status_updated
Description
Emitted whenever a call’s status changes, from initial reception/dialing up to completion or redirection.
Attributes
| Attribute | Type | Values | Description | Example |
|---|---|---|---|---|
| call_type | String | phone_call, web_call | Indicates whether the call is a traditional phone call or a web-based call. | phone_call |
| direction | String | inbound, outbound | Specifies if the call was received (inbound) or made (outbound). | inbound |
| status | String | initiated, ringing, connected, completed, redirection_completed, failed, busy, no_answer, canceled | Describes the current state of the call. | ringing |
| from_phone_number (Optional) | String | — | The phone number that initiated the call. | +1234567890 |
| to_phone_number (Optional) | String | — | The phone number receiving the call. | +0987654321 |
| redirect_duration (Optional) | int (seconds) | — | Duration for which the call was redirected before final status. | 42 |
| timestamp | float | — | Unix timestamp indicating when the event was recorded. | 1633035802.123 |
| call_id | String(uuid4) | — | Unique identifier for the call. | d8016985-e492-... |
B. event_call_answer_type_updated
Description
Emitted when the system (e.g. via Twilio’s Answering Machine Detection) identifies what answered an outbound call (human, machine, voicemail, etc.). Used to drive call-handling logic and analytics.
Attributes
| Attribute | Type | Values | Description | Example |
|---|---|---|---|---|
| call_type | String | phone_call | Specifies this is a phone call (particularly for outbound AMD). | phone_call |
| direction | String | inbound, outbound | Typically outbound for AMD, but included for consistency. | outbound |
| answer_type | String | human, machine, voicemail | The identified entity that answered the call. | human |
| timestamp | float | — | Unix timestamp indicating when the event was recorded. | 1633035802.123 |
| call_id | String(uuid4) | — | Unique identifier for the call. | d8016985-e492-4710-b288-97229... |
C. event_transcript
Description
Captures real-time transcripts of spoken audio or messages during an active call or session. It can fire multiple times as the conversation progresses, allowing continuous tracking of the dialogue.
Attributes
| Attribute | Type | Values | Description | Example |
|---|---|---|---|---|
| text | String | — | The recognized speech or chat text. | "Hello, how can I assist you?" |
| timestamp | float | — | Unix timestamp indicating when the transcript was recorded. | 1633035802.123 |
| sender | String | human, agent | Indicates who sent the message (human or agent). | human |
| call_id | String(uuid4) | — | Unique identifier for the call. | d8016985-e492-... |
D. event_tool
Description
Emitted whenever a tool is called within a session. This includes actions like API calls, database queries, or any action performed by an integrated tool during the call/session.
Attributes
| Attribute | Type | Description | Example |
|---|---|---|---|
| name | String | The name of the tool or action invoked. | "check_order_status" |
| type | String | The category of the tool (e.g., api_call, database_query, etc.). | "custom_tool" |
| arguments (Optional) | dict | Arguments or parameters provided to the tool. | {"order_id": "67890"} |
| response (Optional) | dict | If the tool/action returned data, it may appear here. | {"status": "Order in transit"} |
| timestamp | float | Unix timestamp indicating when the tool was called. | 1633035802.123 |
| call_id | String(uuid4) | Unique identifier for the call associated with this tool event. | d8016985-e492-4710-b288-97229... |
E. event_task_transition
Description
Fired whenever the system transitions from one “task” (or conversational state) to another, including references to the models used and how long the previous task lasted.
Attributes
| Attribute | Type | Description | Example |
|---|---|---|---|
| source_task_name | String | The name of the current/previous task. | "initial_greeting" |
| target_task_name (Optional) | String | The name of the next task the system is transitioning to. | "collecting_information" |
| source_task_model | ModelType | The model used for the source task. | "model123" |
| target_task_model (Optional) | ModelType | The model used for the target task, if applicable. | "model456" |
| source_task_duration (Optional) | int (seconds) | How long the source task lasted before transitioning. | 30 |
| timestamp | float | Unix timestamp indicating when the transition occurred. | 1633035802.123 |
| call_id | String(uuid4) | Unique identifier for the call. | d8016985-e492-... |
F. event_variable_value_updated
Description
Emitted whenever a variable’s value is updated during a call/session. This enables tracking changes in real-time to important metrics or states.
Attributes
| Attribute | Type | Description | Example |
|---|---|---|---|
| variable_name | String | The name of the variable being updated. | "customer_status" |
| value | String | The new value of the variable. | "VIP" |
| timestamp | float | Unix timestamp indicating when the variable was updated. | 1633035802.123 |
| call_id | String(uuid4) | Unique identifier for the call. | d8016985-e492-4710-b288-97229... |
G. event_all_variables_resolved
Description
Indicates that all call/session variables (e.g., extracted data) have been finalized or saved. Typically fired when the system finishes collecting or confirming needed information.
Attributes
| Attribute | Type | Description | Example |
|---|---|---|---|
| variable_values | dict | A dictionary containing the resolved variables relevant to the call or session. | {"customer_id": "12345"} |
| timestamp | float | Unix timestamp indicating when the event was recorded. | 1633035802.123 |
| call_id | String(uuid4) | Unique identifier for the call. | d8016985-e492-4710-b288-97229... |
Additional Notes
- Optional Fields: If a field is not relevant or was not captured in a particular scenario (e.g.,
redirect_durationwhen no redirect occurred), it may be omitted from the payload.
Getting Started with Webhooks
-
Set up your webhook endpoint in your agent’s dashboard.
-
Receive and parse events from our platform using the details above.
-
Respond with a 2xx status code to confirm receipt.
If you have any questions or need help integrating these events into your workflow, feel free to reach out to our support team for additional guidance.