Skip to content Skip to navigation Skip to topbar

Twilio Docs

Programmable Video Overview

Getting Started

JavaScript SDK Android SDK iOS SDK Tutorials and More Getting Started Resources

Technical Concepts

Basic Concepts Understanding Video Rooms Understanding Video Rooms APIs Understanding Video Recordings and Compositions

Platform SDKs

Platform SDK Support Policy

JavaScript

Overview API Reference Changelog JavaScript App Best Practices Specify Audio and Video Constraints in JavaScript Migrating from 1.x to 2.x Older Releases

Android

Overview API Reference KTX API Reference Changelog Migrating from 6.x to 7.x Older Releases

iOS

Overview API Reference iOS App Best Practices Changelog Migrating from 4.x to 5.x Older Releases

REST API Reference

Rooms

Overview Participants Recording Rules PublishedTrack Track Subscriptions

Recordings

Overview Encrypted Recordings External S3 Recordings Recording Rules

Compositions

Overview Encrypted Compositions External S3 Compositions Composition Hooks

Status Callbacks

Developer Guides

Enhancing Quality

Developing High Quality Video Applications Working with VP8 Simulcast Using the Track Priority API Using the Network Bandwidth Profile API Video Regions and Global Low Latency Using the Network Quality API Noise Cancellation

Reconnection States and Events Encrypting your Stored Media Storing into AWS S3 Managing Codecs Add Programmable Voice Participants to Video Rooms Guide to Scaling Applications Programmable Video Quotas and Limits Configure Maximum Participant Duration Programmable Video Processors

Advanced iOS SDK Topics

Video Source APIs Configuring Audio, Video Input and Output devices

Advanced Android SDK Topics

Configuring Audio, Video Input and Output devices

Insights, Troubleshooting, and Diagnostics

Video Insights Video Log Analyzer API Pre-call Testing and Diagnostics Preflight API JavaScript Room Monitor JavaScript Logger

Networking and Security

User Identity & Access Tokens for Programmable Video Video IP Addresses Networking for Video Applications Media Security

Tutorials

Manually mixing Track Recording files Detecting the Dominant Speaker DataTrack API Usage Guides Screen Capture

Solutions Library

Telemedicine Virtual Visits

Messaging
Voice
Serverless
Flex
Studio
All docs...

SDKs
Help

Log in
Sign up

Rate this page:

12345

On this page

Participant Instance Resource

Resource URI
Resource Properties
Path parameters
Request body parameters
Participant List Resource
Resource URI
Path parameters
Query parameters

Participant Instance Resource

Resource Properties

Path parameters

Request body parameters

Participant List Resource

Path parameters

Query parameters

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


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

Resource Properties

Property nameTypePIIDescription

sidSID<PA>

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>

The SID of the participant's room.

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

account_sidSID<AC>

The SID of the Account that created the RoomParticipant resource.

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

statusenum<string>

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

Possible values:

connecteddisconnected

identitystring

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>

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

date_updatedstring<date-time>

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

start_timestring<date-time>

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

end_timestring<date-time>

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

durationinteger

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

urlstring<uri>

The absolute URL of the resource.

linksobject<uri-map>

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

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_19// Download the helper library from https://www.twilio.com/docs/node/install
_19const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19// Find your Account SID and Auth Token at twilio.com/console
_19// and set the environment variables. See http://twil.io/secure
_19const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19const authToken = process.env.TWILIO_AUTH_TOKEN;
_19const client = twilio(accountSid, authToken);
_19
_19async function fetchRoomParticipant() {
_19  const participant = await client.video.v1
_19    .rooms("DailyStandup")
_19    .participants("Alice")
_19    .fetch();
_19
_19  console.log(participant.sid);
_19}
_19
_19fetchRoomParticipant();

Output


_19{
_19  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "room_sid": "DailyStandup",
_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": "Alice",
_19  "identity": "bob",
_19  "status": "connected",
_19  "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "duration": null,
_19  "links": {
_19    "published_tracks": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PublishedTracks",
_19    "subscribed_tracks": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SubscribedTracks",
_19    "subscribe_rules": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SubscribeRules",
_19    "anonymize": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Anonymize"
_19  }
_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

Property nameTypeRequiredPIIDescription

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

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_19// Download the helper library from https://www.twilio.com/docs/node/install
_19const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19// Find your Account SID and Auth Token at twilio.com/console
_19// and set the environment variables. See http://twil.io/secure
_19const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19const authToken = process.env.TWILIO_AUTH_TOKEN;
_19const client = twilio(accountSid, authToken);
_19
_19async function updateRoomParticipant() {
_19  const participant = await client.video.v1
_19    .rooms("DailyStandup")
_19    .participants("Alice")
_19    .update({ status: "disconnected" });
_19
_19  console.log(participant.sid);
_19}
_19
_19updateRoomParticipant();

Output


_19{
_19  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "room_sid": "DailyStandup",
_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": "Alice",
_19  "identity": "alice",
_19  "status": "disconnected",
_19  "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "duration": 1,
_19  "links": {
_19    "published_tracks": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PublishedTracks",
_19    "subscribed_tracks": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SubscribedTracks",
_19    "subscribe_rules": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SubscribeRules",
_19    "anonymize": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Anonymize"
_19  }
_19}

Participant List Resource

Resource URI


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

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

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


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

Output


_12{
_12  "participants": [],
_12  "meta": {
_12    "page": 0,
_12    "page_size": 50,
_12    "first_page_url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants?PageSize=50&Page=0",
_12    "previous_page_url": null,
_12    "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants?PageSize=50&Page=0",
_12    "next_page_url": null,
_12    "key": "participants"
_12  }
_12}

Retrieve `disconnected` Participants from a Room instance

Retrieve a list of disconnected Participants

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


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

Output


_12{
_12  "participants": [],
_12  "meta": {
_12    "page": 0,
_12    "page_size": 50,
_12    "first_page_url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants?PageSize=50&Page=0",
_12    "previous_page_url": null,
_12    "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants?PageSize=50&Page=0",
_12    "next_page_url": null,
_12    "key": "participants"
_12  }
_12}

Rate this page:

12345

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Terms of service

Copyright © 2024 Twilio Inc.