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

Overview

A live event can perform a variety of actions relevant to running and watching the event. This document explains how you can manage and retrieve information on live events in a Sendbird application using the Sendbird Live Platform API.


Resource representation

The following tables show the list of properties in a live event resource.

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

boolean

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: false)

created_by

string

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

set_ready_by

string

The ID of the user who sets the live event to ready to get the live event started. If the live event is set ready by the Platform API, an empty string will return.

started_by

string

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

ended_by

string

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

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 IDs of the users who can be the host for the live event. This property can have up to 10 user IDs.

title

string

The title of a live event. The length is limited to 191 characters.

cover_url

string

The URL of the cover image for the live event. The length is limited to 2,048 characters.

custom_items

nested object

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.


Actions

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

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 {live_event_id}.

List of actions

ActionHTTP request

Create a live event

POST /live-events
Creates a live event.

Set a live event to 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.

Update a live event

PUT /live-events/{live_event_id}
Updates information of 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.