Live / Platform API
Live Platform API v1
Live Platform API
Live
Platform API
Home
/
Live
/
Platform API

Sendbird Live Beta Platform API

With Sendbird Live beta API, you can manage and retrieve information on live events. After you have created a live event, you can change the states of a live event from created to ready, ongoing, and ended. For live events that have been created, information on the host and participants can be retrieved.

This document explains how you can manage and retrieve information on live events in a Sendbird application using the Sendbird Live beta Platform API.

Note: This documentation is intended for customers participating in the Sendbird Live beta program, launched on September 15th, 2022.


Resource representation

The following tables show the list of properties in a live event resource, a host resource, and a participant resource.

List of live event properties

Property nameTypeDescription

live_event_id

string

A unique ID of the live event.

host_type

string

Indicates a type of host for the live event. A valid value is single_host.

created_at

long

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

set_ready_at

long

The timestamp of when the live event was set to ready, in Unix milliseconds.

started_at

long

The timestamp of when the live event was started, in Unix milliseconds.

ended_at

long

The timestamp of when the live event ended, in Unix milliseconds.

state

string

The state of the live event. Valid values are the following:
- created: Indicates the live event is created and the host can enter. The host can stream media.
- ready: Indicates the live event is ready to get started and participants can enter and chat with the host. The host can stream media but participants can’t receive it.
- ongoing : Indicates the live event is ongoing and participants can receive media streaming of the host and chat.
- ended: Indicates the live event has ended.

is_host_streaming

bool

Indicates whether the host is streaming their media while the live event is in the ongoing state or whether the host exited the live event. Default value is false.

created_by

string

The user ID of the user who created the live event. If the live event is created by using Platform API, an empty string will be returned.

set_ready_by

string

The user ID of the user who sets the live event to ready to get the live event started.

started_by

string

The user ID of the user who started the live event. If the live event is started by using Platform API, an empty string will be returned.

ended_by

string

The user ID of the user who ended the live event. If the live event is ended by using Platform API, an empty string will be returned.

duration

int

The period from when the live event was created to when the live event was ended, in milliseconds.

host

Host

The user who is the host of the live event.

participant_count

int

The number of participants in the live event which is counted by the number of devices and browsers concurrently connected to the Sendbird server.

peak_participant_count

int

The highest number of participant_count measured during the live event.

cumulative_participant_count

int

The sum of all participants that entered and exited the live event.

user_ids_for_host

array of strings

An array of the user IDs of the users who can be the host for the live event. This property can have up to 10 user IDs.

custom_items

nested object

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

List of host properties

Property nameTypeDescription

host_id

string

A unique ID of the host.

entered_at

long

The timestamp of when the host entered the live event, in Unix milliseconds.

connected_at

long

The timestamp of when the host was connected and media streaming of the host started, in Unix milliseconds.

disconnected_at

long

The timestamp of when the host was disconnected and media streaming of the host stopped, in Unix milliseconds.

exited_at

long

The timestamp of when the host exited the live event, in Unix milliseconds.

duration

int

The period from when the host entered the live event to when the host left the live event, in milliseconds.

user

User

The user who can access features of a host in the live event.

client_id

string

The unique ID of the client.

state

string

The state of the host. Valid values are the following:
- entered: Indicates that the host entered the live event.
- connected: Indicates that the host is connected to the Sendbird server and media streaming of the host has started.
- disconnected: Indicates that the host is disconnected from the Sendbird server and media streaming of the host has ended.
- exited: Indicates that the host exited the live event.

is_audio_on

bool

Indicates whether the host has turned on their audio.

is_video_on

bool

Indicates whether the host has turned on their video.

live_event_id

string

The unique ID of the live event.

List of participant properties

Property nameTypeDescription

participant_id

string

The unique ID of the participant.

entered_at

long

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

exited_at

long

The timestamp of when the participant left the live event, in Unix milliseconds.

duration

int

The period from when the participant entered the live event to when the participant left the live event, in milliseconds.

user

User

The user who can access features of a participant in the live event.

client_id

string

The unique ID of the client.

state

string

The state of the participant.

live_event_id

string

The unique ID of the live event.


Actions

API endpoints are relative to the base URL allocated to your application. In this documentation, the /live-events endpoint refers to the following.

https://api-{application_id}.calls.sendbird.com/v1/live-events

Note: To get 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 URL encoded, such as {user_id}.


List of actions

ActionHTTP request

Create a live event

POST /live-events
Creates a live event.

Set a live event ready

POST /live-events/{live_event_id}/ready
Sets a specific live event to be ready to get started.

Start a live event

POST /live-events/{live_event_id}/start
Starts a specific live event.

End a live event

DELETE /live-events/{live_event_id}
Ends a specific live event.

Retrieve a live event

GET /live-events/{live_event_id}
Retrieves a specific live event.

Retrieve a list of live events

GET /live-events
Retrieves all live events within the application.

Retrieve a host

GET /live-events/{live_event_id}/hosts
Retrieves the host in a specific live event.

Retrieve participants

GET /live-events/{live_event_id}/participants
Retrieves all participants in a specific live event.


Create a live event

Creates a live event. A live event can be created instantly.

HTTP request

POST https://api-{application_id}.calls.sendbird.com/v1/live-events

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

host_type

string

The type of a host. An acceptable value is single_host.

user_ids_for_host

array of string

An array of user IDs of the users who can be host for the live event. This property can have up to 10 user IDs.

Response

If successful, this action returns a newly created live event in the response body.

{
    "live_event": {
        "live_event_id": "6eec7ed4-c0ed-4480-843f-6497be86b8c6",
        "host_type": "single_host",
        "state": "created",
        "created_at": 1657689300179,
        "set_ready_at": None,
        "started_at": None,
        "ended_at": None,
        "is_host_streaming": False,
        "host": None,
        "created_by": "testuser-666e8b1",
        "set_ready_by": "",
        "started_by": "",
        "ended_by": "",
        "duration": 0,
        "participant_count": 0,
        "peak_participant_count": 0,
        "cumulative_participant_count": 0,
        "user_ids_for_host": ["testuser-666e8b1"],
        "custom_items": {},
    }
}

List of response properties

Property nameTypeDescription

live_event

nested object

The live event that has been created.


Set a live event ready

Sets a live event ready. When a live event is in the ready state, users can start to enter the live event as participants and chat with the host. The host can stream their media but participants can’t watch or hear the host.

HTTP request

POST https://api-{application_id}.calls.sendbird.com/v1/live-events/{live_event_id}/ready

Response

If successful, this action returns a live event that has been set to ready in the response body.

{
    "live_event": {
        "live_event_id": "60fce3f2-840a-49d2-99e9-4de7206010b5",
        "host_type": "single_host",
        "state": "ready",
        "created_at": 1657689627823,
        "set_ready_at": 1657689627867,
        "started_at": None,
        "ended_at": None,
        "is_host_streaming": False,
        "host": None,
        "created_by": "testuser-00be487",
        "set_ready_by": "testuser-00be487",
        "started_by": "",
        "ended_by": "",
        "duration": 0,
        "participant_count": 0,
        "peak_participant_count": 0,
        "cumulative_participant_count": 0,
        "user_ids_for_host": ["testuser-00be487"],
        "custom_items": {},
    }
}

List of response properties

Property nameTypeDescription

live_event

nested object

The live event that has been set to ready.


Start a live event

Starts a live event. When a live event starts, the state of the event changes to ongoing and participants can receive the media stream from the host and chat with the host.

HTTP request

POST https://api-{application_id}.calls.sendbird.com/v1/live-events/{live_event_id}/start

Response

If successful, this action returns a live event that has been started in the response body.

{
    "live_event": {
        "live_event_id": "5ae1fdb3-1f86-4bd5-8b0a-1a0d472ef262",
        "host_type": "single_host",
        "state": "ongoing",
        "created_at": 1657689806089,
        "set_ready_at": 1657689806115,
        "started_at": 1657689806237,
        "ended_at": None,
        "is_host_streaming": False,
        "host": {
            "client_id": "test-client-id",
            "duration": 0,
            "exited_at": None,
            "entered_at": 1657689806172,
            "state": "entered",
            "live_event_id": "5ae1fdb3-1f86-4bd5-8b0a-1a0d472ef262",
            "host_id": "5eaae39f-d5b1-4b52-93a5-ea81d9338f37",
            "connected_at": None,
            "disconnected_at": None,
            "is_audio_on": True,
            "is_video_on": True,
            "user": {
                "user_id": "testuser-d8208e98",
                "nickname": "",
                "profile_url": "",
                "metadata": {},
                "is_active": True,
                "role": None,
            },
        },
        "created_by": "testuser-d8208e98",
        "set_ready_by": "testuser-d8208e98",
        "started_by": "testuser-d8208e98",
        "ended_by": "",
        "duration": 0,
        "participant_count": 0,
        "peak_participant_count": 0,
        "cumulative_participant_count": 0,
        "user_ids_for_host": ["testuser-d8208e98"],
        "custom_items": {},
    }
}

List of response properties

Property nameTypeDescription

live_event

nested object

The live event that has been started.


End a live event

Ends a live event. When a live event ends, participants are forced out of the live event.

HTTP request

DELETE https://api-{application_id}.calls.sendbird.com/v1/live-events/{live_event_id}

Response

If successful, this action returns information about a live event that has been deleted in the response body.

{
    "live_event": {
        "live_event_id": "9c74953c-4f5a-4710-8943-f2f7f5175143",
        "host_type": "single_host",
        "state": "ended",
        "created_at": 1657690113715,
        "set_ready_at": 1657690113746,
        "started_at": 1657690113875,
        "ended_at": 1657690113932,
        "is_host_streaming": False,
        "host": None,
        "created_by": "testuser-0dc2e79",
        "set_ready_by": "testuser-0dc2e79",
        "started_by": "testuser-0dc2e79",
        "ended_by": "testuser-0dc2e79",
        "duration": 216,
        "participant_count": 0,
        "peak_participant_count": 0,
        "cumulative_participant_count": 0,
        "user_ids_for_host": ["testuser-0dc2e79"],
        "custom_items": {},
    }
}

List of response properties

Property nameTypeDescription

live_event

nested object

The live event that has been ended.


Retrieve a live event

Retrieves a specified live event. Only an ongoing live event can be retrieved.

HTTP request

GET https://api-{application_id}.calls.sendbird.com/v1/live-events/{live_event_id}

Response

If successful, this action returns a live event in the response body.

{
    "live_event": {
        "live_event_id": "60fce3f2-840a-49d2-99e9-4de7206010b5",
        "host_type": "single_host",
        "state": "ready",
        "created_at": 1657689627823,
        "set_ready_at": 1657689627867,
        "started_at": None,
        "ended_at": None,
        "is_host_streaming": False,
        "host": None,
        "created_by": "testuser-00be487",
        "set_ready_by": "testuser-00be487",
        "started_by": "",
        "ended_by": "",
        "duration": 0,
        "participant_count": 5,
        "peak_participant_count": 7,
        "cumulative_participant_count": 21,
        "user_ids_for_host": ["testuser-00be487"],
        "custom_items": {},
    }
}

Retrieve a list of live events

Retrieves a list of live events. Only ongoing live events can be retrieved.

HTTP request

GET https://api-{application_id}.calls.sendbird.com/v1/live-events

Parameters

The following table lists the parameters that this action supports.

Parameters
OptionalTypeDescription

host_type

string

Restricts the search scope to only retrieve live events of which the host_type matches any of the specified values. An acceptable value is single_host.

state

string

Restricts the search scope to only retrieve live events of which state matches any of the specified values. Acceptable values are the following:
- created: Indicates the live event is created and the host can enter. The host can stream media.
- ready: Indicates the live event is ready to get started and participants can enter and chat with the host. The host can stream media but participants can’t receive it.
- ongoing : Indicates the live event is ongoing and participants can receive media streaming of the host and chat.
- ended : Indicates the live event has ended.

created_at_start_date

int

Specifies the value of time period to restrict the search scope to only retrieve live events of which the live event's created_at is equal to or greater than the specified value, in Unix milliseconds.

created_at_end_date

int

Specifies the value of time period to restrict the search scope to only retrieve live events of which the live event's created_at is less than the specified value, in Unix milliseconds.

participant_count_range_gte

int

Specifies the number of current participants to restrict the search scope to only retrieve live events of which the number of participants is equal to or greater than the specified value.

participant_count_range_lte

int

Specifies the number of current participants to restrict the search scope to only retrieve lives of which the number of participants is equal to or less than the specified value.

live_event_ids

string

Searches for live events which the specified live event IDs are included in the parameter value. The string should consist of multiple URL encoded live event IDs separated by commas.
-The live_event_id can be used interchangeably with this parameter, but can only specify one live ID. When both live_event_id and live_event_ids are specified, an error will be returned.
-The maximum number of live IDs in a single request is 10.

created_by_user_ids

string

Searches for live events which the specified user IDs of users who created live events are included in the parameter value. The string should consist of multiple URL encoded user IDs separated by commas.
-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.

duration_range_gte

long

Specifies the value of the duration to restrict search scope to only retrieve live events of which duration is equal to or greater than the specified value, in Unix milliseconds.

duration_range_lte

long

Specifies the value of the duration to restrict search scope to only retrieve live events of which duration is less than the specified value, in Unix milliseconds.

limit

int

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

prev

string

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

next

string

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

Response

If successful, this action returns a list of all live events in the application in the response body.

{
    "live_events": [
        {
            "created_at": 1657690472593,
            "created_by": "",
            "cumulative_participant_count": 0,
            "custom_items": {},
            "duration": 0,
            "ended_at": 1657690472579,
            "ended_by": "",
            "host": None,
            "host_type": "single_host",
            "is_host_streaming": False,
            "live_event_id": "bbecbb12-6756-4421-a80b-68cdffabe6bc",
            "participant_count": 0,
            "peak_participant_count": 0,
            "set_ready_at": None,
            "set_ready_by": "",
            "started_at": 1657690472579,
            "started_by": "",
            "state": "ended",
            "user_ids_for_host": None,
        },
        ... # More live events
    ],
    "next": "LWs1OQJJV1FeRxtSDwALfjQwZ2gCXgwHUElWQx1HQwNnazg",
    "prev": None,
}

List of response properties

Property nameTypeDescription

live_event

nested object

The live event that has been retrieved.

prev

string

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

next

string

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


Retrieve a host

Retrieves a host of a live event.

HTTP request

GET https://api-{application_id}.calls.sendbird.com/v1/live-events/{live_event_id}/hosts

Response

If successful, this action returns the host of the specified live event.

{
    "host": {
        "live_event_id": "225225c0-9097-431b-8317-fbf1fd6c8153",
        "host_id": "96705b6c-6ee4-44ac-b85c-8e08d3486443",
        "client_id": "57380739-8aa2-405e-a840-f15053d6fba1",
        "state": "connected",
        "duration": 0,
        "entered_at": 1657692359322,
        "connected_at": 1657692489322,
        "disconnected_at": None,
        "exited_at": None,
        "is_audio_on": True,
        "is_video_on": True,
        "user": {
            "user_id": "_Hi6='",
            "nickname": "",
            "profile_url": "",
            "metadata": {},
            "is_active": False,
            "role": None,
        },
    }
}

List of response properties

Property nameTypeDescription

host

nested object

The user who acts as host for the live event.


Retrieve participants

Retrieves all participants in a live event.

HTTP request

GET https://api-{application_id}.calls.sendbird.com/v1/live-events/{live_event_id}/participants

Parameters

The following table lists the parameters that this action supports.

Parameters
OptionalTypeDescription

limit

int

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

prev

string

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

next

string

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

Response

If successful, this action returns all participants in the specified live event.

{
    "participants": [
        {
            "client_id": "test-client-id",
            "duration": 0,
            "entered_at": 1657692983239,
            "exited_at": None,
            "live_event_id": "1b06a54c-807b-4caa-8a25-3a97ee4fe691",
            "participant_id": "1e411c1d-af5e-49e8-ae20-a463f93be4d1",
            "state": "entered",
            "user": {
                "is_active": True,
                "metadata": {},
                "nickname": "",
                "profile_url": "",
                "role": None,
                "user_id": "vier-testuser-5652b67139e240c39c135604e54c9c02-1657692981",
            },
        },
        {
            "client_id": "test-client-id",
            "duration": 0,
            "entered_at": 1657692983171,
            "exited_at": None,
            "live_event_id": "1b06a54c-807b-4caa-8a25-3a97ee4fe691",
            "participant_id": "079518e1-8921-4831-b812-76d1b57c9de7",
            "state": "entered",
            "user": {
                "is_active": True,
                "metadata": {},
                "nickname": "",
                "profile_url": "",
                "role": None,
                "user_id": "vier-testuser-43103ce314a44f11a630df76f03e59c3-1657692981",
            },
        },
        ... # More participants
    ],
    "prev": "LWs1OQJJV1FeRxtSDwALfjQwZ2gCXgwHUElWQx1HQwNnazg",
    "next": None,
}

List of response properties

Property nameTypeDescription

participants

nested object

The users who participated in the live event.

prev

string

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

next

string

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