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. Theauthorfield 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. Theauthorfields 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 thesnippet.liveChatId,snippet.type, andsnippet.publishedAtfields are present in this type of message. -
userBannedEvent– A user has been banned by a moderator. Theauthorfield 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.
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
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
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.
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
.