Notification event types

When you enable Agora message notifications, the Agora notification server (NCS) sends event notifications about your Conversational AI Platform sessions to your server in HTTPS POST requests. This page describes the request format and each event type.

To receive notifications, configure a webhook for your project in Agora Console.

Choose event types by goal

The following table helps you find the events for common tasks:

Goal	Use these event types	What they help you answer
Confirm that a session started or ended	`1001` Session state changed	Did the agent start? When and why did the session end?
Get what was said in a session	`1002` Session transcripts	What did the user and the agent say?
Investigate failures	`1003` Session errors, `1001` Session state changed	Which component failed? Did the session end because of it?
Measure latency per turn	`1004` Turns finished	How long did each turn take, and in which component?
Renew the agent's RTC token	`1101` RTC token expiring	Does the agent need a new token?
Track phone call progress	`1201` Telephony state	Was the call answered? How and why did it end?

For phone calls, the session and the call are reported separately. 1001 Session state changed reports the agent's session, which can be running while the call is still ringing. 1201 Telephony state reports the call itself. A call can also end before the session's post-call results are ready. To follow a phone call, handle both events.

Request header

Each notification request contains the following headers:

Header	Description
`Content-Type`	`application/json`
`Agora-Signature-V2`	An HMAC/SHA256 signature over the raw request body. Use this signature when you can.
`Agora-Signature`	An HMAC/SHA1 signature over the raw request body, for compatible integrations.

Verify the signature against the unchanged raw request body before you accept the notification.

Request body

The request body is a UTF-8 JSON object with the following fields:

Field	Type	Required	Description
`noticeId`	String	Yes	The notification ID. It stays the same when NCS retries the same event. Use it to deduplicate notifications.
`productId`	Integer	Yes	The product ID. For the Conversational AI Platform, `23`.
`eventType`	Integer	Yes	The event type. See Event types.
`notifyMs`	Integer	Yes	The time NCS sent the notification, as a Unix timestamp in milliseconds. It can change when NCS retries.
`sid`	String	Yes	The session ID. It's the same as `payload.agent_session_id`.
`payload`	Object	Yes	The event details. Each event type has its own fields.

The envelope fields use camelCase. The payload fields use snake_case, like the Session API. In payload, created_at and ended_at are the session's timestamps in Unix seconds, and occurred_at_ms is when the event happened, in Unix milliseconds.

{
  "noticeId": "notice-1001-example",
  "productId": 23,
  "eventType": 1001,
  "notifyMs": 1789913402100,
  "sid": "b42ac95tp25py49fc37hp94vm67ht52h",
  "payload": {
    "agent_session_id": "b42ac95tp25py49fc37hp94vm67ht52h",
    "status": "failed",
    "occurred_at_ms": 1789913402000,
    "created_at": 1789913400,
    "ended_at": 1789913402,
    "transport": {
      "type": "telephony",
      "direction": "outbound",
      "to_number": "+14155550101"
    }
  }
}

Respond to notifications

After you verify a notification, return HTTP status 200 with a JSON body within 10 seconds. Keep the following in mind:

Notifications can be duplicated or arrive out of order. Neither notifyMs nor occurred_at_ms sets the delivery order. Deduplicate by noticeId.
Acknowledge event types that you don't recognize, after you verify their signature.
If you miss a notification, Retrieve a session returns the session's latest status, not the transition you missed. Phone call state and post-call results can't be recovered this way.

Event types

Event types are grouped by scope: 10xx for sessions, 11xx for RTC, and 12xx for telephony. Session events apply to both transports.

Event type	Event name	Event description
1001	Session state changed	The session status changes, including when the agent joins or leaves an RTC channel and when the session fails to start.
1002	Session transcripts	Transcript processing for the session finished or failed.
1003	Session errors	A component of the agent reported an error. The error doesn't necessarily end the session.
1004	Turns finished	Conversation turn data, including metrics for each turn, after the session ends.
1101	RTC token expiring	The agent's RTC token is about to expire.
1201	Telephony state	The state of an inbound or outbound phone call changes.

1001 Session state changed

The session status changed. This event applies to both transports, and it includes failures before the agent joins an RTC channel or before a call is answered. For RTC sessions, running means the agent joined the channel, and stopped or failed means it left.

payload.status is the status at the transition. A later Retrieve a session request can return a newer status.

Field	Type	Required	Description
`agent_session_id`	String	Yes	The session ID. It's the same as the envelope `sid`.
`agent_name`	String	No	The agent name, when it's known.
`labels`	`Object<string, string>`	No	The labels you passed when you started the session.
`status`	String	Yes	The session status at this transition: `idle`, `starting`, `running`, `stopping`, `stopped`, or `failed`.
`occurred_at_ms`	Integer	Yes	When the transition happened, as a Unix timestamp in milliseconds.
`created_at`	Integer	Yes	When the session was created, as a Unix timestamp in seconds.
`ended_at`	Integer	No	When the session ended, as a Unix timestamp in seconds, if it's known.
`transport`	Object	Yes	The session's transport. For `rtc`, `type` and `channel`. For `telephony`, `type`, `direction`, and the `from_number` and `to_number` when they're known. It never contains RTC tokens or encryption settings.
`message`	String	No	Details about the status, as free-form text, for example `OK`. Don't rely on a fixed set of values.

A session can fail before the phone numbers are resolved. In that case, transport doesn't contain from_number or to_number.

The following examples show payloads for RTC and phone sessions:

{
  "agent_session_id": "a42ac95tp25py49fc37hp94vm67ht52h",
  "agent_name": "support-agent",
  "status": "running",
  "occurred_at_ms": 1789913400000,
  "created_at": 1789913400,
  "transport": {
    "type": "rtc",
    "channel": "support-4821"
  },
  "labels": {
    "customer_group": "vip"
  }
}

{
  "agent_session_id": "a42ac95tp25py49fc37hp94vm67ht52h",
  "agent_name": "support-agent",
  "status": "stopped",
  "occurred_at_ms": 1789913470000,
  "created_at": 1789913400,
  "ended_at": 1789913470,
  "transport": {
    "type": "rtc",
    "channel": "support-4821"
  },
  "message": "OK",
  "labels": {
    "customer_group": "vip"
  }
}

{
  "agent_session_id": "c42ac95tp25py49fc37hp94vm67ht52h",
  "agent_name": "support-agent",
  "status": "running",
  "occurred_at_ms": 1789913401000,
  "created_at": 1789913400,
  "transport": {
    "type": "telephony",
    "direction": "outbound",
    "from_number": "+14155550100",
    "to_number": "+14155550101"
  },
  "labels": {
    "customer_group": "vip"
  }
}

1002 Session transcripts

Transcript processing for the session finished or failed. This event applies to both transports. The transcript records what the user and the agent said. It isn't the LLM's context window.

status is the result of transcript processing, not the session status. A phone call can end before this event arrives.

Field	Type	Required	Description
`agent_session_id`	String	Yes	The session ID. It's the same as the envelope `sid`.
`occurred_at_ms`	Integer	Yes	When the event happened, as a Unix timestamp in milliseconds. It isn't the NCS delivery time in `notifyMs`.
`agent_name`	String	No	The agent name, when it's known.
`labels`	`Object<string, string>`	No	The labels you passed when you started the session.
`created_at`	Integer	Yes	When the session was created, as a Unix timestamp in seconds.
`ended_at`	Integer	Yes	When the session ended, as a Unix timestamp in seconds.
`status`	String	Yes	The result of transcript processing: `completed` or `failed`.
`transcript`	`Array<Object>`	Yes	The spoken segments. Empty when processing failed or no speech was captured.
`transcript[].role`	String	Yes	The speaker: `user` or `assistant`.
`transcript[].content`	String	Yes	The words spoken or played. An interrupted agent segment contains only the part that was played.
`transcript[].turn_id`	Integer	Yes	The ID of the turn the segment belongs to.
`transcript[].speech_started_ms`	Integer	No	When the speech or playback started, as a Unix timestamp in milliseconds.
`transcript[].speech_ended_ms`	Integer	No	When the speech or playback ended, as a Unix timestamp in milliseconds.
`transcript[].metadata`	Object	No	The source of the segment in `source`: `greeting`, `asr`, `llm`, or `command`. An interrupted segment also contains `interrupted`, `interrupted_ms`, and `original`, the full text the agent planned to say.