Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Participants


(warning)

Warning

This page 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, 2024(link takes you to an external page).
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide(link takes you to an external page) 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

participant-instance-resource page anchor

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

Resource URI

resource-uri page anchor

_10
/v1/Rooms/{RoomNameOrSid}/Participants/{ParticipantIdentityOrSid}/

Resource properties
sidtype: SID<PA>Not PII

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


room_sidtype: SID<RM>Not PII

The SID of the participant's room.


account_sidtype: SID<AC>Not PII

The SID of the Account(link takes you to an external page) that created the RoomParticipant resource.


statustype: enum<STRING>Not PII

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

Possible values:
connecteddisconnected

identitytype: stringNot PII

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(link takes you to an external page) and limits(link takes you to an external page) for more info.


date_createdtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was created specified in ISO 8601(link takes you to an external page) format.


date_updatedtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.


start_timetype: string<DATE TIME>Not PII

The time of participant connected to the room in ISO 8601(link takes you to an external page) format.


end_timetype: string<DATE TIME>Not PII

The time when the participant disconnected from the room in ISO 8601(link takes you to an external page) format.


durationtype: integerNot PII

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


urltype: string<URI>Not PII

The absolute URL of the resource.


linkstype: object<URI MAP>Not PII

The URLs of related resources.

HTTP GET

http-get page anchor

Returns a single Participant resource represented by {ParticipantNameOrSid}

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

retrieve-a-connected-participant-from-a-room-by-identity page anchor

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.video.v1.rooms('DailyStandup')
_11
.participants('Alice')
_11
.fetch()
_11
.then(participant => console.log(participant.sid));

Output

_19
{
_19
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"room_sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"date_created": "2015-07-30T20:00:00Z",
_19
"date_updated": "2015-07-30T20:00:00Z",
_19
"start_time": "2015-07-30T20:00:00Z",
_19
"end_time": null,
_19
"sid": "PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"identity": "bob",
_19
"status": "connected",
_19
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"duration": null,
_19
"links": {
_19
"published_tracks": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PublishedTracks",
_19
"subscribed_tracks": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SubscribedTracks",
_19
"subscribe_rules": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SubscribeRules",
_19
"anonymize": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Anonymize"
_19
}
_19
}

Modifies a Participant resource.

URI parameters
RoomSidtype: stringNot PII
Path Parameter

The SID of the room with the participant to update.


Sidtype: stringNot PII
Path Parameter

The SID of the RoomParticipant resource to update.


Request body parameters
Statustype: enum<STRING>Not PII

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

kickremove-participant-from-a-room page anchor

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.video.v1.rooms('DailyStandup')
_11
.participants('Alice')
_11
.update({status: 'disconnected'})
_11
.then(participant => console.log(participant.sid));

Output

_19
{
_19
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"room_sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"date_created": "2017-07-30T20:00:00Z",
_19
"date_updated": "2017-07-30T20:00:00Z",
_19
"start_time": "2017-07-30T20:00:00Z",
_19
"end_time": "2017-07-30T20:00:01Z",
_19
"sid": "PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"identity": "alice",
_19
"status": "disconnected",
_19
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"duration": 1,
_19
"links": {
_19
"published_tracks": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PublishedTracks",
_19
"subscribed_tracks": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SubscribedTracks",
_19
"subscribe_rules": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SubscribeRules",
_19
"anonymize": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Anonymize"
_19
}
_19
}


Participant List Resource

participant-list-resource page anchor

_10
/v1/Rooms/{RoomNameOrSid}/Participants/

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.

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

URI parameters
RoomSidtype: stringNot PII
Path Parameter

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


Statustype: enum<STRING>Not PII
Query Parameter

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

Identitytype: stringNot PII
Query Parameter

Read only the Participants with this User(link takes you to an external page) identity value.


DateCreatedAftertype: string<DATE TIME>Not PII
Query Parameter

Read only Participants that started after this date in ISO 8601(link takes you to an external page) format.


DateCreatedBeforetype: string<DATE TIME>Not PII
Query Parameter

Read only Participants that started before this date in ISO 8601(link takes you to an external page) format.


PageSizetype: integerNot PII
Query Parameter

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


Pagetype: integerNot PII
Query Parameter

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


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

Retrieve connected participants from an in-progress Room instance

retrieve-connected-participants-from-an-in-progress-room-instance page anchor

Retrieve a list of connected Participants

retrieve-a-list-of-connected-participants page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.video.v1.rooms('DailyStandup')
_11
.participants
_11
.list({status: 'connected', limit: 20})
_11
.then(participants => participants.forEach(p => console.log(p.sid)));

Output

_32
{
_32
"participants": [
_32
{
_32
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"room_sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"date_created": "2017-07-30T20:00:00Z",
_32
"date_updated": "2017-07-30T20:00:00Z",
_32
"start_time": "2017-07-30T20:00:00Z",
_32
"end_time": "2017-07-30T20:00:01Z",
_32
"sid": "PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"identity": "alice",
_32
"status": "disconnected",
_32
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"duration": 1,
_32
"links": {
_32
"published_tracks": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PublishedTracks",
_32
"subscribed_tracks": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SubscribedTracks",
_32
"subscribe_rules": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SubscribeRules",
_32
"anonymize": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Anonymize"
_32
}
_32
}
_32
],
_32
"meta": {
_32
"page": 0,
_32
"page_size": 50,
_32
"first_page_url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?Status=disconnected&DateCreatedAfter=2017-01-01T00%3A00%3A01Z&DateCreatedBefore=2017-12-31T23%3A59%3A59Z&Identity=alice&PageSize=50&Page=0",
_32
"previous_page_url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?Status=disconnected&DateCreatedAfter=2017-01-01T00%3A00%3A01Z&DateCreatedBefore=2017-12-31T23%3A59%3A59Z&Identity=alice&PageSize=50&Page=0",
_32
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?Status=disconnected&DateCreatedAfter=2017-01-01T00%3A00%3A01Z&DateCreatedBefore=2017-12-31T23%3A59%3A59Z&Identity=alice&PageSize=50&Page=0",
_32
"next_page_url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?Status=disconnected&DateCreatedAfter=2017-01-01T00%3A00%3A01Z&DateCreatedBefore=2017-12-31T23%3A59%3A59Z&Identity=alice&PageSize=50&Page=1",
_32
"key": "participants"
_32
}
_32
}

Retrieve disconnected Participants from a Room instance

retrieve-disconnected-participants-from-a-room-instance page anchor

Retrieve a list of disconnected Participants

retrieve-a-list-of-disconnected-participants page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.video.v1.rooms('DailyStandup')
_11
.participants
_11
.list({status: 'disconnected', limit: 20})
_11
.then(participants => participants.forEach(p => console.log(p.sid)));

Output

_32
{
_32
"participants": [
_32
{
_32
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"room_sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"date_created": "2017-07-30T20:00:00Z",
_32
"date_updated": "2017-07-30T20:00:00Z",
_32
"start_time": "2017-07-30T20:00:00Z",
_32
"end_time": "2017-07-30T20:00:01Z",
_32
"sid": "PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"identity": "alice",
_32
"status": "disconnected",
_32
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"duration": 1,
_32
"links": {
_32
"published_tracks": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PublishedTracks",
_32
"subscribed_tracks": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SubscribedTracks",
_32
"subscribe_rules": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SubscribeRules",
_32
"anonymize": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Anonymize"
_32
}
_32
}
_32
],
_32
"meta": {
_32
"page": 0,
_32
"page_size": 50,
_32
"first_page_url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?Status=disconnected&DateCreatedAfter=2017-01-01T00%3A00%3A01Z&DateCreatedBefore=2017-12-31T23%3A59%3A59Z&Identity=alice&PageSize=50&Page=0",
_32
"previous_page_url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?Status=disconnected&DateCreatedAfter=2017-01-01T00%3A00%3A01Z&DateCreatedBefore=2017-12-31T23%3A59%3A59Z&Identity=alice&PageSize=50&Page=0",
_32
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?Status=disconnected&DateCreatedAfter=2017-01-01T00%3A00%3A01Z&DateCreatedBefore=2017-12-31T23%3A59%3A59Z&Identity=alice&PageSize=50&Page=0",
_32
"next_page_url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?Status=disconnected&DateCreatedAfter=2017-01-01T00%3A00%3A01Z&DateCreatedBefore=2017-12-31T23%3A59%3A59Z&Identity=alice&PageSize=50&Page=1",
_32
"key": "participants"
_32
}
_32
}


Rate this page: