Notification event types
Updated
Conversational AI Engine webhook notification event types.
After enabling Agora message notifications, the Agora notification server sends channel event notifications to your server through HTTPS POST requests. The data format is JSON, the character encoding is UTF-8, and the signature algorithm can be either HMAC/SHA1 or HMAC/SHA256.
This page explains the types of events returned in channel event callbacks and their meanings.
If you are starting from a product goal instead of an event number, begin with Monitor agent status, errors, and performance.
For webhook setup, request format, and signature verification, see Webhooks.
Choose event types by goal
| Goal | Use these event types | What they help you answer |
|---|---|---|
| Confirm that a session started or ended | 101 agent joined, 102 agent left | Did the agent enter the channel? How did the session end? |
| Retrieve conversation history after a session | 103 agent history | What was said during the session? See Retrieve conversation history after a session ends. |
| Investigate failures and alert on production issues | 110 agent error, 102 agent left | Which module failed? Did the session terminate because of that failure? See Debug agent failures with runtime events. |
| Measure latency and runtime health | 111 agent metrics | How long do LLM and TTS stages take? Are there regressions? |
| Track telephony call progress | 201 inbound call state, 202 outbound call state | Where is the SIP call in its lifecycle? |
Request header
The message notification callback header contains the following fields:
| Parameter | Description |
|---|---|
Content-Typestring | Application/json |
Agora-Signaturestring | The signature value generated by Agora using the customer key and |
Agora-Signature-V2string | The signature value generated by Agora using the customer key and |
Request body
The message notification callback request body contains the following fields:
| Parameter | Description |
|---|---|
noticeIdstring | Notification ID. Identifies an event notification from the Agora server. |
productIdinteger | Business ID. A value of |
eventTypeinteger | The event type of the notification. See Event types for details. |
notifyMsinteger | The Unix timestamp (ms) indicating when the Agora message server sent the event notification to your server. This value is updated when the notification is retried. |
sidstring | The session ID. |
payloadobject | The specific content of the notification event. |
Following is an example of a message notification callback request body:
{
"sid": "C866467GVJJ54687",
"noticeId": "2000001428:4330:107",
"productId": 17,
"eventType": 101,
"notifyMs": 1611566412672,
"payload": {}
}Event types
The Agora message notification service notifies the following Conversational AI Engine events:
| Event Type | Event name | Event description |
|---|---|---|
| 101 | agent joined | The agent joins the channel. |
| 102 | agent left | The agent leaves the channel. |
| 103 | agent history | After an agent stops, this event notifies the stored history, which includes messages exchanged between the user and the agent and timestamps indicating when the agent was created and stopped. The maximum number of entries is determined by the llm.max_history parameter you can set when starting the agent. The default value is 32. |
| 104 | agent expire | The agent's RTC token is about to expire. |
| 110 | agent error | Agent error. |
| 111 | agent metrics | The performance metrics of an agent. |
| 112 | turns finished | Batch callback of dialogue round data after the session ends. |
| 201 | inbound call state | Changes in the status of an incoming call. |
| 202 | outbound call state | Changes in the status of an outgoing call. |
101 agent joined
An eventType of 101 indicates that an agent has joined a channel. The payload contains the following fields:
| Parameter | Description |
|---|---|
agent_idstring | Unique identifier of the agent. |
namestring | The agent name provided when calling Start a conversational AI agent. Unique within a channel. |
start_tsinteger | Timestamp indicating when the agent was created. |
channelstring | The name of the channel the agent was in. |
labelsobject | Custom labels in key-value pair format. Contains the same labels that were set when starting the agent. |
Payload example
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"name": "my-agent",
"start_ts": 1737111452,
"channel": "xxxxx",
"labels": {
"campaign_id": "test_campaign",
"customer_group": "vip"
}
}102 agent left
An eventType of 102 indicates that an agent has left a channel. The payload contains the following fields:
| Parameter | Description |
|---|---|
agent_idstring | Unique identifier of the agent. |
namestring | The agent name provided when calling Start a conversational AI agent. Unique within a channel. |
start_tsinteger | Timestamp indicating when the agent was created. |
stop_tsinteger | Timestamp indicating when the agent left the channel. |
channelstring | The name of the channel the agent was in. |
statusstring | Agent status. |
messagestring | The reason why the agent left the channel. |
labelsobject | Custom labels in key-value pair format. Contains the same labels that were set when starting the agent. |
Payload examples
Following are some examples of the payload when an agent leaves a channel for different reasons.
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"name": "my-agent",
"start_ts": 1737111452,
"stop_ts": 1737111455,
"channel": "xxxxx",
"status": "STOPPED",
"message": "OK",
"labels": {
"campaign_id": "test_campaign",
"customer_group": "vip"
}
}{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"name": "my-agent",
"start_ts": 1737111452,
"stop_ts": 1737111455,
"channel": "xxxxx",
"status": "STOPPED",
"message": "Idle for too long",
"labels": {
"campaign_id": "test_campaign",
"customer_group": "vip"
}
}{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"name": "my-agent",
"start_ts": 1737111452,
"stop_ts": 1737111455,
"channel": "xxxxx",
"status": "FAILED",
"message": "Connecting for too long",
"labels": {
"campaign_id": "test_campaign",
"customer_group": "vip"
}
}{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"name": "my-agent",
"start_ts": 1737111452,
"stop_ts": 1737111455,
"channel": "xxxxx",
"status": "FAILED",
"message": "RTC connection error",
"labels": {
"campaign_id": "test_campaign",
"customer_group": "vip"
}
}{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"name": "my-agent",
"start_ts": 1737111452,
"stop_ts": 1737111455,
"channel": "xxxxx",
"status": "STOPPED",
"message": "Task lifetime limit exceeded",
"labels": {
"campaign_id": "test_campaign",
"customer_group": "vip"
}
}103 agent history
An eventType of 103 notifies the history of a user and agent dialogue. The notification payload contains the following fields:
| Parameter | Description |
|---|---|
agent_idstring | Unique identifier of the agent. |
namestring | The agent name provided when calling Start a conversational AI agent. Unique within a channel. |
channelstring | The name of the channel the agent was in. |
start_tsinteger | The timestamp indicating when the agent started and joined the channel. |
stop_tsinteger | The timestamp indicating when the agent stopped and left the channel. |
contentsarray | Agent history.
|
labelsobject | Custom labels in key-value pair format. Contains the same labels that were set when starting the agent. |
speech_start_ms, speech_end_ms, and speech_algorithmic_delay are returned only in 103 agent history events for sessions that use llm.vendor set to custom.
Payload examples
{
"agent_id": "xxxx",
"name": "my-agent",
"channel": "xxxx",
"start_ts": 123,
"stop_ts": 123,
"contents": [
{
"role": "user",
"content": "hello."
},
{
"role": "assistant",
"content": "hi, how can I help you?"
}
],
"labels": {
"campaign_id": "test_campaign",
"customer_group": "vip"
}
}{
"agent_id": "xxxx",
"name": "my-agent",
"channel": "xxxx",
"start_ts": 123,
"stop_ts": 123,
"contents": [
{
"role": "user",
"content": "Hello, I need help with my recent order.",
"speech_start_ms": 1715000001200,
"speech_end_ms": 1715000003400,
"speech_algorithmic_delay": 120
},
{
"role": "assistant",
"content": "Sure, could you please provide your order number?",
"speech_start_ms": 1715000004100,
"speech_end_ms": 1715000005000
},
{
"role": "user",
"content": "I'd like to check the status of my package, tracking number 12345.",
"speech_start_ms": 1715000005200,
"speech_end_ms": 1715000007600,
"speech_algorithmic_delay": 120
},
{
"role": "assistant",
"content": "Your package with tracking number 12345 is currently out for delivery.",
"speech_start_ms": 1715000009500,
"speech_end_ms": 1715000013200
},
{
"role": "user",
"content": "[think API injected] User level: VIP"
}
],
"labels": {
"campaign_id": "test_campaign",
"customer_group": "vip"
}
}104 agent expire
An eventType of 104 indicates that the agent's RTC token is about to expire. The payload contains the following fields:
| Parameter | Description |
|---|---|
agent_idstring | Unique identifier of the agent. |
namestring | The agent name provided when calling Start a conversational AI agent. Unique within a channel. |
start_tsinteger | Timestamp indicating when the agent was created. |
channelstring | The name of the channel the agent is in. |
messagestring | Token expiry warning message. Fixed value: |
Info
This event is a warning only. The agent does not exit the channel or interrupt the session when this event is triggered. Upon receiving this event, call the Update agent API with a new properties.token to refresh the token before it expires.
Payload example
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"name": "my-agent",
"start_ts": 1737111452,
"channel": "xxxxx",
"message": "Task exceeded maximum lifetime"
}110 agent error
An eventType of 110 indicates that an agent has encountered an error. The payload contains the following fields:
| Parameter | Description |
|---|---|
agent_idstring | Unique identifier of the agent. |
namestring | The agent name provided when calling Start a conversational AI agent. Unique within a channel. |
start_tsinteger | Timestamp indicating when the agent was created. |
channelstring | The name of the channel the agent was in. |
turn_idstring | Transcript conversation turn. For details, see Display live transcripts. |
errorsarray | An array of error messages. Each object contains the following fields:
|
labelsobject | Custom labels in key-value pair format. Contains the same labels that were set when starting the agent. |
Payload examples
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"name": "my-agent",
"start_ts": 1737111452,
"channel": "xxxxx",
"turn_id": 2,
"errors": [{"module": "llm", "turn_id":2, "code":503, "message": "Insufficient balance."}],
"labels": {
"campaign_id": "test_campaign",
"customer_group": "vip"
}
}When the greeting audio file fails to download, times out, is in an unsupported format, or fails to decode, the system reports the error via a 110 agent error event and automatically falls back to TTS synthesis using greeting_message. In these errors, errors[].module is agent.
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"name": "outbound_voice_agent",
"start_ts": 1737111452,
"channel": "outbound_call_channel_001",
"turn_id": 0,
"errors": [
{
"module": "agent",
"turn_id": 0,
"code": 4001,
"message": "Greeting audio URL unreachable, fallback to TTS. audio_url: https://cdn.example.com/audio/welcome.mp3"
}
],
"labels": {}
}Info
If parameters.enable_error_message is set to true when starting the agent, greeting audio URL errors are also delivered to the client via the onMessageError RTM callback, in addition to the server-side webhook event.
111 agent metrics
An eventType of 111 notifies the performance metrics of an agent. The payload contains the following fields:
| Parameter | Description |
|---|---|
agent_idstring | Unique identifier of the agent. |
namestring | The agent name provided when calling Start a conversational AI agent. Unique within a channel. |
start_tsinteger | Timestamp indicating when the agent was created and joined the channel. |
stop_tsinteger | Timestamp indicating when the agent stopped and left the channel. |
channelstring | The name of the channel where the agent is located. |
metricsarray | An array of performance metrics. Each object contains the following fields:
|
labelsobject | Custom labels in key-value pair format. Contains the same labels that were set when starting the agent. |
Payload example
{
"agent_id": "A42AC47Hxxxxxxxx4PK27ND25E",
"name": "my-agent",
"start_ts": 1000,
"stop_ts": 1672531200,
"channel": "test-channel",
"metrics": [
{
"turn_id": 1,
"asr_ttlw": 503,
"llm_ttfb": 1104,
"tts_ttfb": 85
},
{
"turn_id": 2,
"asr_ttlw": 2385,
"llm_ttfb": 980,
"tts_ttfb": 78
}
],
"labels": {
"campaign_id": "test_campaign",
"customer_group": "vip"
}
}112 turns finished
An eventType of 112 indicates a batch callback of conversation turn data after the session ends. This event returns the conversation turns for the current session in a single callback, making it convenient for post-session analysis, archiving, or offline processing.
When a session has more than 200 turns, the callback data may be truncated. Use the is_truncated field to check whether the current callback contains the complete turn data.
The payload contains the following fields:
| Parameter | Description |
|---|---|
agent_idstring | Unique identifier of the agent. |
namestring | The agent name provided when calling Start a conversational AI agent. Unique within a channel. |
channelstring | The name of the channel where the agent is located. |
start_tsnumber | Timestamp indicating when the agent was created and joined the channel. |
stop_tsnumber | Timestamp indicating when the agent stopped and left the channel. |
total_turn_countnumber | The total number of conversation turns in the session. |
is_truncatedboolean | Whether the turn data in the current callback is truncated. A value of |
labelsobject | Custom labels in key-value pair format. Contains the same labels that were set when starting the agent. Only returned if labels were passed in when creating the agent. |
turnsarray[object] | A list of conversation turns for the session.
|
Payload example
{
"agent_id": "xxxx",
"name": "support_agent_001",
"channel": "xxxx",
"start_ts": 1715000000000,
"stop_ts": 1715000015000,
"total_turn_count": 250,
"is_truncated": true,
"labels": {
"campaign_id": "test_campaign",
"customer_group": "vip"
},
"turns": [
{
"agent_id": "xxxx",
"channel": "xxxx",
"turn_id": 1,
"start": {
"start_at": 1774579820147,
"type": "voice_input"
},
"end": {
"end_at": 1774579822412,
"type": "ok"
},
"metrics": {
"e2e_latency_ms": 1500,
"segmented_latency_ms": {
"algorithm_processing": 300,
"asr_ttlw": 200,
"llm_ttft": 600,
"tts_ttfb": 200,
"transport": 300
}
}
}
]
}The following example shows the end object of an interrupted turn:
{
"end_at": 1774579822412,
"type": "interrupted",
"metadata": {
"caused_by": "api_interrupt",
"playback_duration_ms": 1200,
"intended_playback_duration_ms": 2400
}
}201 inbound call state
An eventType of 201 notifies changes in the status of an incoming call. The payload contains the following fields:
| Parameter | Description |
|---|---|
agent_idstring | Unique identifier of the agent. |
namestring | The agent name provided when calling Start a conversational AI agent. Unique within a channel. |
channelstring | The name of the channel where the agent is located. |
statestring |
Incoming call status:
|
report_msinteger | Timestamp (in milliseconds) of the state change. |
labelsobject | Custom labels in key-value pair format. Contains the same labels that were set when starting the agent. |
Payload example
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"name": "my-agent",
"channel": "xxxxx",
"state": "START",
"report_ms": 1737111452000,
"labels": {
"campaign_id": "test_campaign",
"customer_group": "vip"
}
}202 outbound call state
An eventType of 202 notifies changes in the status of an outgoing call. The payload contains the following fields:
| Parameter | Description |
|---|---|
agent_idstring | Unique identifier of the agent. |
namestring | The agent name provided when calling Start a conversational AI agent. Unique within a channel. |
channelstring | The name of the channel where the agent is located. |
statestring |
Outgoing call status:
|
report_msinteger | Timestamp (in milliseconds) of the state change. |
labelsobject | Custom labels in key-value pair format. Contains the same labels that were set when starting the agent. |
Payload example
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"name": "my-agent",
"channel": "xxxxx",
"state": "CALLING",
"report_ms": 1737111452000,
"labels": {
"campaign_id": "test_campaign",
"customer_group": "vip"
}
}