Calls / Platform API
Home
/
Calls
/
Platform API

Group call

This page explains the key functions of group call consisting of how to create a room and how a user can participate in a group call by entering and exiting a room.

Note: Right now, the Rooms API for group call supports retrieving rooms and participants in rooms. Other actions should be done from Sendbird Calls SDK.

Room

A room can be created with a unique ID which can be shared among users to enter the room for group calls in Sendbird Calls SDK. Using the Rooms API, you can retrieve information regarding a room.


Resource representation

The following table shows the list of properties in a group call resource.

Property nameTypeDescription

room_id

string

A unique identifier for the room.

room_type

string

The type of a room. A type indicates the room type as audio or video and the capacity of a room. Valid values are limited to large_room_for_audio_only which can hold up to 25 participants and small_room_for_video which can hold up to 6 participants.

created_at

string

The timestamp of when the room was created, in Unix milliseconds.

updated_at

string

The timestamp of when the room information was updated, in Unix milliseconds.

state

string

The state of the room. Valid values are limited to open and deleted, however only open is currently supported.

created_by

string

The user who created the room.

current_participants[]

list

The users who are currently in the room.


Create a room

Creates a room for group calls.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.calls.sendbird.com/v1/rooms

Request body

The following table lists the properties of an HTTP request that this action supports.

Required
Parameter nameTypeDescription

type

string

Specifies the type of the room. Acceptable values are limited to the following:
- small_room_for_video: type of a room that supports audio and video, can have up to 6 participants.
- large_room_for_audio_only: type of a room that only supports audio, can have up to 25 participants.

Response

If successful, this action returns a list of room resources in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "room":{
        "created_by":"taem",
        "state":"open",
        "room_id":"79e8e075-0bff-4eb8-a116-2ac8b6464b6b",
        "room_type":"small_room_for_video",
        "created_at":1617686532318,
        "updated_at":1617686532319,
        "current_participants":[

        ]
    }
}

Retrieve a list of rooms

Retrieves all rooms within the application. The retrieved list of rooms are sorted in reverse order, meaning the newest room appears first and the oldest last.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.calls.sendbird.com/v1/rooms

Parameters

The following table lists the properties of an HTTP request that this action supports.

Optional
Parameter nameTypeDescription

limit

string

Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

next

string

Specifies the value of the next property in the response to retrieve the next page in the result set.

type

type

Restricts the search scope to only retrieve rooms of which the type matches any of the specified values. Acceptable values are limited to all, large_room_for_audio_only, and small_room_for_video. (Default: all)

room_ids

string

Searches for rooms which the specified room IDs are included in the parameter value. The string should consist of multiple URL encoded room IDs separated by commas.
Example:
?room_ids=urlencoded_id_1, urlencoded_id_2

* The room_id can be used interchangeably with this parameter, but can only specify one room ID. When both room_id and room_ids are specified, an error will be returned.
* The maximum number of room IDs in a single request is 10.

state

string

Restricts the search scope to only retrieve rooms of which state matches any of the specified value. Acceptable values are limited to open and deleted.

created_at_start_date

int

Specifies the value of time period to restrict the search scope to only retrieve rooms of which the room's created_at is equal to or greater than the specified value, in Unix milliseconds. The search scope may be specified in conjunction with the created_at_end_date parameter. When both the start date and end date aren't provided, the start date will be set to 2 weeks prior to the date which the request was made by default.

created_at_end_date

int

Specifies the value of time period to restrict the search scope to only retrieve rooms of which the room's created_at is less than the specified value, in Unix milliseconds. The search scope may be specified in conjunction with the created_at_start_date parameter.

current_participant_range_gte

int

Specifies the number of current participants to restrict the search scope to only retrieve rooms which the number of participants is equal to or greater than the specified value. The search scope may be specified in conjunction with the current_participant_range_lte parameter.

current_participant_range_lte

int

Specifies the number of current participants to restrict the search scope to only retrieve rooms which the number of participants is equal to or less than the specified value. The search scope may be specified in conjunction with the current_participant_range_gte parameter.

created_by_user_ids

string

Searches for rooms which the specified user IDs of users who created rooms are included in the parameter value. The string should consist of multiple URL encoded user IDs separated by commas.
Example:
?created_by_user_ids=urlencoded_id_1, urlencoded_id_2

* The created_by_user_id can be used interchangeably with this parameter, but can only specify one user ID. When both created_by_user_id and created_by_user_ids are specified, an error will be returned.
* The maximum number of user IDs in a single request is 10.

Query string example
Light Color Skin
Copy
?limit=5&type=small_room_for_video&room_ids=88564d05-8bce-4a21-a955-9359b82bb89e&created_at_start_date=1617686836000&current_participant_range_lte=1

Response

If successful, this action returns a list of room resources in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "rooms":[
        {
            "created_at":1617686836256,
            "created_by":"julia",
            "current_participants":[
                {
                    "client_id":"a8561605-8ace-4a21-a955-935qlwjbb8tq",
                    "connected_at":null,
                    "duration":null,
                    "entered_at":1617686836318,
                    "exited_at":null,
                    "is_audio_on":true,
                    "is_video_on":true,
                    "participant_id":"4d11f4fb-4808-4049-9bef-25e9cce7bfc4",
                    "room_id":"88564d05-8bce-4a21-a955-9359b82bb89e",
                    "state":"entered",
                    "updated_at":1617686836319,
                    "user":{
                        "is_active":true,
                        "metadata":{

                        },
                        "nickname":"Yogini",
                        "profile_url":"https://sendbird.com/main/img/profiles/profile_94_512px.png",
                        "role":null,
                        "user_id":"julia"
                    }
                }
            ],
            "room_id":"88564d05-8bce-4a21-a955-9359b82bb89e",
            "room_type":"small_room_for_video",
            "state":"open",
            "updated_at":1617686836322
        }
    ],
    "next":null
}

List of response properties

Property nameTypeDescription

rooms[]

list

A list of rooms.

next

Nullable[string]

The value for the next parameter to retrieve the next page in the result set.


Retrieve a room

Retrieves a specific room.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.calls.sendbird.com/v1/rooms/{room_id}

Parameters

The following table lists the properties of an HTTP request that this action supports.

Required
Parameter nameTypeDescription

room_id

string

Specifies the unique ID of the target room.

Response

If successful, this action returns a list of room resources in the response body.

Light Color Skin
Copy
{
    "room":{
        "created_at":1617686836256,
        "created_by":"tree",
        "current_participants":[
            {
                "client_id":"a8561605-8ace-4a21-a955-935qlwjbb8tq",
                "connected_at":null,
                "duration":null,
                "entered_at":1617686836318,
                "exited_at":null,
                "is_audio_on":true,
                "is_video_on":true,
                "participant_id":"4d11f4fb-4808-4049-9bef-25e9cce7bfc4",
                "room_id":"88564d05-8bce-4a21-a955-9359b82bb89e",
                "state":"entered",
                "updated_at":1617686836319,
                "user":{
                    "is_active":true,
                    "metadata":{

                    },
                    "nickname":"springtime",
                    "profile_url":"https://sendbird.com/main/img/profiles/profile_97_512px.png",
                    "role":null,
                    "user_id":"tree"
                }
            }
        ],
        "room_id":"88564d05-8bce-4a21-a955-9359b82bb89e",
        "room_type":"small_room_for_video",
        "state":"open",
        "updated_at":1617686836322
    }
}

Participant

A participant is created in a room when a user enters the room. A user can enter a room from multiple devices. In such a case, a participant representing the same user will be created for each device.


Resource representation

The following table shows the list of properties in a participant resource.

Property nameTypeDescription

room_id

string

A unique identifier for the room.

participant_id

string

A unique identifier for the participant.

entered_at

long

The timestamp of when the participant entered the room, in Unix milliseconds.

updated_at

long

The timestamp of when the participant information was updated within the room, in Unix milliseconds.

exited_at

Nullable[long]

The timestamp of when the participant exited the room, in Unix milliseconds.

* This value is null until the participant leaves the room.

duration

Nullable[long]

The period from the time when the participant entered the room to the time the participant left the room, measured in seconds.

* This value is null until the participant leaves the room.

connected_at

Nullable[long]

The timestamp of when the participant was connected and streaming media in the room, in Unix milliseconds.

* This value is null until the participant leaves the room.

client_id

string

The unique ID of the client.

state

string

The state of the participant. Valid values are limited to the following:
- entered: Indicates that a participant entered the room.
- connected: Indicates that a participant is connected and streaming media.
- exited: Indicates that a participant exited the room.

user

User

The user who can access all features of the room.

is_audio_on

bool

Indicates whether the participant has turned on their audio.

is_video_on

bool

Indicates whether the participant has turned on their video.


Retrieve a list of participants within the room

Retrieves all participants that were created in the room. The retrieved list of participants are sorted in reverse order, meaning the newest participant appears first and the oldest last.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.calls.sendbird.com/v1/rooms/{room_id}/participants

Parameters

The following table lists the properties of an HTTP request that this action supports.

Required
Parameter nameTypeDescription

limit

string

Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

Optional
Parameter nameTypeDescription

next

string

Specifies the value of the next property in the response to retrieve the next page in the result set.

Query string example
Light Color Skin
Copy
?limit=5&next=sWzRa3BTQlArEUBXWnNPF2p2FEd3yZ~~&..

Response

If successful, this action returns a list of participant resources in the response body.

Light Color Skin
Copy
{
    "next":"LWs1OQJJR1FKR1gCBBcdRCQWJysCSUdOGwFWDEkGDwNsa3RwXQ",
    "participants":[
        {
            "client_id":"2fc3a5c4-4c05-4f21-a9b0-94d0d2994acf",
            "connected_at":null,
            "duration":0,
            "entered_at":1617687128092,
            "exited_at":1617687128195,
            "is_audio_on":true,
            "is_video_on":true,
            "participant_id":"57cbfbe2-ddea-41d0-9896-e41e28e2c8ad",
            "room_id":"8f651f0a-e3f7-40eb-869a-85b4721f844b",
            "state":"exited",
            "updated_at":1617687128196,
            "user":{
                "is_active":true,
                "metadata":{

                },
                "nickname":"taem_rocks",
                "profile_url":"https://sendbird.com/main/img/profiles/profile_99_512px.png",
                "role":null,
                "user_id":"taem"
            }
        }
    ]
}