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:

{
  "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, 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`.
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

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

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.
Show propertiesHide properties
- role string
  Possible values: user, assistant
  The message sender.
  
  user: User
  
  assistant: AI agent
- content string
  Message content.

Payload example

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

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
Transcript conversation turn. For details, see Live Transcript API Reference.
errors array
An array of error messages. Each object contains the following fields:
Show propertiesHide properties
- module string
  The module where the error occurred.
- turn_id integer
  Transcript 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

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

111 agent metrics

An eventType of 111 notifies the performance metrics of an agent. 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 and joined the channel.
stop_ts integer
Timestamp indicating when the agent stopped and left the channel.
channel string
The name of the channel where the intelligent agent is located.
metrics array
An array of performance metrics. Each object contains the following fields:
Show propertiesHide properties
- turn_id string
  Dialogue round ID.
- asr_ttlw integer
  The ttlw (Time To Last Word) metric of the ASR module. Represents the delay (in milliseconds) from when the user finishes speaking until the last word is output by the ASR.
- llm_ttfb integer
  The ttfb (Time To First Byte) metric for the LLM module. Represents the latency (in milliseconds) from the start of an LLM request to the receipt of the first byte of the response.
- llm_ttfs integer
  The ttfs (Time To First Sample) metric for the LLM module. Represents the time (in milliseconds) elapsed from the start of an LLM request to the receipt of the first complete sentence response.
- tts_ttfb integer
  The ttfb (Time To First Byte) metric for the TTS module. Represents the latency (in milliseconds) from the start of a TTS request to the receipt of the first byte of the response.

Payload example

{
    "agent_id": "A42AC47Hxxxxxxxx4PK27ND25E",
    "start_ts": 1000,
    "stop_ts": 1672531200,
    "channel": "test-channel",
    "metrics": [
        {
            "turn_id": 1,
            "asr_ttlw": 503,
            "llm_ttfb": 1104
        },
        {
            "turn_id": 2,
            "asr_ttlw": 2385,
            "llm_ttfs": 392
        }
    ]
}

201 inbound call state

An eventType of 201 notifies changes in the status of an incoming call. The payload contains the following fields:

payload

agent_id string
Unique identifier of the agent.
channel string
The name of the channel where the intelligent agent is located.
state string
Possible values: START, ANSWERED, TRANSFERED, HANGUP
Incoming call status:
- START: Call received.
- ANSWERED: Call answered.
- TRANSFERED: Transfer to human operator.
- HANGUP: Call hung up.
report_ms integer
Timestamp (in milliseconds) of the state change.

Payload example

{
    "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
    "channel": "xxxxx",
    "state": "START",
    "report_ms": 1737111452000
}

202 outbound call state

An eventType of 202 notifies changes in the status of an outgoing call. The payload contains the following fields:

payload

agent_id string
Unique identifier of the agent.
channel string
The name of the channel where the intelligent agent is located.
state string
Possible values: START, CALLING, RINGING, ANSWERED, HANGUP
Outgoing call status:
- START: Call begins.
- CALLING: Making a phone call.
- RINGING: The telephone is ringing.
- ANSWERED: The call was connected.
- HANGUP: Call hung up.
report_ms integer
Timestamp (in milliseconds) of the state change.

Payload example

{
    "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
    "channel": "xxxxx",
    "state": "CALLING",
    "report_ms": 1737111452000
}