Trovo Integration

Connect your Trovo accounts to enable chat bots, channel management, and stream interaction.

Setup

Prerequisites

1. A Trovo application registered at Trovo Developer Portal
2. Configure your OAuth redirect URI: {server.public_url}/v1/integrations/callback/trovo
3. Note your Client ID and Client Secret

Configuration

[server]
# The redirect URI is automatically built from this: {public_url}/v1/integrations/callback/trovo
public_url = "https://your-domain.com"

[integrations.trovo]
client_id = "your_trovo_client_id"
client_secret = "your_trovo_client_secret"

Or via environment variables:

SERVER_PUBLIC_URL=https://your-domain.com
TROVO_INTEGRATION_CLIENT_ID=your_client_id
TROVO_INTEGRATION_CLIENT_SECRET=your_client_secret

Redirect URI

The OAuth redirect URI is automatically constructed from server.public_url: {server.public_url}/v1/integrations/callback/trovo

Make sure to add this exact URL to your Trovo application's OAuth settings.

OAuth Scopes

Channel Scopes

Scopes requested for channel (broadcaster) accounts:

Scope	Description	Required
user_details_self	View email and user profile	Yes
channel_details_self	View channel details + stream key	Yes
channel_update_self	Update channel settings	Yes
channel_subscriptions	Get subscribers list	Yes

Bot Scopes

Scopes requested for bot accounts:

Scope	Description	Required
chat_send_self	Send chat messages	Yes
send_to_my_channel	Send messages to my channel	Yes
manage_messages	Perform chat commands and delete messages	Yes

Chat Integration

External API reference

Heimdall provides the Trovo OAuth integration layer (token storage, refresh, scopes). There is no built-in Trovo bot service yet — the chat and moderation REST/WebSocket samples below document the external Trovo API for your own bot implementation.

WebSocket Connection

Trovo uses WebSocket for real-time chat:

const ws = new WebSocket('wss://open-chat.trovo.live/chat');

// Authentication
ws.send(JSON.stringify({
  type: 'AUTH',
  nonce: generateNonce(),
  data: {
    token: accessToken
  }
}));

// Join channel
ws.send(JSON.stringify({
  type: 'JOIN',
  nonce: generateNonce(),
  data: {
    channel_id: channelId
  }
}));

Message Types

Type	Description
CHAT	Normal chat message
GIFT	Gift subscription
SPELL	Spell (like bits/donations)
WELCOME	User joined chat
FOLLOW	User followed channel

Sending Messages

POST https://open-api.trovo.live/openplatform/chat/send
Authorization: OAuth {access_token}
Client-ID: {client_id}
Content-Type: application/json

{
  "channel_id": "{channel_id}",
  "content": "Hello from the bot!"
}

Rate Limits

Type	Limit
Chat messages	30 messages/minute
API requests	60 requests/minute

Connecting Accounts

Connect Channel Account

1. Go to Admin > Integrations
2. Click "Connect" under Trovo
3. Select "Channel" as the account type
4. Sign in with your Trovo broadcaster account
5. Authorize the requested permissions
6. You'll be redirected back to Heimdall

Connect Bot Account

1. Create or log into your bot's Trovo account
2. Go to Admin > Integrations
3. Click "Connect" under Trovo
4. Select "Bot" as the account type
5. Enter a unique bot identifier
6. Sign in with the bot's Trovo account
7. Authorize the requested permissions

Token Management

Token Lifetime

• Access Token: 2 hours (automatically refreshed)
• Refresh Token: 90 days

Automatic Refresh

Tokens are automatically refreshed before expiry. Trovo refresh tokens expire after 90 days of inactivity.

Token Errors

Error	Cause	Solution
invalid_token	Token expired or revoked	Disconnect and reconnect
invalid_client	Client credentials invalid	Verify configuration
expired_token	Refresh token expired (90 days)	Reconnect integration

Moderation

Timeout User

POST https://open-api.trovo.live/openplatform/channels/{channel_id}/timeout
Authorization: OAuth {access_token}
Client-ID: {client_id}
Content-Type: application/json

{
  "user_id": "{user_id}",
  "duration": 600
}

Ban User

POST https://open-api.trovo.live/openplatform/channels/{channel_id}/ban
Authorization: OAuth {access_token}
Client-ID: {client_id}
Content-Type: application/json

{
  "user_id": "{user_id}",
  "reason": "Rule violation"
}

Delete Message

DELETE https://open-api.trovo.live/openplatform/chat/message/{message_id}
Authorization: OAuth {access_token}
Client-ID: {client_id}

Spells and Gifts

Trovo has unique monetization features:

Spells

Virtual items viewers can send:

• Tracked via chat WebSocket events
• Various types with different values
• Can trigger alerts and bot responses

Subscriptions

Monthly subscriptions with tiers:

• Gift subscriptions supported
• Events sent via WebSocket

Troubleshooting

"invalid_client" error

1. Verify Client ID and Secret
2. Ensure app is approved on Trovo
3. Check environment configuration

Chat connection fails

1. Verify the access token is valid (chat connects with the OAuth token, no dedicated chat scope is required)
2. Check WebSocket URL is correct
3. Ensure proper authentication message format

Bot messages not sending

1. Verify chat_send_self scope authorized
2. Check rate limits
3. Ensure bot is not muted/banned

Token refresh fails after 90 days

Trovo refresh tokens expire after 90 days of inactivity:

1. User must reconnect the integration
2. Consider implementing activity tracking
3. Notify users before tokens expire