Active room APIs

Number of APIs: 7

1. Get Active Room Details

GET {{HOST}}/v2/active-rooms/<room_id>

Retrieves the details of a specific active room. 100ms allows you to retrieve details of an active room with their ID.

• You can use this API to check if a room is currently active or not.
• You can also use this in conjunction with retrieve peer API and perform actions such as updating peers, sending messages, and removing peers based on your use case requirements.

---

2. Get Peer Details

GET {{HOST}}/v2/active-rooms/:room_id/peers/:peer_id

Retrieves the details of a specific peer in an active room. You can use the peer_id to retrieve the details of the peer. Use retrieve active room state API to get the list of connected peers in an active room.

Note: You can leverage this API to retrieve the details of connected peers in an active room only. To retrieve details of the peers that left the session already, use the Retrieve a specific session API

Why would you use this API?

• To check if a specific peer has enabled/disabled their audio/video/screen-share at a given time in an active room.
• To check if a specific peer is on-stage and backstage at a particular time.
• You can also use this API to store peer metadata in your database and retrieve it for an abruptly disconnected peer once they join the session again. For example, to enable the user to resume playing the multiplayer game.

---

3. List Peers

GET {{HOST}}/v2/active-rooms/:room_id/peers

---

4. Update Peer

POST {{HOST}}/v2/active-rooms/:room_id/peers/:peer_id

You can use this API to update the details of a connected peer, such as name, role, and metadata (custom/additional information to build real-time interactivity scenarios).

Arguments

Name	Type	Description	Required
room_id — path param	string	Unique identifier of the room where the peer is active. Example: 627cda81ab4f3b56a077dc33	Yes
peer_id — path param	string	Unique identifier of the peer/participant for which you wish to update details. Example: 1038fa72-9345-4651-beab-436f9242ebf4	Yes
name — body param	string	The name of the peer used in the active session.	No
role — body param	string	You can use this to update the role type of the peer. For example, to take the peer to a breakout room.	No
metadata — body param	object	You can use a stringified JSON to update various custom/additional information to a peer such as businessuserid, raisehand/lowerhand info, and more	No

Why would you use this API?

• You can use these APIs to update various properties of the connected peer, such as avatar, BRB status, hand-raise status, etc.
• Custom Avatar:
  • A user updates their profile information on your app/ongoing session; the data is stored in your data store.
  • Use Update peer API and pass the profile picture data from your data store to your client app to display it as the respective connected peer's avatar (based on user_id mapping).

---

5. Send Message

POST {{HOST}}/v2/active-rooms/<room_id>/send-message

You can use this API to send messages to a single peer, a set of peers (a particular role), or all connected peers in the active room. This API supports arguments such as peer_id and role to implement this.

1. If peer_id is specified -- message will be sent only to the specified connected peer.
2. If the role is specified -- message will be sent to all the connected peers assigned with that particular role.
3. If both peer_id and role are specified -- preference will be given to the peer_id and the message will be sent only to the specified connected peer.
4. If both peer_id and role are not specified -- message(broadcast) will be sent to all the connected peers.

Arguments

Name	Type	Description	Required
room_id — path param	string	Unique identifier of the room where the peer is active. Example: 627cda81ab4f3b56a077dc33	Yes
message — body param	string	Actual message to be sent.	Yes
peer_id — path param	string	Unique identifier of the peer/participant for which you wish to send the message. Example: 1038fa72-9345-4651-beab-436f9242ebf4	No
role — body param	string	You can use this to send the message to a set of peers (a particular role).	No
type — body param	string	Indicates the type of message sent, for example, chat or emoji.	No

Why would you use this API?

• Based on your requirements, you can use this API to send a broadcast message, private message, or reactions like emojis.

Example1 - Inform unavailability of teacher

• Suppose a teacher cannot attend a virtual classroom session at the last minute; you can inform all the connected peers (students) by sending a broadcast message to inform the teacher's unavailability.

Example2 - Poker handler

• You can build a handler for a multiplayer game like Poker using this API in conjunction with the peer.join.success webhook event. Let's consider below scenario:
• Four users join the game and start playing -- your app server stores the user_id for each user.
• {
  peer_id: 018b84da-0786-48c5-a3a6-02961d9eac03, // will send the data only to peerid specified.
  message: ", type:customevent"
  }
• {
  message: ", // will send the data to all the peers in the active room as peer_id or role is not specified. type:custom_event"
  }

---

6. Remove Peer

POST {{HOST}}/v2/active-rooms/:room_id/remove-peers

You can use this API to remove/disconnect a connected peer from an active room. 100ms provides options to disconnect a peer either with their peer_id or role.

1. If peer_id is specified -- respective connected peer will be disconnected from the active room.
2. If the role is specified -- all the connected peers assigned with that particular role will be disconnected from the active room.
3. If both peer_id and role are specified -- preference will be given to the peer_id and the respective peer will be disconnected from the active room.
4. If both peer_id and role are not specified -- you must specify peer_id or role for this request.

Arguments

Name	Type	Description	Required
room_id — path param	string	Unique identifier of the room to which the peer is connected. Example: 627cda81ab4f3b56a077dc33	Yes
peer_id — body param	string	Unique identifier of the connected peer/participant you wish to remove from the active room. Example: fd9e87d8-5c7b-4750-932f-d8d2ff18b70b	Conditional
role — body param	string	You can use this to remove a list of connected peers with the specified role type from the active room.	Conditional
reason — body param	string	You can specify the message to be passed to other connected peers in the active room.	No

Note: Conditional Arguments

You should define either of these arguments (peer_id or role) in the payload for the request to be successful.

Why would you use this API?

• Use this API to remove a peer from an active room for misconduct (e.g., abusive chat). This can be combined with custom logic not to generate app tokens for this user to block them from future joins.

---

7. End Active Room

POST {{HOST}}/v2/active-rooms/:room_id/end-room

Trigger this request to end an active room.

Arguments

Name	Type	Description	Required
id — path param	string	Unique identifier of the room you wish to disable. Example: 627cda81ab4f3b56a077dc33	Yes
reason — body param	string	Description to indicate the reason for ending the active room.	No
lock — body param	boolean	Status of the room to be set. Allowed values: true, false. Default: false (ends the current active session only)	No

Warning: If you set the lock argument to true, it will end the active room and users will not be able to join the room later as well. You can use enable a room API or dashboard to enable the room again.

Why would you use this API?

• To disconnect all connected peers at a pre-defined timestamp if you wish to add a hard stop for any sessions.
• Use this to allow peers to join the room only once daily for a respective time slot.
  • Trigger this API at the end of the session with the lock argument as true,
  • The next day, one minute before the schedule - use the enable a room API to enable the room to allow the users to join the session.

---