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:

Header

Content-Typestring

Application/json

Agora-Signaturestring

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-V2string

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:

noticeIdstring

Notification ID. Identifies an event notification from the Agora server.

productIdinteger

Business ID. A value of 17 indicates a Conversational AI Engine notification.

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. 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 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:

payload

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

optional

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_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

optional

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:

payload

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.

rolestring

The message sender.

user: User
assistant: AI agent

contentstring

Message content.

speech_start_msinteger

optional

Unix timestamp in milliseconds indicating when the user started speaking or the agent started TTS playback. Only returned when llm.vendor is custom.

speech_end_msinteger

optional

Unix timestamp in milliseconds indicating when the user stopped speaking, or when TTS playback completed or was interrupted. Only returned when llm.vendor is custom.

speech_algorithmic_delayinteger

optional

The total delay in milliseconds introduced by audio processing algorithms, including noise reduction, background voice suppression, and voiceprint locking, after audio is captured from the user's microphone. Use this value to align timestamps with cloud recording audio.

Only returned when:

llm.vendor is custom
contents[].role is user
Actual voice input is present

labelsobject

optional

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:

payload

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: Task exceeded maximum lifetime.

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:

payload

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:

modulestring

The module where the error occurred.

turn_idinteger

Transcript dialogue turn.

codeinteger

Error code. Refer to the error code document of the vendor corresponding to the error module for detailed information.

messagestring

The error message.

labelsobject

optional

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:

payload

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:

turn_idstring

Dialogue round ID.

asr_ttlwinteger

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_ttfbinteger

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_ttfsinteger

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_ttfbinteger

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.

labelsobject

optional

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_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 true indicates that the current callback did not return all turns.

labelsobject

optional

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.

agent_idstring

Unique identifier of the agent.

channelstring

The name of the channel where the agent is located.

turn_idnumber

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

startobject

Details about the start of the turn.

start_atnumber

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

typestring

Possible values: voice_input
greeting
silence_timeout
api_speak
api_think

The type of event that initiated the turn.

metadataobject

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

speech_duration_msinteger

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

interrupt_duration_msinteger

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

endobject

Details about the end of the turn.

end_atnumber

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

typestring

Possible values: ok
error
ignored
interrupted

The type of event that ended the turn.

metadataobject

Additional context about the turn end event.

metricsobject

Latency metrics for the turn.

e2e_latency_msnumber

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_msobject

A breakdown of latency by segment.

algorithm_processingnumber

Algorithm processing delay in milliseconds.

asr_ttlwnumber

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_ttftnumber

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_ftfsnumber

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_ttfbnumber

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.

transportnumber

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_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

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_msinteger

Timestamp (in milliseconds) of the state change.

labelsobject

optional

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_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

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_msinteger

Timestamp (in milliseconds) of the state change.

labelsobject

optional

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

Notification event types

Choose event types by goal

Request header

Request body

Event types

101 agent joined

Payload example

102 agent left

Payload examples

103 agent history

Payload examples

104 agent expire

Payload example

110 agent error

Payload examples

111 agent metrics

Payload example

112 turns finished

Payload example

201 inbound call state

Payload example

202 outbound call state

Payload example

Contact Us

Contact Us