LiveChatMessages

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.
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,
          "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.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.