# Trovo APIs & OAuth Developer Doc

# 1. Introduction

Welcome, you are one of our first users of Trovo’s APIs! We are so glad to have you here. If you have any questions or feedback, please don’t hesitate to contact us. Through the feedback button in trovo.live, or email us at developer@trovo.live. We appreciate any feedback or advice. We will work hard to improve our platform to make it good and easy for you to integrate with.

Trovo provides a RESTful API for developers to retrieve and update info on Trovo.

Register your app and obtain a client ID before you make API calls. All responses are in JSON blobs.

# 2. Register Your Application

To make an application that uses the Trovo API, you first need to register your application. Once you create a developer application, you are assigned a client ID.

Currently the review process could take less than a week. We may contact you for follow up questions through the email address you provided. You may also contact us through the email developer@trovo.live.

To register your application, You will need to provide the following information:

  • Your application name.
  • Your company name.
  • Contact name and email.
  • Logo picture used for OAuth process, recommended 500x500 px.
  • Redirect URL for OAuth process.
  • Links of terms of service and privacy policy docs, and/or any other terms you want the user to acknowledge through the process.
  • Your product description and links to your product.

Glossary:

Name Description
Client Id Alphanumeric identifier used to authenticate an application making an API call.Client IDs should be unique for each application: do not re-use client IDs across multiple applications. Also, applications should request the appropriate set of scopes for the intended target APIs.
Access Token Authenticate users and allow your app to make requests on their behalf. If your application uses Trovo for login or makes requests in the context of an authenticated user, you need to generate a user access token.

# 3. Authentication

You can use OAuth 2.0 to authenticate with our APIs. We follow the OAuth 2.0 Spec as closely as possible. So if you're familiar it should be easy to get up and running.

This guide describes how to use Trovo authentication to enable your application to take actions on behalf of a Trovo account or access certain data about user’s accounts. We use parts of the (opens new window)OAuth 2.0 protocol (opens new window).

# 3.1. Getting OAuth Tokens: OAuth 2.0 Implicit Flow

  1. After the user clicks the button (sample: "Login with Trovo"), you should direct the user to this URI, which you generated following the format below. This brings the user to the OAuth page for login and authorization.

Trovo Authentication URI format - Implicit Flow:

https://open.trovo.live/page/login.html
?client_id=<your_client_id>
&response_type=token
&scope=<scopes_seperated_by_plus_sign>
&redirect_uri=<redirect_url>
&state=<state>
1
2
3
4
5
6

Example:

https://open.trovo.live/page/login.html?client_id=xxxxxxxxxx
&response_type=token
&scope=channel_details_self+channel_update_self+user_details_self
&redirect_uri=https%3A%2F%2Ftrovo.live
&state=statedata
1
2
3
4
5

URL Params:

Param Required Type Description
client_id required string Your client ID.
redirect_uri required URI Your registered redirect URI. This must exactly match the redirect URI registered in the prior, Registration step.
response_type required string This must be “token”, to return an access token using implicit grant.
scope required string “+” separated list of scopes.
state optional string Your unique token, generated by your application. This is an OAuth 2.0 opaque value, used to avoid CSRF attacks. This value is echoed back in the response. We strongly recommend you use this.
  1. If the user authorizes your application, the user is redirected to your redirect URI. The Access token will be returned along the redirect URI, scope you required, state and token_type (Currently the only token type is “OAuth”):
https://<your_registered_redirect_URI>/#access_token=<access_token>
&scope=<scopes>
&state=<state>
&token_type=OAuth
1
2
3
4

The response includes the state parameter, if it was in your request.

Example url after user authenticated:

https://trovo.live/?access_token=xxxxxxxxxxx
&expires_in=864000
&token_type=OAuth
&scope=channel_subscriptions%20channel_details_self%20channel_update_self%20user_details_self
&client_id=xxxxxxxxxxxxxxxxxxxxxx
&language=en-US
&response_type=token
&redirect_uri=https%3A%2F%2Ftrovo.live
&state=statedata
1
2
3
4
5
6
7
8
9

Params:

Param Description
access_token The access token specifically for your application of the user with the scopes authorized. You will use this access token to call APIs. And if more scope is needed, you will need to have the user authorize again for new scopes.
expires_in Expiration period, unit seconds.
token_type OAuth
scope “+” separated list of scopes.
client_id The client id passed in.
language Language user chosen during the OAuth steps. E.g. en-US.
response_type “token” for implicit grant flow.
redirect_url The redirect url passed in from previous steps.
state Your unique token, generated by your application. This is an OAuth 2.0 opaque value, used to avoid CSRF attacks. This value is echoed back in the response. We strongly recommend you use this.

# 3.2. Getting OAuth Tokens: OAuth 2.0 Authorization Code Flow

  1. After the user clicks the button (sample: “Login with Trovo”), you should direct the user to this URI, which you generated following the format below. This brings the user to the OAuth page for login and authorization.

Trovo Authentication URI format - Authorization Code Flow:

https://open.trovo.live/page/login.html
?client_id=<your_client_id>
&response_type=code
&scope=<scopes_seperated_by_plus_sign>
&redirect_uri=<redirect_url>
&state=<state>
1
2
3
4
5
6

Example:

https://open.trovo.live/page/login.html?client_id=xxxxxxxxxx
&response_type=code
&scope=channel_details_self+channel_update_self+user_details_self
&redirect_uri=https%3A%2F%2Ftrovo.live
&state=statedata
1
2
3
4
5

URL Params:

Param Required Type Description
client_id required string Your client ID.
redirect_uri required URI Your registered redirect URI. This must exactly match the redirect URI registered in the prior, Registration step.
response_type required string This must be “code”, to return an access token using authorization code grant.
scope required string “+” separated list of scopes.
state optional string Your unique token, generated by your application. This is an OAuth 2.0 opaque value, used to avoid CSRF attacks. This value is echoed back in the response. We strongly recommend you use this.
  1. If the user authorizes your application, the user is redirected to your redirect URI. The authorization code will be returned along the redirect URI.
https://<your_registered_redirect_URI>/?code=<authorization code>
1
  1. On your server, get an access token by making this request:

Request Format:

curl --location --request
POST 'https://open-api.trovo.live/openplatform/exchangetoken' \
--header 'Accept: application/json' \
--header 'client-id: <your_client_id>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_secret": <your_client_secret>,
    "grant_type": "authorization_code",
    "code": <code>,
    "redirect_uri": <redirect_uri>
}'
1
2
3
4
5
6
7
8
9
10
11

If you don’t have the Client Secret, please contact: developer@trovo.live.

Response Sample:

{
    "access_token": "a0e1b1ee318088304eb542c86d3c2360",
    "token_type": "bearer",
    "expires_in": "14400",
    "refresh_token": "af6f6d8b601ba6b91367c5ce35b11e1f"
}
1
2
3
4
5
6

# 4. Authentication APIs

# 4.1. Validate Access Token

When validating each of your requests, submit a request to the validation endpoint (https://open-api.trovo.live/openplatform/validate), with your OAuth token in the header.

Requested Scope: None.

Request Access Token: Yes.

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <your_client_id>' \
-H 'Authorization: OAuth <access_token>' \
-X GET 'https://open-api.trovo.live/openplatform/validate'
1
2
3
4
5

Response Sample:

{
    "uid": "100000031",
    "client_ID": "<your_client_id>",
    "nick_name": "hectorDeng",
    "scopes": [
        "channel_details_self",
        "channel_update_self",
        "user_details_self"
    ],
    "expire_ts": "1587281377"
}
1
2
3
4
5
6
7
8
9
10
11

# 4.2. Revoke Access Token

To clean up previously obtained access tokens. Its implementation follows the OAuth standard.

Requested Scope: None.

Request Access Token: Yes.

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <your_client_id>' \
-H 'Authorization: OAuth <access_token>'\
-d '{"access_token":"<access_token>"}' \
-X POST 'https://open-api.trovo.live/openplatform/revoke'
1
2
3
4
5
6

Response Sample:

{
    "empty": ""
}
1
2
3

# 4.3. Refresh Access Token

You may refresh the access token by making this request. A refresh token can hold a maximum of 50 access tokens at the same time. If exceeded, you should wait for the old access tokens to expire before you can refresh again.

Recently update: the new segment "refresh_token" is added in the response. This means you can always get a new refresh_token with 30 days lifetime from your old effective refresh_token before it's going to expire. Also, if you don't care about the new refresh_token, the old one still works before it expires in 30 days.

Request Format:

curl --location --request
POST 'https://open-api.trovo.live/openplatform/refreshtoken' \
--header 'Accept: application/json' \
--header 'client-id: <client_id>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_secret": <client_secret>,
    "grant_type": "refresh_token",
    "refresh_token": <refresh_token>
}'
1
2
3
4
5
6
7
8
9
10

Response Sample:

{
    "access_token": "11ab51c039344c69cb1e03bc2c0d2625",
    "token_type": "bearer",
    "expires_in": "14400",
    "refresh_token": "d53ca510b054023ec0fee3f078a7a813"
}
1
2
3
4
5
6

# 5. Main APIs

# 5.1. Get Game Categories

Retrieves the latest list of categories/games. The order matches the current categories order in Trovo, which is sorted based on the popularity of the categories.

Requested Scope: None.

Request Access Token: No.

Response Fields:

Name Description
category_info List of categories that matches or blur matches the query entered.
id Id of the category.
name Full name of the category.
short_name Short name of the category.
icon_url URL of the category image.
desc Description of the category.

Request format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>' \
-X GET 'https://open-api.trovo.live/openplatform/categorys/top'
1
2
3
4

Sample response:

{
    "category_info": [
        {
            "id": "10023",
            "name": "PUBG Mobile",
            "short_name": "PUBGM",
            "icon_url": "https://static.trovo.live/imgupload/category/20200213_uztn6itp6uGame.png",
            "desc": "Developed by Tencent Games, PUBG MOBILE is the Mobile-first adaptation of PLAYERUNKOWN's BATTLEGROUNDS..."
        },
        {
            "id": "10028",
            "name": "Call of Duty Mobile",
            "short_name": "CODM",
            "icon_url": "https://static.trovo.live/imgupload/category/20200313_lyzr1mfu7abMobile.png",
            "desc": "Call of Duty: Mobile is a free-to-play first-person shooter developed by TiMi Studios and published by Activision for Android and iOS."
        },
      ...
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 5.2. Search Categories

Search for game categories by entering keywords and retrieving a list of matching categories/games.

Keywords are used to match with the full names and the short names of categories. Both exact matching and blurr matching are applied.

Requested Scope: None.

Request Access Token: No.

Request Parameters:

Name Required Type Description
query required string Query/keyword used for searching categories.
limit optional integer Maximum number of objects to return. Maximum: 100. Default: 20.

Response Fields:

Name Description
category_info List of categories that matches or blur matches the query entered.
id Id of the category.
name Full name of the category.
short_name Short name of the category.
icon_url URL of the category image.
desc Description of the category.
has_more If true, it means more matching results are found than the current limit number. Increase the limit to see more results.

Request format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client-id>' \
-d '{"query":"<query>","limit":<limit>}' \
-X POST 'https://open-api.trovo.live/openplatform/searchcategory'
1
2
3
4
5

Sample request:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client-id>' \
-d '{"query":"le","limit":3}' \
-X POST 'https://open-api.trovo.live/openplatform/searchcategory'
1
2
3
4
5

Sample response:

{
    "category_info": [
        {
            "id": "1106467070",
            "name": "PUBG MOBILE",
            "short_name": "PUBG MOBILE",
            "icon_url": "https://puui.qpic.cn/vupload/0/20191218_j7j5hhxc0e/0",
            "desc": "PUBG MOBILE"
        },
        {
            "id": "2000027",
            "name": "Apex Legends",
            "short_name": "Apex",
            "icon_url": "https://static.trovo.live/imgupload/category/20200605_6t0x4cycwitapp.jpg",
            "desc": "Apex"
        },
        {
            "id": "2000017",
            "name": "PLAYERUNKNOWN'S BATTLEGROUNDS",
            "short_name": "PUBG",
            "icon_url": "https://static.trovo.live/imgUpload/game_management.game/20191225_43q4c5nohjbBATTLEGROUNDS.png",
            "desc": "PLAYERUNKNOWN'S BATTLEGROUNDS"
        }
    ],
    "has_more": true
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 5.3. Get top channels

Retrieves information for all live channels. Channels are returned in order or popularity in descending order. The response contains a list of channel information and pagination fields containing information required to query for more streams. Note: Across multiple pages of results, there may be duplicate or missing streams, as viewers join and leave streams.The top channels list refreshes every minute.

Requested Scope: None.

Request Access Token: No.

Request Parameters:

Name Required Type Description
limit Required integer Maximum number of objects to return. Maximum: 100. Default: 20.
after Optional boolean After = true indicates cursor for forward pagination, false means backward: tells the server where to start fetching the next set of results, in a multi-page response.
token Optional string Required for pagination. The token here is from the pagination response field of a prior query.
cursor Optional integer Required for pagination. Indicates the current page the data is on. The cursor value specified here is from the pagination response field of a prior query.
category_id Optional string Returns streams broadcasting a specified game ID.

Response Fields:

Name Description
channel_id The unique ID of the channel.
streamer_user_id The ID of the user owning the channel (same as channel id).
channel_url The name and url of the channel.
is_live Indicates if the channel is streaming.
title The title of the channel.
audi_type The target audience of the channel.
current_viewers Number of current viewers.
num_followers Number of followers of the channel.
category_name Readable category name.
categroy_id Id of the category.
language_code ISO 2 letter language code.
thumbnail Url of the current stream thumbnail.
profile_pic Url of the streamers profile picture.
nick_name Display name of the owner of the channel.
stream_started_at Start time of the current stream.
chatters_count Number of chatters in the current minute.
video_resolution Video resolution of the current stream.
total_page The total number of pages of this multi-page response.
token The token identifies the corresponding multi-page response.
cursor The current page number.
started_at return the latest streaming start time of a given channel.
ended_at return the latest streaming end time of a given channel.

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID:  <client_id>'  \
-d '{"limit":<limit>,"after":<after>,"token":"<token>","cursor":<cursor>,"category_id":"<category_id>"}' \
-X POST 'https://open-api.trovo.live/openplatform/gettopchannels'
1
2
3
4
5

a. First request for top channels:

First time requesting getChannel, no token or cursor needs to be passed in.

The response will return the token, total_page and cursor for pagination.

Request Sample:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>'  \
-d '{"limit":2,"after":true,"token":"","cursor":0,"category_id":""}' \
-X POST 'https://open-api.trovo.live/openplatform/gettopchannels'
1
2
3
4
5

Response Sample:

{
    "top_channels_lists": [
        {
            "channel_id": "100025358",
            "streamer_user_id": "100025358",
            "channel_url": "https://trovo.live/DanniLGaming",
            "is_live": true,
            "title": "En busca del top 100, llegare?! Rumbo a los 10K",
            "audi_type": "CHANNEL_AUDIENCE_TYPE_TEEN",
            "current_viewers": 270,
            "num_followers": 157,
            "category_name": "Call of Duty: Mobile",
            "language_code": "EN",
            "thumbnail": "https://...jpg",
            "nick_name": "DanniLGaming",
            "stream_started_at": "1609907451",
            "category_id": "10028",
            "video_resolution": "720P",
            "channel_country": "",
            "profile_pic": "https://headicon.trovo.live/user/bzcpmbiaaaaaaeaimtwudjy3cy.jpeg?t=1",
            "subscriber_num": 157,
            "username": "DanniLGaming",
            "social_links": [
                {
                    "type": "Discord",
                    "url": "https://discord.gg/PPJRbP"
                }
            ]
        },
        { ...
        }
    ],
    "total_page": 303,
    "token": "xxxxxxxxxxxx=",
    "cursor": 1
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

b.Pagination request

For paginating to the next page of the previous response. Needs to pass in the “token”, “after” and “cursor” obtained from the previous response.

Request Sample:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>'  \
-d '{"limit":2,"after":true,"token":"<token_from_previous_response>","cursor":1,"category_id":""}' \
-X POST 'https://open-api.trovo.live/openplatform/gettopchannels'
1
2
3
4
5

Response Sample:

{
    "top_channels_lists": [
        {
            "channel_id": "100013104",
            "streamer_user_id": "100013104",
            "channel_url": "https://trovo.live/Rebalo",
            "is_live": true,
            "title": "#1 Ranked Player",
            "audi_type": "CHANNEL_AUDIENCE_TYPE_TEEN",
            "current_viewers": 158,
            "num_followers": 366,
            "category_name": "Call of Duty: Mobile",
            "language_code": "EN",
            "thumbnail": "https://...jpg",
            "nick_name": "Rebalo",
            "stream_started_at": "1609905603",
            "category_id": "10028",
            "video_resolution": "480P",
            "channel_country": "",
            "profile_pic": "https://headicon.trovo.live/user/gakpmbiaaaaabujxrpoucrzbcy.png?t=7",
            "subscriber_num": 366,
            "username": "Rebalo",
            "social_links": [
                {
                    "type": "Discord",
                    "url": "https://discord.gg/Rdypp34U2z"
                },
                {
                    "type": "Youtube",
                    "url": "https://www.youtube.com/channel/UCe_xAG6hz6tfSWE6iqX3dog"
                }
            ],
            "started_at":"1684341848",
            "ended_at":"1684341798"
        },
        { ...
        }
    ],
    "total_page": 303,
    "token": "xxxxxxxxxxxx=",
    "cursor": 2
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# 5.4. Get Users (get channel id)

Gets a user’s channel id, user id, and nickname, by username.

Requested Scope: None.

Request Access Token: No.

Request Parameters:

Name Description
users A list of valid usernames that you want to request for. Not case sensitive. Sample: ["userA","userB"]Note: Username is the last part of the streamer’s channel url. For example, for the channel “https://trovo.live/IrenePro (opens new window)” the streamers username is “IrenePro”. The name displayed in chats is the user’s nickname which might be different from the nickname.

Response Fields:

Name Description
total The total number of user info requested and returned.
users The list of user info for each username requested.
user_id Unique id of a user.
channel_id Unique id of a channel.
username The username of a user. Unique across Trovo platform. Username is the last part of the streamer’s channel url.
nickname The display name of a user, displayed in chats, channels and all across Trovo. This could be different from username.

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>' \
-d '{"user":["<usernameA>","<usernameB>"]}' \
-X POST 'https://open-api.trovo.live/openplatform/getusers'
1
2
3
4
5

Request Sample:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>' \
-d '{"user":["hectordeng","leafinsummer"]}' \
-X POST 'https://open-api.trovo.live/openplatform/getusers'
1
2
3
4
5

Response Sample:

{
    "total": 2,
    "users": [
        {
            "user_id": "100000031",
            "username": "hectordeng",
            "nickname": "hectordeng",
            "channel_id": "100000031"
        },
        {
            "user_id": "100000021",
            "username": "leafinsummer",
            "nickname": "leafinsummer",
            "channel_id": "100000021"
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 5.5. Get Channel Info by ID

Fetch a channel’s information by channel ID. You may fetch any channel’s general info using this API call.

Requested scope: None.

Request Access Token: No.

Request Parameters:

Name Required Type Description
channel_id Optional integer Channel id indicating which channel you are requesting.
username Optional string user name of user. (If you fill in username and channel_id at the same time, it should be based on channel_id)

Response Fields:

Name Description
is_live If the channel is currently live streaming. The top channel list is captured for all the live channels. However, channel info is updated in real time. So the channel could go offline when you paginate.
category_id The id of the game category.
category_name Text name of the category.
live_title Current title of the channel.
audi_type Audience type. One of the three values:“CHANNEL_AUDIENCE_TYPE_FAMILYFRIENDLY”,“CHANNEL_AUDIENCE_TYPE_TEEN”,“CHANNEL_AUDIENCE_TYPE_EIGHTEENPLUS”
language_code Language of the channel in in ISO 2 (2 letter language code)
thumbnail URL of the thumbnail. Empty thumbnail means the thumbnail from the previous stream has expired.
current_viewers Number of current viewers
followers Number of followers
streamer_info Profile information of the streamer
profile_pic Url of the streamer’s profile picture
channel_url URL of the channel
created_at Timestamp of the streamer creation time
subscriber_num Count of subscribers
username Username of the channel’s streamer. Also the last part of the channel url.
social_links Social media links of the streamer. Sample: {"type": "Instagram", "url": "https://www.instagram.com/iwang88/"}
started_at return the latest streaming start time of a given channel.
ended_at return the latest streaming end time of a given channel.

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>' \
-d'{"channel_id":<channel_id>}' \
-X POST 'https://open-api.trovo.live/openplatform/channels/id'

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>' \
-d'{"username":<user_name>}' \
-X POST 'https://open-api.trovo.live/openplatform/channels/id'
1
2
3
4
5
6
7
8
9
10
11

Response Sample:

{
    "is_live": false,
    "category_id": "10672",
    "category_name": "Genshin Impact",
    "live_title": "Genshin impact with leafinsummer",
    "audi_type": "CHANNEL_AUDIENCE_TYPE_FAMILYFRIENDLY",
    "language_code": "EN",
    "thumbnail": "",
    "current_viewers": 0,
    "followers": 27,
    "streamer_info": "Hello this is leafinsummer!",
    "profile_pic": "https://headicon.trovo.live/user/cxq7kbiaaaaabd5cniezh3x5cu.jpeg?t=2",
    "channel_url": "https://trovo.live/leafinsummer",
    "created_at": "1584341848",
    "subscriber_num": 1,
    "username": "leafinsummer",
    "social_links": [
        {
            "type": "Instagram",
            "url": "https://www.instagram.com/iwang88/"
        },
        {
            "type": "Youtube",
            "url": "https://www.youtube.com/channel/UCiaqYQXdhAhEd0P79Lsz6Sg"
        }
    ],
    "started_at":"1684341848",
    "ended_at":"1684341798"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 5.6. Read Channel Info with Stream Key

Gets the specific user’s channel information, including the stream key.

Requested scope: channel_details_self

Request Access Token: Yes.

Response field (Aside from the same fields from getChannelInfoByID):

Name Description
stream_key The user’s stream key. (Stream key is sensitive information for each streamer. Please keep the private and make good use of it.)

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <your_client_id>' \
-H 'Authorization: OAuth <access_token>' \
-X GET 'https://open-api.trovo.live/openplatform/channel'
1
2
3
4
5

Response Sample:

{
    "uid": "100000021",
    "channel_id": "100000021",
    "is_live": false,
    "category_id": "10672",
    "category_name": "Genshin Impact",
    "live_title": "Genshin impact with leafinsummer",
    "stream_key": "live/xxxxxxxxxxxxxxxxxxx",
    "audi_type": "CHANNEL_AUDIENCE_TYPE_FAMILYFRIENDLY",
    "language_code": "EN",
    "thumbnail": "",
    "current_viewers": 0,
    "followers": 27,
    "streamer_info": "Hello",
    "profile_pic": "https://headicon.trovo.live/user/cxq7kbiaaaaabd5cniezh3x5cu.jpeg?t=2",
    "channel_url": "https://trovo.live/leafinsummer",
    "created_at": "1584341848",
    "subscriber_num": 1,
    "username": "leafinsummer",
    "social_links": [
        {
            "type": "Instagram",
            "url": "https://www.instagram.com/iwang88/"
        },
        {
            "type": "Youtube",
            "url": "https://www.youtube.com/channel/UCiaqYQXdhAhEd0P79Lsz6Sg"
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 5.7. Edit Channel Information

Allows you to update the user’s channel settings, including title, category, language, audience type. You may update only part of the info.

Requested scope: channel_update_self

Request Access Token: Yes.

Request Parameters:

Name Required Type Description
channel_id Required int ID of the channel
live_title Optional string Name of user’s channel
category Optional string Represent which game is the user playing in his channel. (e.g."category_id":"10023")
language_code Optional string 2 character language ISO 2 code, see standard: https://www.sitepoint.com/iso-2-letter-language-codes/
audi_type Optional string 3 options representing age range All/13+/18+. (See section below)

Audience Type Value (audi_type):

Display Description Value (String)
All CHANNEL_AUDIENCE_TYPE_FAMILYFRIENDLY
13+ CHANNEL_AUDIENCE_TYPE_TEEN
18+ CHANNEL_AUDIENCE_TYPE_EIGHTEENPLUS

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: '<client_id>'\
-H 'Authorization: OAuth <access_token>' \
-d '{"channel_id":<channel_id>,"live_title":"<live_title>","language_code":"<language_code>","audi_type":"<audi_type>"}' \
-X POST 'https://open-api.trovo.live/openplatform/channels/update'
1
2
3
4
5
6

Request Sample:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: xxxxxxxxx' \
-H 'Authorization: OAuth <access_token>' \
-d '{"channel_id":100000031,"live_title":"ABC Germany","category_id":"10023","language_code":"IT","audi_type":"CHANNEL_AUDIENCE_TYPE_FAMILYFRIENDLY"}' \
-X POST 'https://open-api.trovo.live/openplatform/channels/update'
1
2
3
4
5
6

Response Sample:

{
    "empty": ""
}
1
2
3

# 5.8. Get User Info

Retrieves the user info including username, nickname and email address.

Requested scope: user_details_self

Request Access Token: Yes.

Response Fields:

Name Description
userId User ID
userName Username
nickName Display name of the user
email Email address of the user. Note: not every user binds their email address to Trovo account.
profilePic URL of the user’s profile picture
info Profile information of the user
channeId Channel id of the user, same value as user id.

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>' \
-H 'Authorization: OAuth <access_token>' \
-X GET 'https://open-api.trovo.live/openplatform/getuserinfo'
1
2
3
4
5

Response Sample:

{
    "userId": "100000021",
    "userName": "leafinsummer",
    "nickName": "leafinsummer",
    "email": "lxxxxxxxxx@gmail.com",
    "profilePic": "https://headicon.trovo.live/user/cxq7kbiaaaaabd5cniezh3x5cu.jpeg?t=2",
    "info": "Hello this is leafinsummer on Trovo!",
    "channelId": "100000021"
}
1
2
3
4
5
6
7
8
9

# 5.9. Get Subscribers

Gets the subscribers list of a channel.

Requested Scope: channel_subscriptions

Request Access Token: Yes.

Request Parameters:

Name Description
channelID Channel ID
limit Maximum number of objects to return. Default: 25. Maximum: 100.
offset Object offset for pagination of results. Default: 0.
direction Sorting direction. Valid values: asc, desc. Default: asc (oldest first).

Response Fields:

Name Description
total Total number of subscribers
subscriptions An array of subscribers’ information.
user User info for the subscriber, including user id, username, display name, profile picture, and user creation timestamp.
sub_created_at Timestamp when the user subscribed to the channel.
sub_lv Subscription level
sub_tier Subscription tier

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: < clientID >' \
-H 'Authorization: OAuth < access_token >' \
-X GET 'https://open-api.trovo.live/openplatform/channels/{channelID}/subscriptions?limit={limit}&offset={offset}&direction={direction}'
1
2
3
4
5

Request Sample:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <your_client_id> \
-H 'Authorization: OAuth <access_token> \
-X GET 'https://open-api.trovo.live/openplatform/channels/100000021/subscriptions?limit=100&offset=0&direction=asc'
1
2
3
4
5

Response Sample:

{
    "total": 1,
    "subscriptions": [
        {
            "user": {
                "user_id": "100000037",
                "username": "leaf",
                "display_name": "leaf",
                "profile_pic": "https://headicon.trovo.live/user/exq7kbiaaaaaafch2bzqsjakcy.jpeg?t=3",
                "created_at": "1584342605"
            },
            "sub_created_at": 1609902115,
            "sub_lv": "L1",
            "sub_tier": "1"
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 5.10. Get Emotes

Get platform-level emoticons info and custom emoticons info.

Requested scope: None.

Request Access Token: No.

Request Parameters:

Name Required Type Description
emote_type Optional int Get the kind of emotes you want. Sample:emote_type = 0 : Get platform-level emoticons and custom emoticons corresponding to channel IDs;emote_type = 1 : Get the custom emoji corresponding to the channel IDs;emote_type = 2 : Get platform-level emoticons.
channel_id Optional int A list of valid channel IDs you want to request for.Sample:[100000253,10231]

Response Fields:

Name Description
customizedEmotes Custom emoji corresponding to channel IDs.
eventEmotes Platform-level limited emoticons (active emoticons).
globalEmotes Platform-level unrestricted emoticons.
channel_id Unique id of a channel.
name Name of emote.
description Description of emote.
url URL of emote.
status Emoticon available status.
activity_name Name of platform-level limited emoticons activity.
gifp Gifp URL of emote.
webp Webp URL of emote.
update_time Update time of emote.

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>' \
-d '{"emote_type":0/1/2,"channel_id":[channel_idA,channel_idB]}' \
-X POST 'https://open-api.trovo.live/openplatform/getemotes'
1
2
3
4
5

Request Sample:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>' \
-d '{"emote_type":0,"channel_id":[100000253,10231]}' \
-X POST 'https://open-api.trovo.live/openplatform/getemotes'
1
2
3
4
5

Response Sample:

{
    "channels": {
        "customizedEmotes": {
            "channel": [
                {
                    "channel_id": "100000253",
                    "emotes": [
                        {
                            "name": "sub_ggggg",
                            "description": "",
                            "url": "https://test-headicon.trovo.live/file/custom/100000253/7xq7kbiaaaaaaemyj3yfn5rxcy.",
                            "status": "CustomEmoteStatusEnable"
                        }
                    ]
                },
                {
                    "channel_id": "10231",
                    "emotes": [
                        {
                            "name": "sub_holy",
                            "description": "",
                            "url": "https://test-headicon.trovo.live/file/custom/10231/64tqaaaaaaaabeetvm27rjrxcy.",
                            "status": "CustomEmoteStatusEnable"
                        }
                    ]
                }
            ]
        },
        "eventEmotes": [
            {
                "activity_name": "Valentine Hype",
                "name": "3roses",
                "description": "3Roses",
                "gifp": "https://img.trovo.live/test/emotes/3roses.webp",
                "status": "1",
                "update_time": "1612335774",
                "url": "https://img.trovo.live/test/emotes/3roses.png",
                "webp": "https://img.trovo.live/test/emotes/3roses.gif"
            }
        ],
        "globalEmotes": [
            {
                "name": "Cupcake!",
                "description": "Cupcake!",
                "gifp": "https://img.trovo.live/test/emotes/Cupcake!.gif",
                "status": "1",
                "url": "https://img.trovo.live/test/emotes/Cupcake!.png",
                "webp": "https://img.trovo.live/test/emotes/Cupcake!.webp"
            }
        ]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

# 5.11. Get channel viewers

Get channel current online logined viewers list.

Requested Scope: None.

Request Access Token: No.

Request Parameters:

Name Required Type Description
channel_id Required integer Channel id indicating which channel you are requesting.
limit Optional integer Maximum number of objects to return. Maximum: 100000. Default: 100000. Minimum: 20.
cursor Optional integer Required for pagination. The cursor value specified here is from the pagination response field of a prior query.

Response Fields:

Name Description
live_title The channel's title.
total The channel's total login users.
nickname The channel's streamer nickname.
chatters An map of online users nickname group by role type.
custom_roles An map of online users nickname group by custome role type.
roles Roles type include: moderators, editors, supermods, subscribers,followers,admins, VIPS, wardens, ace, aceplus.

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>' \
-d '{"limit":0,"cursor":0}' \
-X POST 'https://open-api.trovo.live/openplatform//openplatform/channels/{channel_id}/viewers'
1
2
3
4
5

Response Sample:

{
    "live_title": "ray's channel",
    "total": "1",
    "nickname": "ray",
    "chatters": {
        "VIPS": {
            "viewers": []
        },
        "ace": {
            "viewers": []
        },
        "aceplus": {
            "viewers": []
        },
        "admins": {
            "viewers": []
        },
        "all": {
            "viewers": [
                "reynold1111111111111111111111111111111111111111111"
            ]
        },
        "creators": {
            "viewers": []
        },
        "editors": {
            "viewers": []
        },
        "followers": {
            "viewers": [
                "reynold1111111111111111111111111111111111111111111"
            ]
        },
        "moderators": {
            "viewers": [
                "reynold1111111111111111111111111111111111111111111"
            ]
        },
        "subscribers": {
            "viewers": [
                "reynold1111111111111111111111111111111111111111111"
            ]
        },
        "supermods": {
            "viewers": []
        },
        "wardens": {
            "viewers": [
                "reynold1111111111111111111111111111111111111111111"
            ]
        }
    },
    "custome_roles": {}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

# 5.12. Get channel followers

Get channel followers list.

Requested Scope: None.

Request Access Token: No.

Request Parameters:

Name Required Type Description
channel_id Required integer Channel id indicating which channel you are requesting.
limit Optional integer Maximum number of objects to return. Maximum: 100. Default: 20.
cursor Optional integer Required for pagination. The cursor value specified here is from the pagination response field of a prior query.
direction Optional string Sorting direction. Valid values: asc, desc. Default: asc (oldest first).

Response Fields:

Name Description
total Number of followers of the channel.
follower An array of followers’ information.
user_id Unique id of a user.
nickname The display name of a user, displayed in chats, channels and all across Trovo. This could be different from username.
profile_pic User's profile picture
followed_at Return the following time
total_page The total number of pages of this multi-page response.
cursor The current page number.

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>' \
-d '{"limit":5,"cursor":0}' \
-X POST 'https://open-api.trovo.live/openplatform//openplatform/channels/{channel_id}/followers'
1
2
3
4
5

Response Sample:

{
    "total": "9",
    "follower": [
        {
            "user_id": "100000242",
            "nickname": "games",
            "profile_pic": "https://headicon-1300619292.cos.ap-hongkong.myqcloud.com/user/6lq7kbiaaaaabqcafjjg4yxzcu.jpeg",
            "followed_at": "2021-08-03 02:21:37"
        },
        {
            "user_id": "100000208",
            "nickname": "Streamer",
            "profile_pic": "https://test-headicon.trovo.live/user/2dq7kbiaaaaaagj7bcvo6mp3cu.jpeg?t=5",
            "followed_at": "2021-08-03 02:22:08"
        },
        {
            "user_id": "100000240",
            "nickname": "patrickgotest",
            "profile_pic": "https://test-headicon.trovo.live/user/6dq7kbiaaaaabin5ucuebxizcy.jpeg?t=12",
            "followed_at": "2021-08-03 08:14:01"
        },
        {
            "user_id": "100000214",
            "nickname": "keemanyeung",
            "profile_pic": "https://test-headicon.trovo.live/user/23q7kbiaaaaaas5l2odkckx7cu.png?t=25",
            "followed_at": "2021-08-04 06:50:09"
        },
        {
            "user_id": "10831",
            "nickname": "yajanel",
            "profile_pic": "https://test-headicon.trovo.live/default/2.png",
            "followed_at": "2021-08-19 07:26:53"
        }
    ],
    "total_page": 2,
    "cursor": 5
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# 5.13 Get Live Stream Urls

Get live stream m3u8 urls to play live stream in player, access limited to specific clients that are in cooperation with Trovo. Please add the referer header "http://openplatform.trovo.live" when using the url Clients without permission get void return.

Requested Scope: None.

Request Access Token: No.

Request Parameters:

Name Required Type Description
channel_id Required integer Channel id indicating which channel you are requesting.

Response Fields:

Name Description
Stream_urls The m3u8 urls of the stream. Resolution (480P, 720P and 1080P) will be returned with different urls, depending on the stream's original resolution and clients' permissions.
desc The resolution of above given url

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: '<client_id>'\
-d '{"channel_id":<channel_id>}' \
-X POST 'https://open-api.trovo.live/openplatform/livestreamurl'
1
2
3
4
5

Response Sample:

{
 "stream_urls": [
     {
         "play_url": "http://liveplay.trovo.live/live/sampleurl",
         "desc": "480P",
     }
   ]
}
1
2
3
4
5
6
7
8

# 6. Chat APIs - send and delete chats

# 6.1 Send Chat to My Channel

Sends chat messages to my channel as myself. Both the target channel and sender is defined by the access token passed in.

Requested Scope: chat_send_self

Request Access Token: Yes

Request Parameters:

Name Description
content The chat message to send.

Request format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: < your_client_id >' \
-H 'Authorization: OAuth < access_token >' \
-d '{"content": "< chat_content_string >"}' \
-X POST 'https://open-api.trovo.live/openplatform/chat/send'
1
2
3
4
5
6

Response - success:

{}
1

# 6.2 Send Chat to a Selected Channel

Sends chat messages to other channels. To send a message as sender (user A) to channel (owned by user B), the application needs to get scopes “chat_send_self” of user A, and “send_to_my_channel”of user B. Usually, it’s used by anchor(user B) for sending greetings to someone who enters into the channel.

Requested Scope: chat_send_self (Of the sender), send_to_my_channel (Of target channel).

Request Access Token: Yes

Request Parameters:

Name Description
content The chat message to send.
channel_id Channel id of the targeting channel.

Request format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: < your_client_id >' \
-H 'Authorization: OAuth < access_token_of_the_sender >' \
-d '{"content": "< chat_content_string >", "channel_id": < target_channel_id >}' \
-X POST 'https://open-api.trovo.live/openplatform/chat/send'
1
2
3
4
5
6

Response - success:

{}
1

# 6.3. Delete a Message

Deletes a message. The operator needs to have sufficient permission to delete the message from the sender. For example, streamers can delete chat messages sent from viewers or mods, but mods cannot delete messages from streamers.

Requested Scope: manage_messages

Request Access Token: Yes.

Request URL Parameters:

Name Required Description
channelID required The channel id where the message to be deleted is in.
messageID required The message ID of the message to be deleted.
uID required The user ID of the sender of the message. This id is required for checking whether the operator has the permission to delete messages from the sender. If messageID and uID does not match, message deletion will fail.

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID:  < your_client_id >'  \
-H 'Authorization: OAuth < access_token >' \
-X DELETE 'https://open-api.trovo.live/openplatform/channels/{channelID}/messages/{messageID}/users/{uID}'
1
2
3
4
5

Response & error:

Response Msg Description
Success Messages will not show up in Trovo chat box. Could be (1) the message was deleted successfully or (2) the message does not exist in the chat history, as expired chat messages will be removed from the chat history automatically.
No permission to delete this message Failed to delete message due to lack of permission to delete messages from the sender.
Delete failed. (System error / message id does not match sender uid) Failed to delete message due to system error, or the message id does not match the sender uid.

# 6.4. Perform chat commands

Perform Trovo official chat commands through API.

Requested Scope: manage_messages

Request Access Token: Yes.

Request Parameters:

Name Description
command Command to be performed. No slash at the beginning. Sample: “settitle xxx”, “mod @xxx”, “ban xxx”
channelID Channel id indicating which channel to perform this command in.

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: < clientID >' \
-H 'Authorization: OAuth < access_token >' \
-d '{"command":"< command >", "channel_id": <channelID>}' \
-X POST 'https://open-api.trovo.live/openplatform/channels/command'
1
2
3
4
5
6

Request Sample:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: < your_client_id > \
-H 'Authorization: OAuth < access_token > \
-d '{"command":"mod leafinsummer", "channel_id": 12345678}' \
-X POST 'https://open-api.trovo.live/openplatform/channels/command'
1
2
3
4
5
6

Response Fields:

Name Description
is_success Whether the command is processed successfully. If false, there could be various reasons, like invalid command entered, no permission to perform, or invalid username entered, etc.
display_msg If the command failed to perform, the display message shows the detailed reason. This is the same warning message displayed to user in Trovo chat box for a failed command operation.

Response Sample - success:

{
    "is_success": true,
    "display_msg": ""
}
1
2
3
4

Response Sample - 200 but failed to perform the command (detailed message shown in display_msg):

{
    "is_success": false,
    "display_msg": "Unrecognized command: /xxx"
}
1
2
3
4

# 7. Rate Limit

Trovo’s API rate limits requests in order to prevent abuse of the service. This rate limit is shared by all clients using the same client ID. When an application is first registered, your application will get a rate limit of 1200 requests per minute. This means you can send up to 1200 requests every minute from the same client id.

You can always request for a higher rate limit for your client id by emailing to developer@trovo.live providing your application and the reason for the increase.

# Rate Limit in Response Header Format

These header field names are case-insensitive, the parsing rule should take care of this.

Rate Limit Header Examples:

x-ratelimit-limit: 1200
x-ratelimit-remaining: 1198
x-ratelimit-reset: 1607658000
1
2
3
Header Description
x-ratelimit-limit The current rate limit for the client id. The total number of requests can be made in the current time window (60 sec).
x-ratelimit-remaining The number of requests remaining in this current time window.
x-ratelimit-reset Unix epoch timestamp at which the rate limit will be reset.

If rate limit exceeded:

{
    "status": 11706,
    "error": "Internal Server Error",
    "message": "API rate limit exceeded. (You may apply for rate limit increase by contacting Trovo staff)"
}
1
2
3
4
5

# 8. Read chat messages through websocket

For receiving and sending chat messages. Please read our developer doc about chat service.

Trovo Chat Service (opens new window)

# 9. CORS

If you are making API calls from the client side, you may come across CORS issues. Your domain needs to be whitelisted in Trovo in order to do CORS calls.

In addition, please add origin in the header when you are making cross-site calls.

Origin: "https://xxxxxx"
1

# 10. Scopes

Scope Description
user_details_self View your email address and user profiles.
channel_details_self View your channel details. Including Stream Key.
channel_update_self Update your channel settings
channel_subscriptions Get your subscribers list.
chat_send_self Send chat messages on behalf of myself.
send_to_my_channel Send chat messages to my channel.
manage_messages Perform chat commands and delete chat messages.

# 11. Error codes

Status Error Message Description & troubleshooting
-10500 Failed to fetch profile data. Please try again.
-1201 Internal server error. Internal service failed to fetch data. Please try again.
-1000 Internal server error. Try send the request again. In most cases, it is caused by timeout of an internal service.
1002 Invalid parameters. Server received invalid parameters. Please check the params you requested.
1111 Unknown internal server error. Please report to developer@trovo.live Unknown or uncategorized internal server error. Please report to developer@trovo.live
1203 Conflict. Please try again. Please try again.
10505 Invalid user. The user does not exist.
10703 Authorization failed. Please double check your token or the auth status.
10710 Authorization Code doesn't exist or has expired Authorization Code doesn't exist or has expired
10908 Please don't spam. (Check out error code explianation for the this chat rule) To avoid spam, one user cannot send the same message in 30 sec to a channel, or send more than 1 message in 1 sec across all platforms. Streamers, Mods and Admins does not have this limit. Give your chatbot mod access then you will not get this limit.
11000 Invalid category. The category does not exist.
11101 Content conflicts with Trovo moderation rule. The content entered may conflict to Trovo's moderation policy. You may try something else.
11103 Content conflicts with Trovo moderation rule. The content entered may conflict to Trovo's moderation policy. You may try something else.
11400 This account has been blocked due to ${0} ${1}. The user account has been blocked by Trovo. To unblock the user, please contact us at customer@trovo.live
11701 Invalid header. Error in the request header.
11703 Invalid scope Please try again with a valid scope.
11704 Invalid access token. Double the access token you passed in is valid or not.
11706 API rate limit exceeded. (You may apply for rate limit increase by contacting Trovo staff) Rate limit exceeded. You may check the rate limit info in response header to optimize your request. You may also apply for higher rate limit by contacting developer@trovo.live.
11707 No permission to send chats to this channel. Please check if you have obtained the sufficient scope to send chat to this channel
11708 Invalid shard value. (Please make sure total_shard > 0 and 0 <= current_shard < total_shard) Check your parameters for the shard. total_shard > 0 and 0 <= current_shard < total_shard.
11709 No permission to get the sharding token. Please contact us to get whitelisted. Get shard token API is currently open to trusted developers only. You may email developer@trovo.live to get whitelisted.
11710 Authorization Code doesn't exist or has expired Authorization Code doesn't exist or has expired.
11711 Authorization Code has been used Authorization Code has been used.
11712 Refresh token has expired Refresh token has expired.
11713 Invalid refresh token Invalid refresh token.
11714 Access token has expired Access token has expired.
11715 Invalid grant type Invalid grant type.
11716 Invalid Redirect URI Invalid Redirect URI.
11717 Invalid client secret Invalid client secret.
11730 scope not authorized Scope is not authorized by the user.
11718 Access token num limit Access token num is greater than 50, you should wait for the old access token to expire before you can refresh again.
12400 User is banned from chatting in this channel. The user is banned from chatting in this channel. Please contact the streamer/mods to unban the user.
12401 Channel is in slow mode only. Channel is currently in slow mode. Please follow the slow mode rule to chat.
12402 The channel is in follower-only chat mode. The streamer has set the channel to be follower only chat. Please follow the channel to chat.
12905 No permission to send hyperlinks in this channel. Block hyperlink mode on. The user does not have permission to send hyperlinks in this channel. The channel is in block hyperlink mode. Please check the hyperlink mode rules.
12906 Your message was moderated due to conflicts with the channel's moderation settings. Please try again with different content.
20000 Unknown bad request error. Please report to developer@trovo.live Unknown or uncategorized error. Please report to developer@trovo.live.

# 12. Embedding Player and Chatbox

Please refer to this doc:

Trovo Embedded Player and Chats (opens new window)