LiveChatMessages

  • The liveChatMessage resource represents a message in a YouTube live chat, encompassing text, fan funding, and other event types, and it is only available during the live event.

  • This resource's snippet property contains the core message details, including the message type, author information, and content, which can be a simple text message, a super chat, poll data or even details of a deleted message.

  • The authorDetails property within liveChatMessage provides comprehensive information about the message sender, such as their channel ID, display name, profile image, and their role in the chat (e.g., owner, sponsor, moderator).

  • Different message types, like superChatDetails, superStickerDetails, pollDetails, membershipGiftingDetails, or giftMembershipReceivedDetails, provide specific data structures that capture the unique attributes and data associated with each individual type of message in the live chat.

  • The liveChatMessage resource supports several methods including list to retrieve messages, insert to add messages or polls, transition to modify message states, and delete to remove messages, with the delete method requiring authorization.

A liveChatMessage resource represents a chat message in a YouTube live chat. The resource can contain details about several types of messages, including a newly posted text message or fan funding event.

The live chat feature is enabled by default for live broadcasts and is available while the live event is active. (After the event ends, live chat is no longer available for that event.)

Methods

The API supports the following methods for liveChatMessages resources:

list
Lists live chat messages for a specific chat. Try it now.
streamList
Enables a server-streaming connection for receiving live chat messages for a specific chat in low latency. Try it now.
insert
Adds a message or a poll to a live chat. Try it now.
transition
Transitions the state of a live message. Try it now.
delete
Deletes a chat message. The API request must be authorized by the channel owner or a moderator of the live chat. Try it now.

Resource representation

The following JSON structure shows the format of a liveChatMessages resource:

{
  "kind": "youtube#liveChatMessage",
  "etag": etag,
  "id": string,
  "snippet": {
    "type": string,
    "liveChatId": string,
    "authorChannelId": string,
    "publishedAt": datetime,
    "hasDisplayContent": boolean,
    "displayMessage": string,
    "fanFundingEventDetails": {
      "amountMicros": unsigned long,
      "currency": string,
      "amountDisplayString": string,
      "userComment": string
    },
    "textMessageDetails": {
      "messageText": string
    },
    "messageDeletedDetails": {
      "deletedMessageId": string
    },
    "userBannedDetails": {
      "bannedUserDetails": {
        "channelId": string,
        "channelUrl": string,
        "displayName": string,
        "profileImageUrl": string
      },
      "banType": string,
      "banDurationSeconds": unsigned long
    },
    "memberMilestoneChatDetails": {
      "userComment": string,
      "memberMonth": unsigned integer,
      "memberLevelName": string
    },
    "newSponsorDetails": {
      "memberLevelName": string,
      "isUpgrade": bool
    },
    "superChatDetails": {
      "amountMicros": unsigned long,
      "currency": string,
      "amountDisplayString": string,
      "userComment": string,
      "tier": unsigned integer
    },
    "superStickerDetails": {
      "superStickerMetadata": {
        "stickerId": string,
        "altText": string,
        "language": string
      },
      "amountMicros": unsigned long,
      "currency": string,
      "amountDisplayString": string,
      "tier": unsigned integer
    },
    "pollDetails": {
      "metadata": {
        "options": {
          "optionText": string,
          "tally": string,
        },
        "questionText": string,
        "status": enum
      },
    },
    "membershipGiftingDetails": {
      "giftMembershipsCount": integer,
      "giftMembershipsLevelName": string
    },
    "giftMembershipReceivedDetails": {
      "memberLevelName": string,
      "gifterChannelId": string,
      "associatedMembershipGiftingMessageId": string
    },
  },
  "authorDetails": {
    "channelId": string,
    "channelUrl": string,
    "displayName": string,
    "profileImageUrl": string,
    "isVerified": boolean,
    "isChatOwner": boolean,
    "isChatSponsor": boolean,
    "isChatModerator": boolean
  },
}

Properties

The following table defines the properties that appear in this resource:

Properties
kind string
Identifies the API resource's type. The value will be youtube#liveChatMessage.
etag etag
The Etag of this resource.
id string
The ID that YouTube assigns to uniquely identify the message.
snippet object
The snippet object contains core details about the chat message.
snippet.type string
The message's type. This property is always present, and its value determines which fields are present in the resource.

Valid values for this property are:
  • chatEndedEvent – The chat has ended and no more messages can be inserted after this one. This will occur naturally a little while after a broadcast ends. This type of message is not sent for live chats on a channel's default broadcast.
  • messageDeletedEvent – A message has been deleted by a moderator. The author field contains the moderator's details. This event does not have any display content.
  • sponsorOnlyModeEndedEvent – The chat is no longer in sponsors-only mode, which means that users that are not sponsors are now able to send messages. This event does not have any display content.
  • sponsorOnlyModeStartedEvent – The chat has entered sponsors-only mode, which means that only sponsors are able to send messages. This event has no display content.
  • newSponsorEvent – A new user has sponsored the channel that owns the live chat. The author fields contain the new sponsor's details.
  • memberMilestoneChatEvent – A user has sent a Member Milestone Chat.
  • superChatEvent – A user has purchased a Super Chat.
  • superStickerEvent – A user has purchased a Super Sticker.
  • textMessageEvent – A user has sent a text message.
  • tombstone – A tombstone signifies that a message used to exist with this id and publish time, but it has since been deleted. It is not sent upon deletion of a message, but rather is shown to signify where the message used to be before deletion. Only the snippet.liveChatId, snippet.type, and snippet.publishedAt fields are present in this type of message.
  • userBannedEvent – A user has been banned by a moderator. The author field contains the moderator's details.
  • membershipGiftingEvent – A user has purchased memberships for other viewers.
  • giftMembershipReceivedEvent – A user has received a gift membership.
  • pollDetails – A user has created a live poll.
snippet.liveChatId string
The ID that uniquely identifies the live chat with which the message is associated. The live chat ID associated with a broadcast is returned in the liveBroadcast resource's snippet.liveChatId property.
snippet.authorChannelId string
The ID of the user that authored the message. This field is only filled for the following message types:
  • If the message type is textMessageEvent, the property value identifies the user that wrote the message.
  • If the message type is fanFundingEvent, the property value identifies the user that funded the broadcast.
  • If the message type is messageDeletedEvent, the property value identifies the moderator that deleted the message.
  • If the message type is newSponsorEvent, the property value identifies the user that just became a sponsor.
  • If the message type is memberMilestoneChatEvent, the property value identifies the member that sent the message.
  • If the message type is userBannedEvent, the property value identifies the moderator that banned the user.
  • If the message type is membershipGiftingEvent, the property value identifies the user that made the membership gifting purchase.
  • If the message type is giftMembershipReceivedEvent, the property value identifies the user that received the gift membership.
  • If the message type is pollEvent, the property value identifies the user that created a live poll.
snippet.publishedAt datetime
The date and time when the message was originally published. The value is specified in ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) format.
snippet.hasDisplayContent boolean
Indicates whether the message has display content that should be displayed to users.
snippet.displayMessage string
Contains a string that is displayed to users. This field is not present if the message type is chatEndedEvent or tombstone.
snippet.fanFundingEventDetails object
Note: This object and its child properties have been deprecated. As of February 28, 2017, liveChatMessage resources will no longer return details for Fan Funding events.

This object contains details about the funding event. It is only present if the message type is fanFundingEvent.
snippet.fanFundingEventDetails.amountMicros unsigned long
Note: This property has been deprecated.

The amount of the fund.
snippet.fanFundingEventDetails.currency string
Note: This property has been deprecated.

The currency in which the fund was made.
snippet.fanFundingEventDetails.amountDisplayString string
Note: This property has been deprecated.

A rendered string that displays the fund amount and currency to the user.
snippet.fanFundingEventDetails.userComment string
Note: This property has been deprecated.

The comment added by the user to this fan funding event.
snippet.textMessageDetails object
This object contains details about the text message. It is only present if the message type is textMessageEvent.
snippet.textMessageDetails.messageText string
The user's message.
snippet.messageDeletedDetails object
This object contains details about a message deleted by a chat moderator or by the owner of the live broadcast's channel. It is only present if the message type is messageDeletedEvent.
snippet.messageDeletedDetails.deletedMessageId string
The ID that uniquely identifies the deleted message. The value is the same as the id property value of the original text message. For example, if a textMessageEvent has an id property value of 123, and that message is subsequently deleted, the snippet.messageDeletedDetails.deletedMessageId value will be 123 for that message.

If you cache chat messages after retrieving them, use the value of this property to identify the message that should no longer be displayed.
snippet.userBannedDetails object
This object contains details about a user who has been banned from the chat. It also contains details about the ban itself. Users can be banned from a chat permanently or temporarily.
snippet.userBannedDetails.bannedUserDetails object
This object contains information about the banned user.
snippet.userBannedDetails.bannedUserDetails.channelId string
The banned user's YouTube channel ID.
snippet.userBannedDetails.bannedUserDetails.channelUrl string
The URL of the banned user's YouTube channel.
snippet.userBannedDetails.bannedUserDetails.displayName string
The display name of the banned user's YouTube channel.
snippet.userBannedDetails.bannedUserDetails.profileImageUrl string
The avatar of the banned user's YouTube channel.
snippet.userBannedDetails.banType string
The type of ban. Valid values for this property are:
  • permanent
  • temporary
snippet.userBannedDetails.banDurationSeconds unsigned long
The duration of the ban. This property is only present if the snippet.userBannedDetails.banType property value is temporary.
snippet.memberMilestoneChatDetails object
This object contains details about a Member Milestone event. It is only present if the message type is memberMilestoneChatEvent.
snippet.memberMilestoneChatDetails.userComment string
The comment added by the member to this Member Milestone Chat. This field is empty for messages without a comment from the member.
snippet.memberMilestoneChatDetails.memberMonth unsigned integer
The total amount of months (rounded up) the viewer has been a member that granted them this Member Milestone Chat. This is the same number of months as is being displayed to YouTube users.
snippet.memberMilestoneChatDetails.memberLevelName string
The name of the Level at which the viewer is a member. The Level names are defined by the YouTube channel offering the Membership. In some situations this field isn't filled.
snippet.newSponsorDetails object
This object contains details about the New Member Announcement event. This is only set if the type is newSponsorEvent. "Member" is the term for "sponsor."
snippet.newSponsorDetails.memberLevelName string
The name of the Level at which the viewer is a member. The Level names are defined by the YouTube channel offering the Membership. In some situations, this field isn't filled.
snippet.newSponsorDetails.isUpgrade bool
Indicates whether the viewer just upgraded from a lower Level. For viewers that were not members at the time of purchase, the field value is false.
snippet.superChatDetails object
This object contains details about a Super Chat event. It is only present if the message type is superChatEvent.
snippet.superChatDetails.amountMicros unsigned long
The purchase amount, in micros of the purchase currency. For example, if the purchase amount is one dollar, the snippet.amountMicros property value is 1000000.
snippet.superChatDetails.currency string
The currency in which the purchase was made. The value is an ISO 4217 currency code.
snippet.superChatDetails.amountDisplayString string
A string, like $1.00, that contains the purchase amount and currency. The string is intended to be displayed to the user.
snippet.superChatDetails.userComment string
The comment added by the user to this Super Chat event.
snippet.superChatDetails.tier unsigned integer
The tier for the paid message. Note that in a superChatEvent resource, the snippet.messageType property contains this value.

The tier is based on the amount of money spent to purchase the message. It also determines the color used to highlight the message in the live chat UI, the maximum message length, and the amount of time that the message is pinned the ticker.

The Super Chat tiers are documented in the YouTube Help Center. (See the expandable section about Super Chat purchase details.) In that list, the tier with the lowest purchase amount is tier 1, the next lowest amount is tier 2, and so forth.
snippet.superStickerDetails object
This object contains details about a Super Sticker event. It is only present if the message type is superStickerEvent.
snippet.superStickerDetails.superStickerMetadata object
Details about the Super Sticker.
snippet.superStickerDetails.superStickerMetadata.stickerId string
A unique ID that identifies the sticker image. Note that the image is only displayed as part of the Super Sticker message when users view the chat window on YouTube. However, the image URL is not available using the API. For reference only, you can find which Sticker IDs relate to which Super Stickers in this CSV file.
snippet.superStickerDetails.superStickerMetadata.altText string
A text string that describes the sticker. The snippet.superStickerDetails.superStickerMetadata.language field identifies the language of the text. When calling the liveChatMessages.list method, set the hl parameter value to the chosen language for the text.
snippet.superStickerDetails.superStickerMetadata.language string
The language of the snippet.superStickerDetails.superStickerMetadata.altText property value.
snippet.superStickerDetails.amountMicros unsigned long
The purchase amount, in micros of the purchase currency. For example, if the purchase amount is one dollar, the snippet.amountMicros property value is 1000000.
snippet.superStickerDetails.currency string
The currency in which the purchase was made. The value is an ISO 4217 currency code.
snippet.superStickerDetails.amountDisplayString string
A string, like $1.00, that contains the purchase amount and currency. The string is intended to be displayed to the user.
snippet.superStickerDetails.tier unsigned integer
The tier for the paid message. Note that in a superChatEvent resource, the snippet.messageType property contains this value.

The tier is based on the amount of money spent to purchase the message. It also determines the color used to highlight the message in the live chat UI, the maximum message length, and the amount of time that the message is pinned the ticker.

The Super Chat tiers, which also cover Super Stickers, are documented in the YouTube Help Center. (See the expandable section about Super Chat purchase details.) In that list, the tier with the lowest purchase amount is tier 1, the next lowest amount is tier 2, and so forth.
snippet.pollDetails object
This object contains details about a poll event. It is only present if the message type is pollEvent.
snippet.pollDetails.metadata object
Details about the poll event.
snippet.pollDetails.metadata.options object
The options in the live poll.
snippet.pollDetails.metadata.options.optionText string
The text of the live poll option.
snippet.pollDetails.metadata.options.tally string
The tally of the live poll option. The tally is only present if the API request is authorized by the channel owner.
snippet.pollDetails.metadata.questionText string
The text of the live poll question.
snippet.pollDetails.metadata.status enum
The status of the live poll event. Valid values for this property are:
  • unknown
  • active
  • closed
snippet.membershipGiftingDetails object
This object contains details about a Membership Gifting event. It is only present if the message type is membershipGiftingEvent.
snippet.membershipGiftingDetails.giftMembershipsCount integer
The number of gift memberships purchased by the user.
snippet.membershipGiftingDetails.giftMembershipsLevelName string
The name of the Level of the gift memberships purchased by the user. Level names are defined by the YouTube channel offering the Membership. In some situations, this field isn't filled.
snippet.giftMembershipReceivedDetails object
This object contains details about a Gift Membership Received event. It is only present if the message type is giftMembershipReceivedEvent.
snippet.giftMembershipReceivedDetails.memberLevelName string
The name of the Level at which the viewer is a member. This matches the snippet.membershipGiftingDetails.giftMembershipsLevelName of the associated membership gifting message. Level names are defined by the YouTube channel offering the Membership. In some situations, this field isn't filled.
snippet.giftMembershipReceivedDetails.gifterChannelId string
The ID of the user that made the membership gifting purchase. This matches the snippet.authorChannelId of the associated membership gifting message.
snippet.giftMembershipReceivedDetails.associatedMembershipGiftingMessageId string
The ID of the membership gifting message that is related to this gift membership. This ID will always refer to a message whose type is membershipGiftingEvent.
authorDetails object
The authorDetails object contains additional details about the user that posted this message.
authorDetails.channelId string
The author's YouTube channel ID.
authorDetails.channelUrl string
The URL of the author's YouTube channel.
authorDetails.displayName string
The display name of the author's YouTube channel.
authorDetails.profileImageUrl string
The avatar URL of the author's YouTube channel.
authorDetails.isVerified boolean
This value indicates whether the author's identity has been verified by YouTube.
authorDetails.isChatOwner boolean
This value indicates whether the author is the owner of the live chat.
authorDetails.isChatSponsor boolean
This value indicates whether the author is a sponsor of the live chat.
authorDetails.isChatModerator boolean
This value indicates whether the author is a moderator of the live chat.