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	Read user profile	Yes
channel_details_self	Read channel information	Yes
channel_update_self	Update channel settings	No
channel_subscriptions	View subscribers	No
chat_connect	Connect to chat	Yes
chat_send_self	Send chat messages	No

Bot Scopes

Scopes requested for bot accounts:

Scope	Description	Required
user_details_self	Read user profile	Yes
chat_connect	Connect to chat	Yes
chat_send_self	Send chat messages	Yes
send_to_my_channel	Send to own channel	No
manage_messages	Delete messages	No

Chat Integration

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 chat_connect scope authorized
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