YouTube Live Chat, Polls and Moderation
Read and moderate the live chat of a YouTube broadcast, post messages and polls as the channel, and list the Super Chats it received. For the broadcast itself see Live broadcasts and streams.
All paths start with /api/uploadposts/youtube/live. Send user (profile username) in the query string or the JSON body and Authorization: Apikey your-api-key-here. Choose the chat with one of:
broadcast_id: a broadcast of your channel (Upload-Post looks up its chat).live_chat_id: any chat ID (snippet.liveChatIdof a broadcast).
Reading works on any chat. Writing (messages, polls, moderators and bans) only works in the chats of your channel's own broadcasts: another chat answers 403 youtube_live_chat_not_own. With live_chat_id, Upload-Post looks for it among your channel's active and upcoming broadcasts (1 unit per page of 50 broadcasts); a channel with many broadcasts may get 409 youtube_live_chat_needs_broadcast_id: send the broadcast_id instead, which is always checked exactly.
The chat exists only while the event lasts. They follow the common rules of the YouTube endpoints.
Read the chat
GET /api/uploadposts/youtube/live/chat
| Name | Type | Required | Description |
|---|---|---|---|
broadcast_id / live_chat_id | String | One of | The chat. |
page_token | String | No | next_page_token of the previous answer. Without it YouTube returns only the most recent messages. |
max_results | Integer | No | 200-2000 (YouTube's default: 500). |
profile_image_size | Integer | No | 16-720 px (default 88). |
hl | String | No | Language for amounts in Super Chats (e.g. es). |
Each request returns one page. Upload-Post does not follow the chat for you: your app calls again with next_page_token after waiting polling_interval_ms.
{
"success": true,
"live_chat_id": "Cg0KC2FiY2RlZmdoaWpr",
"items": [
{"id": "LCC.Cg8...", "snippet": {"type": "textMessageEvent", "displayMessage": "Hello!", "publishedAt": "..."},
"authorDetails": {"channelId": "UC...", "displayName": "Ana", "isChatModerator": false}}
],
"next_page_token": "GO2s...",
"page_info": {"totalResults": 1, "resultsPerPage": 500},
"polling_interval_ms": 5000,
"active_poll": null,
"offline_at": null
}
Messages come as YouTube's liveChatMessage resource: snippet.type tells text, superChatEvent (superChatDetails), superStickerEvent, newSponsorEvent, memberMilestoneChatEvent, membershipGiftingEvent, giftMembershipReceivedEvent, giftEvent (Jewels, giftDetails), pollEvent (pollDetails), userBannedEvent, chatEndedEvent… active_poll is the poll running now, if any.
Polling rules. Each read spends YouTube quota shared by everyone, so:
- Wait at least
polling_interval_ms(never less than 5 seconds) between reads of the same chat. Earlier calls answer429 youtube_live_chat_poll_too_soonwithretry_after_ms, without calling YouTube. - Up to 30 chat reads per minute per channel across all its chats (
429 youtube_live_chat_poll_limit). - Each read costs 5 units of the daily allowance: following a chat every 5 seconds uses about 3,600 units per hour. The daily allowance of a paid plan covers about 33 minutes of continuous reading; poll only while you need it.
YouTube's streaming alternative (liveChatMessages.streamList) only exists over gRPC and is not offered.
Post a message or a poll
POST /api/uploadposts/youtube/live/chat
The message is published as the channel in the public chat.
- Text:
{"user": "my-profile", "broadcast_id": "abc123def45", "message": "Welcome everyone!"}(one line, up to 200 characters). - Poll:
{"user": "my-profile", "broadcast_id": "abc123def45", "poll": {"question": "Next topic?", "options": ["Pricing", "Roadmap", "Q&A"]}}(2 to 4 different options, shown in that order). Only one poll can be active:400 youtube_live_poll_already_active. - Optional
idempotency_key(1-200 printable characters): the same key for the same channel within 24 hours posts once; the repeat gets the first answer with"idempotent_replay": true, or409 youtube_duplicate_requestwhile the first result is not confirmed.
Answer 201 with message (its id is the one to close the poll or delete it). Costs 20 units. Each channel can post a limited number of messages and polls per day through Upload-Post: 429 youtube_action_daily_limit with limit, retry_after and resets_at (midnight Pacific Time). If YouTube does not answer in time you get 502 youtube_write_outcome_unknown: read the chat before sending it again, it may already be there.
Close a poll
POST /api/uploadposts/youtube/live/chat/polls/{message_id}/close
Ends an active poll and returns the message with the final result (snippet.pollDetails.metadata.options[].tally). 20 units.
Delete a message
DELETE /api/uploadposts/youtube/live/chat/messages/{message_id}?user=my-profile&confirm=true
As the chat owner or a moderator (YouTube checks it: the message ID does not say which chat it belongs to). Cannot be undone. 20 units.
Moderators
Only for chats of your own broadcasts. Moderators and bans need the full YouTube permission: connections made before it was requested answer 403 youtube_insufficient_scope (reconnect the channel) before any unit is spent.
GET /live/moderators?broadcast_id=…(max_results0-50, default 50;page_token): 50 units per page.POST /live/moderatorswith{"broadcast_id": "…", "channel_id": "UC…"}: adds a moderator. 200 units.DELETE /live/moderators/{moderator_id}?confirm=true(theidfrom the list, not a channel ID). 200 units.
Bans
POST /api/uploadposts/youtube/live/bans
| Field | Required | Description |
|---|---|---|
broadcast_id / live_chat_id | One of | The chat. |
channel_id | Yes | Channel ID (UC…) of the user, from authorDetails.channelId. |
type | Yes | permanent or temporary. |
duration_seconds | No | Temporary bans only. Default 300 (5 minutes). |
confirm | Yes | true. |
The chat owner and moderators cannot be banned (403 youtube_live_chat_ban_not_allowed). Answer 201 with ban; keep its id to lift it with DELETE /live/bans/{ban_id}. 200 units each.
Super Chats and Super Stickers
GET /api/uploadposts/youtube/live/super-chats?user=my-profile
The channel's Super Chats and Super Stickers of the last 30 days (YouTube's window), newest first: supporter, amount (amountMicros, currency, displayString), comment and tier. hl (language of displayString), max_results (1-50, default 50), page_token. 2 units.
Channel memberships (members and levels) need a permission YouTube grants on request and are not available.
Error Responses
All errors carry success: false, error and a stable error_code; those from YouTube add youtube_status and youtube_reason.
- 400 —
invalid_filter(send one ofbroadcast_id/live_chat_id),invalid_parameter,missing_parameter,confirmation_required,invalid_idempotency_key,invalid_json,youtube_live_chat_message_invalid,youtube_live_poll_already_active. - 403 —
youtube_live_chat_not_own(writing in a chat that is not of your channel's broadcasts),youtube_insufficient_scope,youtube_live_chat_disabled,youtube_live_chat_ended,youtube_live_chat_not_allowed(the channel is not the owner or a moderator of that chat),youtube_live_chat_modification_not_allowed,youtube_live_chat_ban_not_allowed. - 404 —
youtube_live_chat_not_found,youtube_live_broadcast_not_found,youtube_live_chat_message_not_found,youtube_live_chat_user_not_found,youtube_live_chat_ban_not_found. - 409 —
youtube_live_chat_unavailable: the broadcast has no chat now (disabled or finished).youtube_live_chat_needs_broadcast_id: sendbroadcast_idinstead oflive_chat_id.youtube_duplicate_request: a request with thisidempotency_keyis still unconfirmed. - 429 —
youtube_live_chat_poll_too_soon(retry_after_ms),youtube_live_chat_poll_limit,youtube_action_daily_limit(messages and polls of this channel today), the daily allowance (youtube_daily_budget_exhausted,youtube_shared_budget_exhausted,youtube_quota_exhausted) oryoutube_rate_limited. - 502 —
youtube_write_outcome_unknown(check before retrying),youtube_unreachable,youtube_upstream_error. - 503 —
youtube_feature_disabled: YouTube management features are temporarily off on Upload-Post. Uploads keep working.