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 to a live chat. 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
    },
    "superChatDetails": {
      "amountMicros": unsigned long,
      "currency": string,
      "amountDisplayString": string,
      "userComment": string,
      "tier": unsigned integer
    }
  },
  "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. Note that this type of message is not currently sent for live chats on a channel's default broadcast.
  • fanFundingEventNote: This value has been deprecated. The API will no longer return resources describing Fan Funding events after February 28, 2017. Fan funding messages contain information about the contribution made and the chat user who made it.
  • 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.
  • newSponsorEvent – A new user has sponsored the channel that owns the live chat. The author fields contain the new sponsor's details.
  • 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.
  • superChatEvent – A user has purchased a Super Chat.
  • 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.
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 userBannedEvent, the property value identifies the moderator that banned the user.
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.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.
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.