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

The Trovo APIs use two types of access tokens now,user access tokens and app access token. Some APIs require a user access token, others require an app access token.You could get user access token by getting OAuth Tokens, or get app access token by getting Trovo signature.

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>

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

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.

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

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

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>

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

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.

2. 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>
&state=statedata

3. 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>
}'

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

3.3. Getting App Access Token: Trovo Signature

1. You could use App Access Token by getting Trovo Signature. For offering Trovo signature, you should calculate signatureString by Trovo-Tm (Request timestamp) and client secret first.

   (a).Trovo-Tm (Request timestamp) will be invalid in 3 minutes. You need to request another timestamp for calculating your trovo signatureString after 3 minutes.

   (b).SignatureString is disposable. Everytime you call an API that requires this token, you need to re-apply for the signature.

Parameters	Description
Trovo-Tm	The current request timestamp
Trovo-Signature	App access token

Calculation:

Encoding Format: UTF-8

bodyMD5 = MD5.sum($body)

signatureString = '$urlPath|$rawQuery|$bodyMD5|$Trovo-Tm|$client_secret'

Trovo-Signature = base64.StdEncoding(HMAC-SHA1('$client_secret', '$signatureString'))

Sample:

curl \

-H 'Accept: application/json' \
-H 'Client-ID: f2uc89189f1811gjj19h89c2e91hf891' \
-H 'Trovo-Tm: 1681989114' \
-H 'Trovo-Signature: dlJ3dZvgOOZj8aZBZU9htEe+eBI=' \
-d '{"a": "1"}' \
-X POST 'https://open-api.trovo.live/openplatform/posttest?test=1'

bodyMD5 = MD5.sum($body)
signatureString = '$urlPath|$rawQuery|$bodyMD5|$Trovo-Tm|$client_secret'
Trovo-Signature = base64.StdEncoding(HMAC-SHA1('$client_secret', '$signatureString'))

client_secret = "1njfg11fnb1j1hf1on1nhiodni11niof"
bodyMD5 = MD5.('{"a": "1"}') = 44550aefb0b85d9db968d11e4fdfa6bc
signatureString = '/openplatform/posttest|test=1|44550aefb0b85d9db968d11e4fdfa6bc|1681989114|1njfg11fnb1j1hf1on1nhiodni11niof'
Trovo-Signature = base64.StdEncoding(HMAC-SHA1('1njfg11fnb1j1hf1on1nhiodni11niof', '$signatureString')) = dlJ3dZvgOOZj8aZBZU9htEe+eBI=

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'

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

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'

Response Sample:

{
    "empty": ""
}

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>
}'

Response Sample:

{
    "access_token": "11ab51c039344c69cb1e03bc2c0d2625",
    "token_type": "bearer",
    "expires_in": "14400",
    "refresh_token": "d53ca510b054023ec0fee3f078a7a813"
}

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'

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

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'

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'

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
}

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'

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'

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
}

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'

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
}

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'

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'

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

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'

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

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'

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

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'

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'

Response Sample:

{
    "empty": ""
}

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
channelId	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'

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

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}'

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'

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

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'

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'

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

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/channels/{channel_id}/viewers'

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

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//channels/{channel_id}/followers'

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
}

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'

Response Sample:

{
 "stream_urls": [
     {
         "play_url": "http://liveplay.trovo.live/live/sampleurl",
         "desc": "480P",
     }
   ]
}

5.14 Get Clips Info

Get clips info with channel id, game category, period and clip id, return info of clips that meet all the requirements in multi-page response. Return null if there's no clip meets requirements.
Clip info including: clips numbers, total page, clip id, streamer id, streamer username, streamer nickname, clip title, url, language, thumbnail, category, date, duration, views, likes, number of comments, clip makers' username and nickname.

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.
category_id	Optional	string	The category to search for clips
period	Optional	string	The window of time to search for clips. Valid values: day, week, month, all. Default: week.
clip_id	Optional	string	Unique id of the clip
limit	Optional	integer	Maximum number of objects to return every Maximum: 100. Default: 20
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.
direction	Optional	string	Sorting direction. Valid values: asc, desc. Default: asc(oldest first)

Response Fields:

Name	Description
total_clips	Number of clips to return
clips_info	An array of clips' info
streamer_id	Unique id of streamer
streamer_username	The clip's streamer username
streamer_nickname	The clip's streamer nickname
clip_id	Unique id of the clip
title	Clip title
url	Url of the clip
language	Clip language
thumbnail	Thumbnail url of the clip
category_id	Clip category
sub_only	Only subscribers can watch the clip
made_at	When the clip was made
duration	Duration of the clip (seconds)
views	Clips' views
likes	Clips' likes
comments_number	Number of comments for the clip
maker_username	Clip makers' username
maker_nickname	Clip makers' nickname
total_page Total	number of the pages of this multi-page response
cursor	The current page number

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>' \
-d '{"channel_id":<channel_id>,"category_id":<category_id>,"period":<period>,"clip_id":<clip_id>,"limit":<limit>,"cursor":<cursor>,"direction":<direction>}' \
-X POST 'https://open-api.trovo.live/openplatform/clips'

Response Sample:

{
    "total":30,
    "clips_info": [
        {
            "streamer_id":"1106467070",
            "streamer_username":"ray",
            "streamer_nickname":"ray",
            "clip_id":"Itv-1035_1",
            "title":"Clip title",
            "url":"https://trovo.live/clip/vc-1035_1?ltab=videos",
            "language":"clip language",
            "thumbnail":"thumbnail url",
            "category_id":"game category",
            "sub_only":"true",
            "made_at":"1638292874",
            "duration":360,
            "views":120,
            "likes":12,
            "comments_number":2,
            "maker_username":"Dora",
            "maker_nickname":"Dora"
         },
         {    
            "streamer_id":"1106467071",
            "streamer_username":"ray",
            "streamer_nickname":"ray",
            "clip_id":"Itv-1035_2",
            "title":"Clip title",
            "url":"https://trovo.live/clip/vc-1035_1?ltab=videos",
            "language":"clip language",
            "thumbnail":"thumbnail url",
            "category_id":"game category",
            "sub_only":"false",
            "made_at":"184632939",
            "duration":34,
            "views":200,
            "likes":4,
            "comments_number":1,
            "maker_username":"Dora",
            "maker_nickname":"Dora",
          }
       ],
       "total_page":10,
       "cursor":1
}

5.15 Get Past Streams Info

Get past stream info by channel id, category, period and past stream id, return info of past streams that meet all the requirements in multi-page response. Return null if there's no past stream meets requirements.
Info including: total number of past streams, streamer id, streamer username, streamer nickname, past stream id, past stream title, url, language, thumbnail, category, sub only, start&end time, duration, views, likes, numbers of comments

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.
category_id	Optional	string	The category to search for past stream
period	Optional	string	The window of time to search for past stream. Valid values: day, week, month, all. Default: week.
past_stream_id	Optional	string	Unique id of the past stream
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_paststreams	Total number of past streams returned
paststreams_info	An array of past streams' info
streamer_id	Unique id of streamer
streamer_username	The clip's streamer username
streamer_nickname	The clip's streamer nickname
past_stream_id	Unique id of the past stream
title	Past stream title
url	Url of the past stream
language	Stream language
thumbnail	Thumbnail url of the past stream
category_id	Stream category
sub_only	Only subscribers can watch the clip
duration	Duration of the stream (seconds)
start_at	Past streams' start time
end_at	Past streams' end time
views	Past streams' views (live views+VOD views)
likes	Past streams' likes
comments_number	Number of comments for the past stream
total_page	Total number of the pages of this multi-page response
cursor	The current page number

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: <client_id>' \
-d '{"channel_id":<channel_id>,"category_id":<category_id>,"period":<period>,"past_stream_id":<past_stream_id>,"limit":<limit>,"cursor":<cursor>,"direction":<direction>}' \
-X POST 'https://open-api.trovo.live/openplatform/paststreams'

Response Sample:

{
    "total_pastStreams":30,
    "paststreams_info": [
        {
            "streamer_id":"103847372",
            "streamer_username":"Dora",
            "streamer_nickname":"Dora",
            "past_stream_id":"Itv-1035_3",
            "title":"past stream title",
            "url":"https://trovo.live/video/ltv-1035_3?ltab=videos",
            "language":"stream language",
            "thumbnail":"thumbnail url",
            "category_id":"game category",
            "sub_only":"true",
            "duration":36000,
            "start_at":"153647283",
            "end_at":"1648239474",
            "views":800,
            "likes":202,
            "comments_number":1
         },
         {    
            "streamer_id":"103847372",
            "streamer_username":"Dora",
            "streamer_nickname":"Dora",
            "past_stream_id":"Itv-1035_4",
            "title":"past stream title",
            "url":"https://trovo.live/video/ltv-1035_4?ltab=videos",
            "language":"stream language",
            "thumbnail":"thumbnail url",
            "category_id":"game category",
            "sub_only":"false",
            "duration":1332,
            "start_at":"1638373783",
            "end_at":"16738392937",
            "views":80,
            "likes":2,
            "comments_number":1
          }
       ],
       "total_page":2,
       "cursor":1
}

5.16 Get Drops Entitlement

Gets an organization's list of entitlements that have been granted to target users.

Requested Scope: None

Request Access Token: App access token (see 3.3 Getting Trovo Signature (opens new window)). The client ID in the access token must own the game.

Request Parameters:

Name	Required	Type	Description
startTimestamp	Optional	integer	The timestamp at which the request list start.
limit	Optional	Interger	The maximum number of enetitlements to return per page in the response. The minimum page size is 0 entitlement per page and the maximum is 100. The default is 20.
fulfillmentStatus	Optional	string	The entitlement's fulfillment status. Used to filter the list to only those with the specified status. Possbile value are ALL=0; CLAIMED=1; FULFILLED=2.
endTimestamp	Optional	Interger	The timestamp at which the request list end.
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
data	The list of entitlement.
entitlementID	The only identification of entitlmement id.
rewardTime	The UTC date and time (in RFC3339 format) of when the entitlement was granted.
userID	An ID that identifies the user who was granted the entitlement.
boxID	An ID that identifies the treasure box the user was playing when the reward was entitled.
fulfillmentStatus	THe entitlement's fulfillment status. Possible values are: ALL=0; CLAIMED=1; FULFILLED=2.
total	The total number of this multi-page response.
cursor	The cursor value specified here is from the pagination response field of a prior query.
hasmore	Whether there are remaining list

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: 553e1ea2742b41892a0ecf393e734ab9' \
-H 'Trovo-Tm: 1681989114' \
-H 'Trovo-Signature: z7DO1aUGGQqwdW2o8uI92bCc4fU=' \
-d'{"fulfillmentStatus":1, "startTimestamp": 0, "endTimestamp": 1881981689, "cursor": 0, "limit": 10}' \
-X POST 'https://open-api.trovo.live/openplatform/getdropsentitlements?'

Response Sample:

{
    "items": [
        {
            "entitlementID": "2001",
            "boxID": "384",
            "userID": "11761",
            "fulfillmentStatus": "CLAIM",
            "rewardTime": "1682242009"
        },
        {
            "entitlementID": "3",
            "boxID": "384",
            "userID": "11368",
            "fulfillmentStatus": "CLAIM",
            "rewardTime": "1682406649"
        }
    ],
    "total": "2",
    "cursor": "2",
    "hasMore": false
}

5.17 Update Drops Entitlements

Update the Drop entitlements' fulfillment status that have been granted to target users.

Requested Scope: None

Request Access Token: App access token (see 3.3 Getting Trovo Signature (opens new window)). The client ID in the access token must own the game.

Request Parameters:

Name	Required	Type	Description
entitlementIDs	Optional	String	A list of IDs that identify the entitlements to update.
fulfillmentStatus	Optional	String	The fulfillment status to set the entitlement to. The only values are FULFILLED=2: The developer granted the benefit that the user claimed.

Response Fields:

Name	Description
updateResults	A list that indicates which entitlements were successfully updated and those that weren't。
status	A string that indicates wheter the status of the entitlements in the list were successfully updated. Possbile values are: SUCCESS: The status of the entitlements in the list were successfully updated; UPDATE_FAILED: The update failed. These are considered transient errors and the request should be retried later.
entitlementIDs	The list of entitlements that the status in the status field applies to.

Request Format:

curl \
-H 'Accept: application/json' \
-H 'Client-ID: 553e1ea2742b41892a0ecf393e734ab9' \
-H 'Trovo-Tm: 1681989114' \
-H 'Trovo-Signature: 0ibQ5M0D7rkdbwBB9LT2VcM9Cl8=' \
-d'{"fulfillmentStatus":2, "entitlementIDs": [3001]}' \
-X POST 'https://open-api.trovo.live/openplatform/updatedropsentitlements'

Response Sample:

{
    "updateResults": [
        {
            "entitlementID": "3001",
            "status": "SUCCESS"
        }
    ]
}

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'

Response - success:

{}

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'

Response - success:

{}

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}'

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'

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'

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

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

{
    "is_success": false,
    "display_msg": "Unrecognized command: /xxx"
}

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

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

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"

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
11402	The IP address has been blocked due to ${0}.	The IP address has been blocked by Trovo. To unblock 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.
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.
11730	scope not authorized	Scope is not authorized by the user.
11747	Invalid Header Trovo-Tm	Failed to offer the header or the timestamp is invalid ( over 180s)
11748	Invalid Header TrovoSignature	Failed to offer the header or wrong calculation
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)