Calls Platform API v1

Calls Platform API

Version 1

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.

Resource representation

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

List of room properties

Property name	Type	Description
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

Property name	Type	Description
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 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

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

Action	HTTP 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

Creates a room for group calls.

HTTP request

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.

Parameters

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

Optional	Type	Description
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

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

Status: 200 OK

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

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

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

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
room_id	string	The unique ID of the target room.

Response

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

Status: 200 OK

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

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

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 name	Type	Description
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.

Query string example

?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

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

Property name	Type	Description
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

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 name	Type	Description
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.

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

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

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

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
room_id	string	The unique ID of the target room.

Response

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.

Status: 200 OK

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

List of response properties

Property name	Type	Description
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

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

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
room_id	string	The unique ID of the target room.

Request body

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

Properties

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

Optional	Type	Description
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.

Request body example

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

Response

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

Status: 200 OK

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

Property name	Type	Description
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

Deletes custom items of a specific room.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
room_id	string	The unique ID of the target room.

Request body

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

Optional

Property name	Type	Description
keys	array	Specifies the keys of custom items to delete. If not specified, all custom items of the room are deleted.

Request body example

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

Response

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

Status: 200 OK

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

Property name	Type	Description
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

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

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 name	Type	Description
limit	string	Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

Optional

Parameter name	Type	Description
next	string	Specifies the value of the next property in the response to retrieve the next page in the result set.

Query string example

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

Response

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

On this page

Resource representation Actions Create a room Delete a room Retrieve a list of rooms Retrieve a room Retrieve all custom items of a room Update custom items of a room Delete custom items of a room Retrieve a list of participants within the room