Skip to main content

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 and HMAC/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 and HMAC/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:


_8
{
_8
"sid": "C866467GVJJ54687",
_8
"noticeId": "2000001428:4330:107",
_8
"productId": 17,
_8
"eventType": 101,
_8
"notifyMs": 1611566412672,
_8
"payload": {...}
_8
}

Event types

The Agora message notification service notifies the following Conversational AI Engine events:

Event TypeEvent nameEvent description
101agent joinedThe agent joins the channel.
102agent leftThe agent leaves the channel.
103agent historyAfter an agent stops, its stored history is notified which includes the following information:
  • Messages exchanged between the user and the agent
  • 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.
110agent errorAgent 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


_5
{
_5
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
_5
"start_ts": 1737111452,
_5
"channel": "xxxxx"
_5
}

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_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"start_ts": 1737111452,
"stop_ts": 1737111455,
"channel": "xxxxx",
"status": "STOPPED",
"message": "OK"
}

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: User
        • assistant: AI agent

      • content string

        Message content.

Payload example


_16
{
_16
"agent_id": "xxxx",
_16
"channel": "xxxx",
_16
"start_ts": 123,
_16
"stop_ts": 123,
_16
"contents": [
_16
{
_16
"role": "user",
_16
"content": "hello."
_16
},
_16
{
_16
"role": "assistant",
_16
"content": "hi, how can I help you?"
_16
}
_16
]
_16
}

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.

Payload example


_7
{
_7
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
_7
"start_ts": 1737111452,
_7
"channel": "xxxxx",
_7
"turn_id": 2,
_7
"errors": [{"module": "llm", "turn_id":2, "code":503, "message": "Insufficient balance."}]
_7
}

vundefined