YouTube Integration

Connect your YouTube accounts to enable live chat interaction, stream management, and channel analytics.

Setup

Prerequisites

1. A Google Cloud project with YouTube Data API v3 enabled
2. OAuth 2.0 credentials configured at Google Cloud Console
3. Configure your OAuth redirect URI: {server.public_url}/v1/integrations/callback/youtube
4. Note your Client ID and Client Secret

Google Cloud Configuration

1. Go to Google Cloud Console
2. Create or select a project
3. Enable the YouTube Data API v3
4. Go to APIs & Services > Credentials
5. Create OAuth 2.0 Client ID (Web application)
6. Add authorized redirect URI: {server.public_url}/v1/integrations/callback/youtube

Configuration

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

[integrations.youtube]
client_id = "your_google_client_id.apps.googleusercontent.com"
client_secret = "your_google_client_secret"

Or via environment variables:

SERVER_PUBLIC_URL=https://your-domain.com
YOUTUBE_INTEGRATION_CLIENT_ID=your_client_id.apps.googleusercontent.com
YOUTUBE_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/youtube

Make sure to add this exact URL to your Google Cloud OAuth 2.0 credentials' authorized redirect URIs.

OAuth Scopes

Channel Scopes

Scopes requested for channel (broadcaster) accounts:

Scope	Description	Required
https://www.googleapis.com/auth/youtube.readonly	View channel and video info	Yes
https://www.googleapis.com/auth/youtube	Manage YouTube account	Yes
https://www.googleapis.com/auth/youtube.force-ssl	Manage videos, comments, live chat	Yes

Bot Scopes

Scopes requested for bot accounts:

Scope	Description	Required
https://www.googleapis.com/auth/youtube.readonly	View channel and video info	Yes
https://www.googleapis.com/auth/youtube.force-ssl	Send live chat messages	Yes

YouTube Live Chat

Message Types

YouTube Live Chat supports several message types:

Type	Description	Bot Access
textMessageEvent	Regular chat message	Send & Read
superChatEvent	Paid highlight message	Read only
superStickerEvent	Paid sticker	Read only
membershipGiftingEvent	Gifted memberships	Read only
newSponsorEvent	New channel member	Read only

Sending Messages

POST https://www.googleapis.com/youtube/v3/liveChat/messages?part=snippet
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "snippet": {
    "liveChatId": "{live_chat_id}",
    "type": "textMessageEvent",
    "textMessageDetails": {
      "messageText": "Hello from the bot!"
    }
  }
}

Chat Rate Limits

YouTube has strict rate limits for live chat:

Quota Type	Limit
API Quota	10,000 units/day
LiveChatMessages.insert	200 units/request
LiveChatMessages.list	5 units/request

Daily limit: ~50 messages/day with default quota

To increase limits:

1. Apply for quota increase in Google Cloud Console
2. Verify your app through Google's verification process

Connecting Accounts

Connect Channel Account

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

Connect Bot Account

1. Create or use a separate Google account for your bot
2. Create a YouTube channel for the bot account (required)
3. Go to Admin > Integrations
4. Click "Connect" under YouTube
5. Select "Bot" as the account type
6. Enter a unique bot identifier
7. Sign in with the bot's Google account
8. Authorize the requested permissions

Token Management

Token Lifetime

• Access Token: 1 hour (automatically refreshed)
• Refresh Token: Does not expire (valid until revoked)

Automatic Refresh

Tokens are automatically refreshed before expiry. Google refresh tokens remain valid unless:

• User revokes access
• Token unused for 6 months
• User changes password

Token Errors

Error	Cause	Solution
invalid_grant	Refresh token revoked	Disconnect and reconnect
access_denied	User denied permissions	Retry with proper scopes
quota_exceeded	API quota limit reached	Wait 24h or request quota increase

Live Stream Detection

To work with live chat, you need to find the active live stream:

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?part=snippet,status&mine=true&broadcastStatus=active
Authorization: Bearer {access_token}

Response includes:

• id - Broadcast ID
• snippet.liveChatId - Chat ID for sending messages

Moderation

Delete Messages

DELETE https://www.googleapis.com/youtube/v3/liveChat/messages?id={message_id}
Authorization: Bearer {access_token}

Ban Users

POST https://www.googleapis.com/youtube/v3/liveChat/bans?part=snippet
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "snippet": {
    "liveChatId": "{live_chat_id}",
    "type": "permanent",
    "bannedUserDetails": {
      "channelId": "{user_channel_id}"
    }
  }
}

Ban types:

• permanent - Permanent ban
• temporary - Timeout (specify banDurationSeconds)

Troubleshooting

"App not verified" warning

During development, users see a warning screen. For production:

1. Complete Google's OAuth verification process
2. Submit privacy policy and app details
3. Wait for review (can take several weeks)

"Quota exceeded" errors

YouTube API has strict quotas:

1. Check quota usage in Google Cloud Console
2. Optimize API calls (batch where possible)
3. Request quota increase if needed

"Live chat not enabled"

The stream must have live chat enabled:

1. Check stream settings on YouTube
2. Ensure chat is enabled for the broadcast
3. Wait for stream to go fully live

Bot messages not appearing

1. Verify bot account has a YouTube channel
2. Check API response for errors
3. Ensure you're using the correct liveChatId
4. Verify quota hasn't been exceeded