Skip to content Skip to navigation Skip to topbar

On this page

Participants

(warning)

Warning

This documentation is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2026.

We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide to assist you in minimizing any service disruption.

The Participants resource is a subresource of a Rooms instance resource. It represents participants currently connected to a given Room. A Participant instance resource represents an individual Room participant.

The Participant Instance resource lets you kick Participants out of a Room they are connected to. You can query the Participants List resource to get a list of participants currently connected to the Room. You can also get a list of Participants that are disconnected from the Room.

Participant Instance Resource

This resource represents a single Room participant, identified by the ParticipantSid or a ParticipantIdentity.

Resource URI

1/v1/Rooms/{RoomNameOrSid}/Participants/{ParticipantIdentityOrSid}/
2

Resource Properties

Property nameTypeRequiredDescriptionChild properties

sidSID<PA>Optional

The unique string that we created to identify the RoomParticipant resource.

Pattern: ^PA[0-9a-fA-F]{32}$Min length: 34Max length: 34

room_sidSID<RM>Optional

The SID of the participant's room.

Pattern: ^RM[0-9a-fA-F]{32}$Min length: 34Max length: 34

account_sidSID<AC>Optional

The SID of the Account that created the RoomParticipant resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

statusenum<string>Optional

The status of the Participant. Can be: connected or disconnected.

Possible values:

connecteddisconnected

identitystringOptional

The application-defined string that uniquely identifies the resource's User within a Room. If a client joins with an existing Identity, the existing client is disconnected. See access tokens and limits for more info.

date_createdstring<date-time>Optional

The date and time in GMT when the resource was created specified in ISO 8601 format.

date_updatedstring<date-time>Optional

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

start_timestring<date-time>Optional

The time of participant connected to the room in ISO 8601 format.

end_timestring<date-time>Optional

The time when the participant disconnected from the room in ISO 8601 format.

durationintegerOptional

The duration in seconds that the participant was connected. Populated only after the participant is disconnected.

urlstring<uri>Optional

The absolute URL of the resource.

linksobject<uri-map>Optional

The URLs of related resources.

HTTP GET

Returns a single Participant resource represented by {ParticipantNameOrSid}

Naming behavior

GET /Participants/{ParticipantIdentity} implicitly searches only connected Participants for the given ParticipantIdentity and returns either an instance or a 404.

Retrieve a `connected` Participant from a Room by `Identity`

Will return the Participant instance object for the Participant Alice whose Status is connected, from the in-progress Room named DailyStandup.

Retrieve a Participant

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchRoomParticipant() {
11  const participant = await client.video.v1
12    .rooms("DailyStandup")
13    .participants("Alice")
14    .fetch();
15
16  console.log(participant.sid);
17}
18
19fetchRoomParticipant();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "room_sid": "DailyStandup",
4  "date_created": "2015-07-30T20:00:00Z",
5  "date_updated": "2015-07-30T20:00:00Z",
6  "start_time": "2015-07-30T20:00:00Z",
7  "end_time": null,
8  "sid": "Alice",
9  "identity": "bob",
10  "status": "connected",
11  "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12  "duration": null,
13  "links": {
14    "published_tracks": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PublishedTracks",
15    "subscribed_tracks": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SubscribedTracks",
16    "subscribe_rules": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SubscribeRules",
17    "anonymize": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Anonymize"
18  }
19}

HTTP POST

Modifies a Participant resource.

Path parameters

Property nameTypeRequiredPIIDescription

RoomSidstringrequired

The SID of the room with the participant to update.

Sidstringrequired

The SID of the RoomParticipant resource to update.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

Statusenum<string>Optional

The new status of the resource. Can be: connected or disconnected. For in-progress Rooms the default Status is connected, for completed Rooms only disconnected Participants are returned.

Possible values:

connecteddisconnected

Kick/Remove Participant from a Room

Update a Participant's status to disconnected to remove the Participant from a Room.

Remove a Participant

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateRoomParticipant() {
11  const participant = await client.video.v1
12    .rooms("DailyStandup")
13    .participants("Alice")
14    .update({ status: "disconnected" });
15
16  console.log(participant.sid);
17}
18
19updateRoomParticipant();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "room_sid": "DailyStandup",
4  "date_created": "2017-07-30T20:00:00Z",
5  "date_updated": "2017-07-30T20:00:00Z",
6  "start_time": "2017-07-30T20:00:00Z",
7  "end_time": "2017-07-30T20:00:01Z",
8  "sid": "Alice",
9  "identity": "alice",
10  "status": "disconnected",
11  "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12  "duration": 1,
13  "links": {
14    "published_tracks": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PublishedTracks",
15    "subscribed_tracks": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SubscribedTracks",
16    "subscribe_rules": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SubscribeRules",
17    "anonymize": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Anonymize"
18  }
19}

Participant List Resource

Resource URI

1/v1/Rooms/{RoomNameOrSid}/Participants/
2

HTTP GET

Returns a list of Participant resources associated with this Room. The list includes paging information. You can filter the results by providing query string parameters.

List Filters

The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive.

Path parameters

Property nameTypeRequiredPIIDescription

RoomSidstringrequired

The SID of the room with the Participant resources to read.

Query parameters

Property nameTypeRequiredPIIDescription

Statusenum<string>Optional

Read only the participants with this status. Can be: connected or disconnected. For in-progress Rooms the default Status is connected, for completed Rooms only disconnected Participants are returned.

Possible values:

connecteddisconnected

IdentitystringOptional

Read only the Participants with this User identity value.

DateCreatedAfterstring<date-time>Optional

Read only Participants that started after this date in ISO 8601 format.

DateCreatedBeforestring<date-time>Optional

Read only Participants that started before this date in ISO 8601 format.

PageSizeintegerOptional

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

PageintegerOptional

The page index. This value is simply for client state.

Minimum: 0

PageTokenstringOptional

The page token. This is provided by the API.

Retrieve `connected` participants from an `in-progress` Room instance

Retrieve a list of connected Participants

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listRoomParticipant() {
11  const participants = await client.video.v1
12    .rooms("DailyStandup")
13    .participants.list({
14      status: "connected",
15      limit: 20,
16    });
17
18  participants.forEach((p) => console.log(p.sid));
19}
20
21listRoomParticipant();

Output

1{
2  "participants": [],
3  "meta": {
4    "page": 0,
5    "page_size": 50,
6    "first_page_url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants?PageSize=50&Page=0",
7    "previous_page_url": null,
8    "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants?PageSize=50&Page=0",
9    "next_page_url": null,
10    "key": "participants"
11  }
12}

Retrieve `disconnected` Participants from a Room instance

Retrieve a list of disconnected Participants

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listRoomParticipant() {
11  const participants = await client.video.v1
12    .rooms("DailyStandup")
13    .participants.list({
14      status: "disconnected",
15      limit: 20,
16    });
17
18  participants.forEach((p) => console.log(p.sid));
19}
20
21listRoomParticipant();

Output

1{
2  "participants": [],
3  "meta": {
4    "page": 0,
5    "page_size": 50,
6    "first_page_url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants?PageSize=50&Page=0",
7    "previous_page_url": null,
8    "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants?PageSize=50&Page=0",
9    "next_page_url": null,
10    "key": "participants"
11  }
12}