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, this event notifies the stored history, 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.
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:

payload

agent_id string

Unique identifier of the agent.

name string

The agent name provided when calling Start a conversational AI agent. Unique within a channel.

start_ts integer

Timestamp indicating when the agent was created.

channel string

The name of the channel the agent was in.

labels objectnullable

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:

payload

agent_id string

Unique identifier of the agent.

name string

The agent name provided when calling Start a conversational AI agent. Unique within a channel.

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.

labels objectnullable

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 manually stopped
Agent idle timeout
Agent error
RTC connection error

{
   "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"
   }    
}

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.

name string

The agent name provided when calling Start a conversational AI agent. Unique within a channel.

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.

labels objectnullable

Custom labels in key-value pair format. Contains the same labels that were set when starting the agent.

Payload example

{
  "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"
  }  
}

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.

name string

The agent name provided when calling Start a conversational AI agent. Unique within a channel.

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.

labels objectnullable

Custom labels in key-value pair format. Contains the same labels that were set when starting the agent.

Payload examples

LLM module error
SIP module error

{
  "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"
  }     
}

{
  "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
  "name": "my-agent",
  "start_ts": 1737111452,
  "channel": "xxxxx",
  "turn_id": "",
  "errors": [{"module": "sip", "turn_id": "", "code":50, "message": "Insufficient balance."}],
  "labels": {
    "campaign_id": "test_campaign",
    "customer_group": "vip"
  }       
}

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.

name string

The agent name provided when calling Start a conversational AI agent. Unique within a channel.

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 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 Sentence) 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.

labels objectnullable

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:

payload

agent_id string

Unique identifier of the agent.

name string

The agent name provided when calling Start a conversational AI agent. Unique within a channel.

channel string

The name of the channel where the agent is located.

start_ts number

Timestamp indicating when the agent was created and joined the channel.

stop_ts number

Timestamp indicating when the agent stopped and left the channel.

total_turn_count number

The total number of conversation turns in the session.

is_truncated boolean

Whether the turn data in the current callback is truncated. A value of true indicates that the current callback did not return all turns.

labels objectnullable

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.

turns array[object]

A list of conversation turns for the session.

Show propertiesHide properties

agent_id string

Unique identifier of the agent.

channel string

The name of the channel where the agent is located.

turn_id number

The sequential index of the turn within the session. Starts at 1.

start object

Details about the start of the turn.

Show propertiesHide properties

start_at number

The Unix timestamp in milliseconds (UTC time) when the turn started.

type string

Possible values: voice_input, greeting, silence_timeout, api_speak, api_think

The type of event that initiated the turn.

voice_input: The turn was initiated by user voice input.
greeting: The turn was initiated by an agent greeting.
silence_timeout: The turn was initiated due to a silence timeout.
api_speak: The turn was initiated by a call to the speak API.
api_think: The turn was initiated by a call to the think API.

metadata object

Additional context about the turn start event. Included fields depend on the value of the type field.

Show propertiesHide properties

speech_duration_ms integer

The duration of the user's voice input in milliseconds. Included only when type is voice_input.

interrupt_duration_ms integer

The minimum voice duration in milliseconds required to trigger an interruption. Included only when type is voice_input.

end object

Details about the end of the turn.

Show propertiesHide properties

end_at number

The Unix timestamp in milliseconds (UTC time) when the turn ended.

type string

Possible values: ok, error, ignored, interrupted

The type of event that ended the turn.

ok: The turn ended normally.
error: The turn ended due to an error.
ignored: The turn was ignored.
interrupted: The turn was interrupted.

metadata object

Additional context about the turn end event.

metrics object

Latency metrics for the turn.

Show propertiesHide properties

e2e_latency_ms number

The end-to-end latency in milliseconds for the turn. Represents the time from when the user finishes speaking to when the agent starts speaking.

segmented_latency_ms object

A breakdown of latency by segment.

Show propertiesHide properties

algorithm_processing number

Algorithm processing delay in milliseconds.

asr_ttlw number

The ASR Time To Last Word (TTLW) in milliseconds. Represents the delay from when the user finishes speaking to when the ASR module outputs the last word.

llm_ttft number

The LLM Time To First Token (TTFT) in milliseconds. Represents the delay from when the LLM receives the request to when it outputs the first token.

llm_ftfs number

The LLM First Token To First Sentence (FTFS) in milliseconds. Represents the delay from when the LLM outputs the first token to when it outputs the first complete sentence.

tts_ttfb number

The TTS Time To First Byte (TTFB) in milliseconds. Represents the delay from when the TTS module receives a text request to when it outputs the first audio byte.

transport number

Network transmission delay in milliseconds. Not returned when the user is connected using the RTC Web SDK.

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
        }
      }
    }
  ]
}

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.

name string

The agent name provided when calling Start a conversational AI agent. Unique within a channel.

channel string

The name of the channel where the 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.

labels objectnullable

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:

payload

agent_id string

Unique identifier of the agent.

name string

The agent name provided when calling Start a conversational AI agent. Unique within a channel.

channel string

The name of the channel where the 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.

labels objectnullable

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"
  } 
}