Chatroom Status Update Callback

"Chatroom Status Update Callback" is a server-side callback service provided by the RTC product, offering the following capabilities:

• Notifies your application server of RTC room status changes at specified intervals.
• Alerts your application server when events are triggered by call participants, meeting members, or hosts in live streaming rooms. For specific events, refer to the event field (room event types) below.

Note

Operations performed by audience members in live streaming mode rooms will not trigger event callbacks.

Enabling the Service

Navigate to the RTC page to configure the Chatroom Status Update Callback address. Ensure the callback URL is publicly accessible. Follow these steps:

1. Verify that the current App Key has RTC service enabled. If you manage multiple apps, select the correct app name first. Each app provides two independent sets of App Key / Secret for isolating development and production environments. Ensure you select the appropriate environment (development/production).

   tip

   If your app hasn't been submitted for RC review, only the development environment is available.

2. On the RTC page, enter the Chatroom Status Update Callback address:

   • Example callback URL: http(s)://your.app.server/any-url-path
   • If version selection is required, choose 1.1 (version 1.0 is no longer maintained).
   • Changes take effect within 15 minutes.

Once configured, all RTC room status changes in your app will trigger real-time HTTP callbacks to your server, including room creation/destruction, user joins/exits (excluding audience roles), and audio/video resource publishing.

Callback Method

POST: <your-receiving-server-url>

Data format: application/json

The callback URL <your-receiving-server-url> is the configured endpoint for your App Key. Ensure it's accessible. If your network has IP restrictions, configure the IP allowlist to receive callbacks properly.

Each request includes a signature for verification. See Server Callback for signature rules.

Callback Body Parameters

The HTTP request body is in application/json format with the following structure:

Parameter	Type	Description
appKey	String	Current App Key in use.
roomId	String	RTC room ID provided during client SDK join/create.
sessionId	String	Unique room identifier generated by the RTC server.
userId	String	User ID associated with the event.
event	Number	Event type, dependent on room mode. See room event types.
exitType	Number	When event is 12, indicates the reason for user exit: 1: Voluntary leave 2: Kicked 3: Network timeout (kicked after 1 minute of no heartbeat) 4: Multi-device login conflict Defaults to 0 for other events.
timestamp	Number	Event timestamp in milliseconds since 1970-01-01.
extra	Object	Custom room attributes set by the business logic.
data	Object	Internal room attributes set by the SDK.
audience	Array	Only included when event is 1. Lists the first 500 audience members by join time.
durationTime	Number	For event 12: Cumulative duration (ms) of a user's single room session. For event 3: Total room duration (ms).
members	Array	User resource details: - For event 1: Full list of all user resources. - For other events: Only incremental changes (e.g., user1's resources if user1 published).
members[i].userId	String	User ID.
members[i].joinTime	Number	Join timestamp in milliseconds since 1970-01-01.
members[i].data	Object	Published resource details.
members[i].data.role	String	Caller/callee role in 1:1 calls (using CallLib/CallPlus/CallKit SDKs). RC_CallInvter: Caller. RC_CallInvitee: Callee.
members[i].data.uris	Array	Resource list details below.
members[i].data.uris[i].mediaType	Number	Resource type: 0 (audio), 1 (video).
members[i].data.uris[i].msid	String	Stream ID.
members[i].data.uris[i].uri	String	Globally unique resource URI (opaque string).
members[i].data.uris[i].tag	String	Client-specified stream tag (default: RongCloudRTC).
members[i].data.uris[i].state	Number	Resource state: 0 (disabled), 1 (enabled).
members[i].extra	Object	Custom user attributes set by client SDK.

event Field (Room Event Types)

Room event types (event field):

• 1: Periodic full room state sync (default: 120s interval, configurable between 15-600s).
• 2: Room created.
• 3: Room destroyed (auto-destroy or API-triggered). See auto-destroy rules.
• 4: Room attributes updated.
• 5: All members (non-live) or hosts (live) left:
  • Live mode: Triggers when all hosts leave (room persists if audience remains).
  • Meeting/call mode: Triggers when last member leaves (triggers auto-destroy).
• 11: Member joined.
• 12: Member exited (see exitType for reason).
• 13: Member attributes updated.
• 14: PK invitation (live mode only).
• 15: PK invitation canceled (live mode).
• 16: PK invitation accepted (live mode).
• 17: PK invitation declined (live mode).
• 18: PK session ended (live mode).
• 20: Resource/data change (stream publish/cancel, role switch, etc.).
• 22: User offline (no heartbeat for 15s; still in room).
• 23: User resumed online (reconnected before timeout kick).

Callback Request Examples

• Request example for event 1:

  POST /any-url-path HTTP/1.1
  Host: your.app.server
  Content-Type: application/json
  
  {
    "appKey":"appKey",
    "sessionId":"sessionId",
    "roomId":"roomId",
    "userId":"123",
    "event":1,
    "exitType":2,
    "timestamp":1586244141831,
    "extra":{
          "key":"value"
        },
    "data":{
      "key":"value"
    },
    "audience":[
      "1118445"
      ],
    "members":[
        {
          "userId":"123",
          "joinTime":1586244140932,
          "data":{
          "uris":[
          {
            "mediaType":0,
            "msid":"13811223344_h0fc_web_RongCloudRTC",
            "uri":"{\"clusterId\":\"rtc-data-dev-rtc40-15-bdcbj.rongcloud.net\",\"serverId\":\"172.24.151.15:9005\",\"resourceId\":\"13811223344_h0fc_web_RongCloudRTC_0\",\"connectionId\":\"AAY2NjM0NjMAFDEzODExMjIzMzQ0X2gwZmNfd2ViAAM0NDQA\",\"ssrc\":2750434140,\"serviceProvider\":\"awsnx\",\"userTimestamp\":1585043802893}",
            "tag":"RongCloudRTC",
            "state":1
          },
          {
            "mediaType":1,
            "msid":"13811223344_h0fc_web_RongCloudRTC",
            "uri":"{\"clusterId\":\"rtc-data-dev-rtc40-15-bdcbj.rongcloud.net\",\"serverId\":\"172.24.151.15:9005\",\"resourceId\":\"13811223344_h0fc_web_RongCloudRTC_1\",\"connectionId\":\"AAY2NjM0NjMAFDEzODExMjIzMzQ0X2gwZmNfd2ViAAM0NDQA\",\"ssrc\":1782111418,\"serviceProvider\":\"awsnx\",\"userTimestamp\":1585043802893}",
            "tag":"RongCloudRTC",
            "state":1
          }
        ]
      },
      "extra":{
        "key":"v"
        }
      }
    ]
  }

• Request example for event 12:

  POST /any-url-path HTTP/1.1
  Host: your.app.server
  Content-Type: application/json
  
  {
      "appKey":"appKey",
      "roomId":"5d959b9a-25c7-45bd-8a01-64107e2ce76d",
      "sessionId":"zUYTr6J6es9ggF3japy867",
      "userId":"d1830a0970729c2fb73bf4fc7563e220",
      "event":12,
      "exitType":1,
      "timestamp":1645495818536,
      "durationTime":54866
  }

Responding to Callbacks

tip

• RC considers the status synced upon receiving HTTP 200 OK.
• If the response times out (5s), RC retries twice before abandoning the sync.
• Widespread timeouts may pause callbacks for 1 minute before resuming.