Skip to main content

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.liveChatId of 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
NameTypeRequiredDescription
broadcast_id / live_chat_idStringOne ofThe chat.
page_tokenStringNonext_page_token of the previous answer. Without it YouTube returns only the most recent messages.
max_resultsIntegerNo200-2000 (YouTube's default: 500).
profile_image_sizeIntegerNo16-720 px (default 88).
hlStringNoLanguage 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 answer 429 youtube_live_chat_poll_too_soon with retry_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, or 409 youtube_duplicate_request while 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_results 0-50, default 50; page_token): 50 units per page.
  • POST /live/moderators with {"broadcast_id": "…", "channel_id": "UC…"}: adds a moderator. 200 units.
  • DELETE /live/moderators/{moderator_id}?confirm=true (the id from the list, not a channel ID). 200 units.

Bans​

POST /api/uploadposts/youtube/live/bans
FieldRequiredDescription
broadcast_id / live_chat_idOne ofThe chat.
channel_idYesChannel ID (UC…) of the user, from authorDetails.channelId.
typeYespermanent or temporary.
duration_secondsNoTemporary bans only. Default 300 (5 minutes).
confirmYestrue.

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 of broadcast_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: send broadcast_id instead of live_chat_id. youtube_duplicate_request: a request with this idempotency_key is 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) or youtube_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.