LiveChatMessages

Um recurso liveChatMessage representa uma mensagem de chat em um chat ao vivo do YouTube. O recurso pode conter detalhes sobre vários tipos de mensagens, incluindo uma mensagem de texto recém-postada ou um evento de financiamento por fãs.

O chat ao vivo é ativado por padrão para transmissões ao vivo e fica disponível enquanto o evento está ativo. Depois que o evento termina, o chat ao vivo fica indisponível.

Métodos

A API é compatível com os seguintes métodos para recursos liveChatMessages:

list
Lista as mensagens do chat ao vivo de um chat específico. Faça um teste agora.
streamList
Ativa uma conexão de streaming do servidor para receber mensagens de chat ao vivo de um chat específico com baixa latência. Faça um teste agora.
inserir
Adiciona uma mensagem ou uma enquete a um chat ao vivo. Faça um teste agora.
transition
Faz a transição do estado de uma mensagem publicada. Faça um teste agora.
delete
Exclui uma mensagem de chat. A solicitação de API precisa ser autorizada pelo proprietário do canal ou por um moderador do chat ao vivo. Faça um teste agora.

Representação de recurso

A estrutura JSON a seguir mostra o formato de um recurso liveChatMessages:

{
  "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
  },
}

Propriedades

A tabela a seguir define as propriedades que aparecem neste recurso:

Propriedades
kind string
Identifica o tipo do recurso da API. O valor será youtube#liveChatMessage.
etag etag
A ETag deste recurso.
id string
O ID que o YouTube atribui para identificar exclusivamente a mensagem.
snippet object
O objeto snippet contém detalhes principais sobre a mensagem de chat.
snippet.type string
O tipo da mensagem. Essa propriedade está sempre presente, e o valor dela determina quais campos estão presentes no recurso.

Os valores válidos para essa propriedade são:
  • chatEndedEvent: o chat foi encerrado e não é possível inserir mais mensagens depois dessa. Isso vai acontecer naturalmente um pouco depois que uma transmissão terminar. Esse tipo de mensagem não é enviado para chats ao vivo na transmissão padrão de um canal.
  • messageDeletedEvent – Uma mensagem foi excluída por um moderador. O campo author contém os detalhes do moderador. Este evento não tem conteúdo de exibição.
  • sponsorOnlyModeEndedEvent – O chat não está mais no modo somente para patrocinadores, o que significa que usuários que não são patrocinadores agora podem enviar mensagens. Este evento não tem conteúdo de exibição.
  • sponsorOnlyModeStartedEvent – O chat entrou no modo somente para patrocinadores, o que significa que apenas patrocinadores podem enviar mensagens. Este evento não tem conteúdo de exibição.
  • newSponsorEvent – Um novo usuário patrocinou o canal proprietário do chat ao vivo. Os campos author contêm os detalhes do novo patrocinador.
  • memberMilestoneChatEvent: um usuário enviou uma Mensagem prêmio para membros.
  • superChatEvent: um usuário comprou um Super Chat.
  • superStickerEvent: um usuário comprou um Super Sticker.
  • textMessageEvent: um usuário enviou uma mensagem de texto.
  • tombstone: um marcador indica que uma mensagem existia com esse ID e horário de publicação, mas foi excluída. Ela não é enviada quando uma mensagem é excluída, mas sim mostrada para indicar onde a mensagem estava antes da exclusão. Apenas os campos snippet.liveChatId, snippet.type e snippet.publishedAt estão presentes nesse tipo de mensagem.
  • userBannedEvent – Um usuário foi banido por um moderador. O campo author contém os detalhes do moderador.
  • membershipGiftingEvent – Um usuário comprou assinaturas para outros espectadores.
  • giftMembershipReceivedEvent: um usuário recebeu uma assinatura de presente.
  • pollDetails: um usuário criou uma enquete ao vivo.
snippet.liveChatId string
O ID que identifica exclusivamente o chat ao vivo associado à mensagem. O ID do chat ao vivo associado a uma transmissão é retornado na propriedade snippet.liveChatId do recurso liveBroadcast.
snippet.authorChannelId string
O ID do usuário que criou a mensagem. Esse campo só é preenchido para os seguintes tipos de mensagem:
  • Se o tipo de mensagem for textMessageEvent, o valor da propriedade vai identificar o usuário que escreveu a mensagem.
  • Se o tipo de mensagem for fanFundingEvent, o valor da propriedade vai identificar o usuário que financiou a transmissão.
  • Se o tipo de mensagem for messageDeletedEvent, o valor da propriedade vai identificar o moderador que excluiu a mensagem.
  • Se o tipo de mensagem for newSponsorEvent, o valor da propriedade vai identificar o usuário que acabou de se tornar um patrocinador.
  • Se o tipo de mensagem for memberMilestoneChatEvent, o valor da propriedade vai identificar o membro que enviou a mensagem.
  • Se o tipo de mensagem for userBannedEvent, o valor da propriedade vai identificar o moderador que baniu o usuário.
  • Se o tipo de mensagem for membershipGiftingEvent, o valor da propriedade vai identificar o usuário que fez a compra da assinatura para presente.
  • Se o tipo de mensagem for giftMembershipReceivedEvent, o valor da propriedade vai identificar o usuário que recebeu a assinatura de presente.
  • Se o tipo de mensagem for pollEvent, o valor da propriedade vai identificar o usuário que criou uma enquete ao vivo.
snippet.publishedAt datetime
A data e a hora em que a mensagem foi publicada originalmente. O valor é especificado no formato ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
snippet.hasDisplayContent boolean
Indica se a mensagem tem conteúdo de exibição que deve ser mostrado aos usuários.
snippet.displayMessage string
Contém uma string que é exibida aos usuários. Esse campo não aparece se o tipo de mensagem for chatEndedEvent ou tombstone.
snippet.fanFundingEventDetails object
Observação: esse objeto e as propriedades filho dele foram descontinuados. Desde 28 de fevereiro de 2017, os recursos liveChatMessage não retornam mais detalhes sobre eventos de financiamento pelos fãs.

Esse objeto contém detalhes sobre o evento de financiamento. Ele só está presente se o tipo de mensagem for fanFundingEvent.
snippet.fanFundingEventDetails.amountMicros unsigned long
Observação: essa propriedade foi descontinuada.

O valor do fundo.
snippet.fanFundingEventDetails.currency string
Observação: essa propriedade foi descontinuada.

A moeda em que o fundo foi feito.
snippet.fanFundingEventDetails.amountDisplayString string
Observação: essa propriedade foi descontinuada.

Uma string renderizada que mostra o valor e a moeda do fundo ao usuário.
snippet.fanFundingEventDetails.userComment string
Observação: essa propriedade foi descontinuada.

O comentário adicionado pelo usuário a esse evento de financiamento por fãs.
snippet.textMessageDetails object
Esse objeto contém detalhes sobre a mensagem de texto. Ele só está presente se o tipo de mensagem for textMessageEvent.
snippet.textMessageDetails.messageText string
A mensagem do usuário.
snippet.messageDeletedDetails object
Esse objeto contém detalhes sobre uma mensagem excluída por um moderador do chat ou pelo proprietário do canal da transmissão ao vivo. Ele só está presente se o tipo de mensagem for messageDeletedEvent.
snippet.messageDeletedDetails.deletedMessageId string
O ID que identifica exclusivamente a mensagem excluída. O valor é o mesmo da propriedade id da mensagem de texto original. Por exemplo, se uma textMessageEvent tiver um valor de propriedade id de 123 e essa mensagem for excluída posteriormente, o valor de snippet.messageDeletedDetails.deletedMessageId será 123 para essa mensagem.

Se você armazenar em cache as mensagens de chat depois de recuperá-las, use o valor dessa propriedade para identificar a mensagem que não deve mais ser exibida.
snippet.userBannedDetails object
Esse objeto contém detalhes sobre um usuário que foi banido do chat. Ele também contém detalhes sobre a proibição. Os usuários podem ser banidos de um chat de forma permanente ou temporária.
snippet.userBannedDetails.bannedUserDetails object
Esse objeto contém informações sobre o usuário banido.
snippet.userBannedDetails.bannedUserDetails.channelId string
O ID do canal do YouTube do usuário banido.
snippet.userBannedDetails.bannedUserDetails.channelUrl string
O URL do canal do YouTube do usuário banido.
snippet.userBannedDetails.bannedUserDetails.displayName string
O nome de exibição do canal do YouTube do usuário banido.
snippet.userBannedDetails.bannedUserDetails.profileImageUrl string
O avatar do canal do YouTube do usuário banido.
snippet.userBannedDetails.banType string
O tipo de proibição. Os valores válidos para essa propriedade são:
  • permanente
  • temporário
snippet.userBannedDetails.banDurationSeconds unsigned long
A duração da proibição. Essa propriedade só aparece se o valor da propriedade snippet.userBannedDetails.banType for temporary.
snippet.memberMilestoneChatDetails object
Esse objeto contém detalhes sobre um evento de conquista de membro. Ele só está presente se o tipo de mensagem for memberMilestoneChatEvent.
snippet.memberMilestoneChatDetails.userComment string
O comentário adicionado pelo membro a esta Mensagem prêmio para membros. Esse campo fica vazio para mensagens sem um comentário do membro.
snippet.memberMilestoneChatDetails.memberMonth unsigned integer
O número total de meses (arredondado para cima) em que o espectador foi membro e ganhou a Mensagem prêmio para membros. Esse é o mesmo número de meses exibido para os usuários do YouTube.
snippet.memberMilestoneChatDetails.memberLevelName string
O nome do nível em que o espectador é membro. Os nomes dos níveis são definidos pelo canal do YouTube que oferece o clube. Em algumas situações, esse campo não é preenchido.
snippet.newSponsorDetails object
Esse objeto contém detalhes sobre o evento de anúncio de novo membro. Isso só será definido se o tipo for newSponsorEvent. "Membro" é o termo usado para "patrocinador".
snippet.newSponsorDetails.memberLevelName string
O nome do nível em que o espectador é membro. Os nomes dos níveis são definidos pelo canal do YouTube que oferece o clube. Em algumas situações, esse campo não é preenchido.
snippet.newSponsorDetails.isUpgrade bool
Indica se o espectador acabou de fazer upgrade de um nível inferior. Para espectadores que não eram membros no momento da compra, o valor do campo é false.
snippet.superChatDetails object
Esse objeto contém detalhes sobre um evento do Super Chat. Ele só está presente se o tipo de mensagem for superChatEvent.
snippet.superChatDetails.amountMicros unsigned long
O valor da compra, em micros da moeda de compra. Por exemplo, se o valor da compra for de um dólar, o valor da propriedade snippet.amountMicros será 1000000.
snippet.superChatDetails.currency string
A moeda em que a compra foi feita. O valor é um código de moeda ISO 4217.
snippet.superChatDetails.amountDisplayString string
Uma string, como $1.00, que contém o valor e a moeda da compra. A string deve ser exibida para o usuário.
snippet.superChatDetails.userComment string
O comentário adicionado pelo usuário a esse evento do Super Chat.
snippet.superChatDetails.tier unsigned integer
O nível da mensagem paga. Em um recurso superChatEvent, a propriedade snippet.messageType contém esse valor.

O nível é baseado no valor gasto para comprar a mensagem. Ele também determina a cor usada para destacar a mensagem na interface do chat ao vivo, o comprimento máximo da mensagem e o tempo que ela fica fixada no ticker.

Os níveis do Super Chat estão documentados na Central de Ajuda do YouTube. (Consulte a seção expansível sobre detalhes da compra do Super Chat.) Nessa lista, a camada com o menor valor de compra é a 1, o próximo menor valor é a camada 2 e assim por diante.
snippet.superStickerDetails object
Esse objeto contém detalhes sobre um evento de Super Sticker. Ele só está presente se o tipo de mensagem for superStickerEvent.
snippet.superStickerDetails.superStickerMetadata object
Detalhes sobre o Super Sticker.
snippet.superStickerDetails.superStickerMetadata.stickerId string
Um ID exclusivo que identifica a imagem do adesivo. A imagem só aparece como parte da mensagem do Supersticker quando os usuários abrem a janela de chat no YouTube. No entanto, o URL da imagem não está disponível usando a API. Para referência, confira neste arquivo CSV (em inglês) quais IDs de adesivos estão relacionados a quais Superadesivos.
snippet.superStickerDetails.superStickerMetadata.altText string
Uma string de texto que descreve o adesivo. O campo snippet.superStickerDetails.superStickerMetadata.language identifica o idioma do texto. Ao chamar o método liveChatMessages.list, defina o valor do parâmetro hl como o idioma escolhido para o texto.
snippet.superStickerDetails.superStickerMetadata.language string
O idioma do valor da propriedade snippet.superStickerDetails.superStickerMetadata.altText.
snippet.superStickerDetails.amountMicros unsigned long
O valor da compra, em micros da moeda de compra. Por exemplo, se o valor da compra for de um dólar, o valor da propriedade snippet.amountMicros será 1000000.
snippet.superStickerDetails.currency string
A moeda em que a compra foi feita. O valor é um código de moeda ISO 4217.
snippet.superStickerDetails.amountDisplayString string
Uma string, como $1.00, que contém o valor e a moeda da compra. A string deve ser exibida para o usuário.
snippet.superStickerDetails.tier unsigned integer
O nível da mensagem paga. Em um recurso superChatEvent, a propriedade snippet.messageType contém esse valor.

O nível é baseado no valor gasto para comprar a mensagem. Ele também determina a cor usada para destacar a mensagem na interface do chat ao vivo, o tamanho máximo da mensagem e o tempo que ela fica fixada no ticker.

Os níveis do Super Chat, que também incluem os Super Stickers, estão documentados na Central de Ajuda do YouTube. (Consulte a seção expansível sobre detalhes da compra do Super Chat.) Nessa lista, a camada com o menor valor de compra é a 1, o próximo menor valor é a camada 2 e assim por diante.
snippet.pollDetails object
Esse objeto contém detalhes sobre um evento de pesquisa. Ele só está presente se o tipo de mensagem for pollEvent.
snippet.pollDetails.metadata object
Detalhes sobre o evento de pesquisa.
snippet.pollDetails.metadata.options object
As opções na enquete ao vivo.
snippet.pollDetails.metadata.options.optionText string
O texto da opção de enquete ao vivo.
snippet.pollDetails.metadata.options.tally string
A contagem da opção de enquete ao vivo. A contagem só aparece se a solicitação de API for autorizada pelo proprietário do canal.
snippet.pollDetails.metadata.questionText string
O texto da pergunta da enquete em tempo real.
snippet.pollDetails.metadata.status enum
O status do evento de enquete ao vivo. Os valores válidos para essa propriedade são:
  • unknown
  • active
  • closed
snippet.membershipGiftingDetails object
Esse objeto contém detalhes sobre um evento de presente de assinatura. Ele só está presente se o message type for membershipGiftingEvent.
snippet.membershipGiftingDetails.giftMembershipsCount integer
O número de assinaturas de presente compradas pelo usuário.
snippet.membershipGiftingDetails.giftMembershipsLevelName string
O nome do nível das assinaturas de presente compradas pelo usuário. Os nomes dos níveis são definidos pelo canal do YouTube que oferece o clube. Em algumas situações, esse campo não é preenchido.
snippet.giftMembershipReceivedDetails object
Esse objeto contém detalhes sobre um evento de assinatura recebida como presente. Ele só está presente se o message type for giftMembershipReceivedEvent.
snippet.giftMembershipReceivedDetails.memberLevelName string
O nome do nível em que o espectador é membro. Isso corresponde ao snippet.membershipGiftingDetails.giftMembershipsLevelName da mensagem associada de presente de assinatura. Os nomes dos níveis são definidos pelo canal do YouTube que oferece o clube. Em algumas situações, esse campo não é preenchido.
snippet.giftMembershipReceivedDetails.gifterChannelId string
O ID do usuário que fez a compra do presente de assinatura. Isso corresponde ao snippet.authorChannelId da mensagem associada de presente de assinatura.
snippet.giftMembershipReceivedDetails.associatedMembershipGiftingMessageId string
O ID da mensagem de presente de assinatura relacionada a esta assinatura presenteada. Esse ID sempre se refere a uma mensagem cujo type é membershipGiftingEvent.
authorDetails object
O objeto authorDetails contém mais detalhes sobre o usuário que postou essa mensagem.
authorDetails.channelId string
O ID do canal do YouTube do autor.
authorDetails.channelUrl string
O URL do canal do YouTube do autor.
authorDetails.displayName string
O nome de exibição do canal do YouTube do autor.
authorDetails.profileImageUrl string
O URL do avatar do canal do YouTube do autor.
authorDetails.isVerified boolean
Esse valor indica se a identidade do autor foi verificada pelo YouTube.
authorDetails.isChatOwner boolean
Esse valor indica se o autor é o proprietário do chat em tempo real.
authorDetails.isChatSponsor boolean
Esse valor indica se o autor é um patrocinador do chat ao vivo.
authorDetails.isChatModerator boolean
Esse valor indica se o autor é um moderador do chat ao vivo.