Calls Platform API v1
Calls Platform API
Calls Platform API
Version 1

Group call

Copy link

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.


Resource representation

Copy link

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

List of room properties

Copy link
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 large_room_for_audio_only which can hold up to 100 participants and small_room_for_video which can hold up to 6 participants.

created_at

long

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

updated_at

long

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

state

string

The state of the room. Valid values are the following:
- Open: Indicates that users can enter the room to participate in a group call.
- Deleted: Indicates that users can't enter the room and the room can't be reopened.

created_by

string

The user ID of the user who created the room. If the room is created with the Platform API, an empty string will be returned.

deleted_by

string

The user ID of the user who deleted the room. If the room is deleted with the Platform API, an empty string will be returned.

current_participants[]

list

The users who are currently in the room.

custom_items

nested object

Specifies a JSON object that has custom key-value items to add. The key and value must be a string and its length is limited to 128 characters. This parameter can have up to 10 custom items.

List of participant properties

Copy link
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 connected to the room and began streaming media, in Unix milliseconds.

client_id

string

The unique ID of the client.

state

string

The state of the participant. Valid values are 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.


Actions

Copy link
  • API endpoints are relative to the base URL allocated to your application. In this page, the /rooms endpoint refers to https://api-{application_id}.calls.sendbird.com/v1/rooms.

Note: If you want to know your application ID, sign in to your dashboard, go to the Settings > Application > General, and then check the Application ID.

  • It's recommended that the parameter values in API URLs be urlencoded, such as {user_id}.

List of actions

Copy link
ActionHTTP request

Create a room

POST /rooms
Creates a room.

Delete a room

DELETE /rooms/{room_id}
Deletes a specific room.

Retrieve a list of rooms

GET /rooms
Retrieves all rooms within the application.

Retrieve a room

GET /rooms/{room_id}
Retrieves a specific room.

Retrieve all custom items of a room

GET /rooms/{room_id}/custom_items
Retrieves all custom items of a specific room.

Update custom items of a room

PUT /rooms/{room_id}/custom_items
Updates custom items of a specific room.

Delete custom items of a room

DELETE /rooms/{room_id}/custom_items
Deletes custom items of a specific room.

Retrieve a list of participants within the room

GET /rooms/{room_id}/participants
Retrieves all participants within a specific room.


Create a room

Copy link

Creates a room for group calls.

HTTP request

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

Request body

Copy link

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

Parameters
RequiredTypeDescription

type

string

Specifies the type of the room. Acceptable values are 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 100 participants.

OptionalTypeDescription

custom_items

nested object

Specifies a JSON object that has key-value custom items to add. The key and value must be a string and its length is limited to 128 characters. This parameter can have up to 10 custom items.

Response

Copy link

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

{
    "room": {
        "created_by": "taem",
        "deleted_by": "",
        "state": "open",
        "room_id": "79e8e075-0bff-4eb8-a116-2ac8b6464b6b",
        "room_type": "small_room_for_video",
        "created_at": 1617686532318,
        "updated_at": 1617686532319,
        "current_participants": [],
        "custom_items": {},
    }
}

Delete a room

Copy link

Deletes a specific room. Once a room is deleted, the current participants are removed from the room and the room can't be reopened. Users can retrieve a deleted room, but can't enter it. Also, the custom items of the deleted room can be retrieved, but can't be updated or deleted.

HTTP request

Copy link
DELETE https://api-{application_id}.calls.sendbird.com/v1/rooms/{room_id}

Parameters

Copy link

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

room_id

string

The unique ID of the target room.

Response

Copy link

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

{
    "room":{
        "created_by":"changwan",
        "deleted_by":"",
        "state":"deleted",
        "room_id":"3b6e7d23-e16d-431d-8bd9-dda147e2aaa0",
        "room_type":"small_room_for_video",
        "created_at":1617614146233,
        "updated_at":1617614196257,
        "current_participants":[],
        "custom_items":{}
    }
}

Retrieve a list of rooms

Copy link

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

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

Parameters

Copy link

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

?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

Copy link

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

{
    "rooms":[
        {
            "created_at":1617686836256,
            "created_by":"julia",
            "deleted_by":"",
            "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":"",
                        "profile_url":"",
                        "role":null,
                        "user_id":"vier-testuser-2fde908137d0409a88bb1c18a04ff2d9-1617686833"
                    }
                }
            ],
            "room_id":"88564d05-8bce-4a21-a955-9359b82bb89e",
            "room_type":"small_room_for_video",
            "state":"open",
            "updated_at":1617686836322,
            "custom_items":{

            }
        }
    ],
    "next":null
}

List of response properties

Copy link
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

Copy link

Retrieves a specific room.

HTTP request

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

Parameters

Copy link

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

Copy link

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

{
    "room":{
        "created_at":1617686836256,
        "created_by":"tree",
        "deleted_by":"",
        "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":"",
                    "profile_url":"",
                    "role":null,
                    "user_id":"vier-testuser-2fde908137d0409a88bb1c18a04ff2d9-1617686833"
                }
            }
        ],
        "room_id":"88564d05-8bce-4a21-a955-9359b82bb89e",
        "room_type":"small_room_for_video",
        "state":"open",
        "updated_at":1617686836322,
        "custom_items":{

        }
    }
}

Retrieve all custom items of a room

Copy link

Retrieves all custom items of a specific room. A room can have custom key-value items which store additional information for the room.

Note: When a room is created, its custom items have no values by default.

HTTP request

Copy link
GET https://api-{application_id}.sendbird.com/v1/rooms/{room_id}/custom_items

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

room_id

string

The unique ID of the target room.

Response

Copy link

If custom items already exist in the target room, this action returns the custom items including the updated or newly added ones in the response body.

{
  "custom_items": {
    "is_paid_call": "Y",
    "call_quality": "HIGH",
  },
  "affected_at": 1574764792342
}

List of response properties

Copy link
Property nameTypeDescription

custom_items

nested object

The custom items including the updated or newly added ones.

affected_at

long

The time of when the specified custom items have been updated, in Unix milliseconds. If custom items do not exist in the target room, affected_at is excluded in the response.


Update custom items of a room

Copy link

Updates custom items of a specific room. A room can have custom key-value items which store additional information for the room.

HTTP request

Copy link
PUT https://api-{application_id}.sendbird.com/v1/rooms/{room_id}/custom_items

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

room_id

string

The unique ID of the target room.

Request body

Copy link

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

Properties
RequiredTypeDescription

custom_items

nested object

Specifies a JSON object that has key-value custom items to update. The key and value must be a string and its length is limited to 128 characters. This parameter can have up to 10 custom items.

OptionalTypeDescription

mode

string

Determines whether to update the existing custom items or add new custom items. Acceptable values are the following:
- upsert (default): The existing items are updated with new values when there are already custom items with the same keys.
- insert: New key-value custom items are added when the keys don't exist on the list of custom items.

{
    "custom_items":{
        "is_paid_call":"Y",
        "call_quality":"HIGH",
        "satisfaction_score":"5",
        "satisfaction_comment":"Good quality!"
    },
    "mode":"upsert"
}

Response

Copy link

If successful, this action returns custom items including the updated or newly added ones in the response body.

{
    "room_id":"25168092-A882-4173-8EED-158AA8542BFC",
    "updated":[
        "satisfaction_score",
        "satisfaction_comment"
    ],
    "custom_items":{
        "is_paid_call":"Y",
        "call_quality":"HIGH",
        "satisfaction_score":"5",
        "satisfaction_comment":"Good quality!"
    },
    "affected_at":1574763467896
}

List of response properties

Copy link
Property nameTypeDescription

room_id

string

The unique ID of the target room.

updated

array

An array of the keys for updated custom items.

custom_items

nested object

The custom items including the updated or newly added ones.

affected_at

long

The time of when the specified custom items have been updated, in Unix milliseconds.


Delete custom items of a room

Copy link

Deletes custom items of a specific room.

HTTP request

Copy link
DELETE https://api-{application_id}.calls.sendbird.com/v1/rooms/{room_id}/custom_items

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

room_id

string

The unique ID of the target room.

Request body

Copy link

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

Optional
Property nameTypeDescription

keys

array

Specifies the keys of custom items to delete. If not specified, all custom items of the room are deleted.

{
    "keys": ["satisfaction_score", "satisfaction_comment"]
}

Response

Copy link

If successful, this action returns custom items excluding the deleted ones in the response body.

{
    "room_id":"25168092-A882-4173-8EED-158AA8542BFC",
    "deleted":[
        "satisfaction_score",
        "satisfaction_comment"
    ],
    "custom_items":{
        "is_paid_call":"Y",
        "call_quality":"HIGH"
    },
    "affected_at":1574764792341
}

List of response properties

Copy link
Property nameTypeDescription

room_id

string

The unique ID of the target room.

deleted

array

An array of the keys for deleted custom items.

custom_items

nested object

The custom items excluding the deleted custom items.

affected_at

long

The time of when the specified custom items have been deleted, in Unix milliseconds.


Retrieve a list of participants within the room

Copy link

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

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

Parameters

Copy link

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.

?limit=5&next=sWzRa3BTQlArEUBXWnNPF2p2FEd3yZ~~&..

Response

Copy link

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

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