Calls / Platform API
Home
/
Calls
/
Platform API

Group call

This page explains the key functions of group call consisting of how to create, delete 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.

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.

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}.sendbird.com/v1/rooms

Request body

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

Parameters
RequiredTypeDescription

room_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.
(Default: small_room_for_video)

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}.sendbird.com/v1/rooms

Parameters

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

Required
NameTypeDescription

limit

string

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

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)

Optional
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&type=small_room_for_video&...

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

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}.sendbird.com/v1/rooms/{room_id}

Parameters

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

Required
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.

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. he 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}.sendbird.com/v1/rooms/participants

Parameters

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

Required
NameTypeDescription

limit

string

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

Optional
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"
            }
        }
    ]
}