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.
Request header
The message notification callback header contains the following fields:
Header
- Content-Type string
Application/json
- Agora-Signature string
The signature value generated by Agora using the customer key and
HMAC/SHA1
algorithm. Use the customer key andHMAC/SHA1
algorithm to verify the signature value. See Verify the signature for details. - Agora-Signature-V2 string
The signature value generated by Agora using the customer key and
HMAC/SHA256
algorithm. Use the customer key andHMAC/SHA256
algorithm to verify the signature value. See Verify the signature for details.
Request body
The message notification callback request body contains the following fields:
BODY
- noticeId string
Notification ID. Identifies an event notification from the Agora server.
- productId integer
Business ID. A value of
17
indicates a Conversational AI Engine notification. - eventType integer
The event type of the notification. See Event types for details.
- notifyMs integer
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.
- sid string
The session ID.
- payload object
The specific content of the notification event.
payload
varies depending on the event type. For details, see Event types.
Following is an example of a message notification callback request body:
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, its stored history is notified which includes the following information:
llm.max_history parameter you can set when starting the agent. The default value is 32 . |
110 | agent error | Agent error. |
101 agent joined
An eventType
of 101
indicates that an agent has joined a channel. The payload
contains the following fields:
payload
- agent_id string
Unique identifier of the agent.
- start_ts integer
Timestamp indicating when the agent was created.
- channel string
The name of the channel the agent was in.
Payload example
102 agent left
An eventType
of 102
indicates that an agent has left a channel. The payload
contains the following fields:
payload
- agent_id string
Unique identifier of the agent.
- start_ts integer
Timestamp indicating when the agent was created.
- stop_ts integer
Timestamp indicating when the agent left the channel.
- channel string
The name of the channel the agent was in.
- status string
Agent status.
- message string
The reason why the agent left the channel.
Payload examples
Following are some examples of the payload
when an agent leaves a channel for different reasons.
- Agent manually stopped
- Agent idle timeout
- Agent error
- RTC connection error
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"start_ts": 1737111452,
"stop_ts": 1737111455,
"channel": "xxxxx",
"status": "STOPPED",
"message": "OK"
}
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"start_ts": 1737111452,
"stop_ts": 1737111455,
"channel": "xxxxx",
"status": "STOPPED",
"message": "Idle for too long"
}
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"start_ts": 1737111452,
"stop_ts": 1737111455,
"channel": "xxxxx",
"status": "FAILED",
"message": "Connecting for too long"
}
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"start_ts": 1737111452,
"stop_ts": 1737111455,
"channel": "xxxxx",
"status": "FAILED",
"message": "RTC connection error"
}
103 agent history
An eventType
of 103
notifies the history of a user and agent dialogue. The notification payload
contains the following fields:
payload
- agent_id string
Unique identifier of the agent.
- channel string
The name of the channel the agent was in.
- start_ts integer
The timestamp indicating when the agent started and joined the channel.
- stop_ts integer
The timestamp indicating when the agent stopped and left the channel.
- contents array
Agent history.
- role string
Possible values:
user
,assistant
The message sender.
user
: Userassistant
: AI agent
- content string
Message content.
Payload example
110 agent error
An eventType
of 110
indicates that an agent has encountered an error. The payload
contains the following fields:
payload
- agent_id string
Unique identifier of the agent.
- start_ts integer
Timestamp indicating when the agent was created.
- channel string
The name of the channel the agent was in.
- turn_id string
Subtitle conversation turn. For details, see Live Subtitle API Reference.
- errors array
An array of error messages. Each object contains the following fields:
- module string
The module where the error occurred.
- turn_id integer
Subtitle dialogue turn.
- code integer
Error code. Refer to the error code document of the vendor corresponding to the error module for detailed information.
- message string
The error message.