LiveChatMessages

liveChatMessage 리소스는 YouTube 실시간 채팅의 채팅 메시지를 나타냅니다. 리소스에는 새로 게시된 문자 메시지 또는 크리에이터 후원 이벤트 등 여러 유형의 메시지에 대한 세부정보가 포함될 수 있습니다.

실시간 채팅 기능은 실시간 방송에서 기본적으로 사용 설정되어 있으며 실시간 이벤트가 진행되는 동안 사용할 수 있습니다. 이벤트가 종료되면 해당 이벤트에서는 더 이상 실시간 채팅을 사용할 수 없습니다.

메서드

API는 liveChatMessages 리소스에 다음 메서드를 지원합니다.

list
특정 채팅의 실시간 채팅 메시지를 나열합니다. 지금 사용해보기
insert
실시간 채팅에 메시지 또는 설문조사를 추가합니다. 지금 사용해보기
transition
실시간 메시지의 상태를 전환합니다. 지금 사용해보기
삭제
채팅 메시지를 삭제합니다. API 요청은 채널 소유자 또는 실시간 채팅 운영자의 승인을 받아야 합니다. 지금 사용해보기

리소스 표현

다음 JSON 구조는 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,
          "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
  },
}

속성

다음 표는 이 리소스에 표시되는 속성을 정의합니다.

속성
kind string
API 리소스의 유형을 식별합니다. 값은 youtube#liveChatMessage입니다.
etag etag
이 리소스의 Etag입니다.
id string
YouTube가 메시지를 고유하게 식별하기 위해 할당하는 ID입니다.
snippet object
snippet 객체에는 채팅 메시지에 관한 핵심 세부정보가 포함되어 있습니다.
snippet.type string
메시지 유형입니다. 이 속성은 항상 존재하며 이 속성에 따라 리소스에 있는 필드가 결정됩니다.

이 속성에 유효한 값은 다음과 같습니다.
  • chatEndedEvent – 채팅이 종료되어 더 이상 메시지를 삽입할 수 없습니다. 이는 방송이 끝나고 잠시 후에 자연스럽게 발생합니다. 이러한 유형의 메시지는 채널의 기본 브로드캐스트에서 실시간 채팅에 대해 전송되지 않습니다.
  • messageDeletedEvent – 운영자가 메시지를 삭제했습니다. author 필드에는 운영자의 세부정보가 포함됩니다. 이 이벤트에는 디스플레이 콘텐츠가 없습니다.
  • sponsorOnlyModeEndedEvent - 채팅이 더 이상 스폰서 전용 모드가 아닙니다. 즉, 스폰서가 아닌 사용자도 메시지를 보낼 수 있습니다. 이 이벤트에는 디스플레이 콘텐츠가 없습니다.
  • sponsorOnlyModeStartedEvent - 채팅이 스폰서 전용 모드로 전환되어 스폰서만 메시지를 보낼 수 있습니다. 이 이벤트에는 디스플레이 콘텐츠가 없습니다.
  • newSponsorEvent - 신규 사용자가 실시간 채팅을 소유한 채널을 후원했습니다. author 필드에는 새 스폰서의 세부정보가 포함됩니다.
  • memberMilestoneChatEvent - 사용자가 멤버십 기념 메시지를 보냈습니다.
  • superChatEvent - 사용자가 Super Chat을 구매했습니다.
  • superStickerEvent - 사용자가 Super Sticker를 구매했습니다.
  • textMessageEvent - 사용자가 문자 메시지를 보냈습니다.
  • tombstone - Tombstone은 이전에 이 ID와 게시 시간으로 존재했지만 삭제되었음을 나타냅니다. 메시지가 삭제될 때 전송되는 것이 아니라 메시지가 삭제되기 전의 위치를 나타내기 위해 표시됩니다. 이 유형의 메시지에는 snippet.liveChatId, snippet.type, snippet.publishedAt 필드만 있습니다.
  • userBannedEvent – 운영자에 의해 사용자가 차단되었습니다. author 필드에는 운영자의 세부정보가 포함됩니다.
  • membershipGiftingEvent - 사용자가 다른 시청자를 위해 멤버십을 구매했습니다.
  • giftMembershipReceivedEvent - 사용자가 멤버십 선물을 받았습니다.
  • pollDetails - 사용자가 실시간 설문조사를 만들었습니다.
snippet.liveChatId string
메시지가 연결된 실시간 채팅을 고유하게 식별하는 ID입니다. 방송과 연결된 실시간 채팅 ID는 liveBroadcast 리소스의 snippet.liveChatId 속성에 반환됩니다.
snippet.authorChannelId string
메시지를 작성한 사용자의 ID입니다. 이 필드는 다음 메시지 유형에 대해서만 채워집니다.
  • 메시지 유형이 textMessageEvent인 경우 속성 값은 메시지를 작성한 사용자를 식별합니다.
  • 메시지 유형이 fanFundingEvent인 경우 속성 값은 방송 자금을 지원한 사용자를 식별합니다.
  • 메시지 유형이 messageDeletedEvent인 경우 속성 값은 메시지를 삭제한 운영자를 식별합니다.
  • 메시지 유형이 newSponsorEvent인 경우 속성 값은 방금 스폰서가 된 사용자를 식별합니다.
  • 메시지 유형이 memberMilestoneChatEvent인 경우 속성 값은 메시지를 보낸 구성원을 식별합니다.
  • 메시지 유형이 userBannedEvent인 경우 속성 값은 사용자를 차단한 운영자를 식별합니다.
  • 메시지 유형이 membershipGiftingEvent인 경우 속성 값은 멤버십 선물을 구매한 사용자를 식별합니다.
  • 메시지 유형이 giftMembershipReceivedEvent인 경우 속성 값은 멤버십 선물을 받은 사용자를 식별합니다.
  • 메시지 유형이 pollEvent인 경우 속성 값은 실시간 설문조사를 만든 사용자를 식별합니다.
snippet.publishedAt datetime
메시지가 처음 게시된 날짜 및 시간입니다. 값은 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 형식으로 지정됩니다.
snippet.hasDisplayContent boolean
메시지에 사용자에게 표시되어야 하는 디스플레이 콘텐츠가 있는지 여부를 나타냅니다.
snippet.displayMessage string
사용자에게 표시되는 문자열이 포함됩니다. 이 필드는 message type이 chatEndedEvent 또는 tombstone인 경우에는 표시되지 않습니다.
snippet.fanFundingEventDetails object
참고: 이 객체 및 하위 속성은 지원 중단되었습니다. 2017년 2월 28일부터 liveChatMessage 리소스에서 더 이상 크리에이터 후원 이벤트의 세부정보를 반환하지 않습니다.

이 객체에는 자금 지원 이벤트에 대한 세부정보가 포함되어 있습니다. message type이 fanFundingEvent인 경우에만 존재합니다.
snippet.fanFundingEventDetails.amountMicros unsigned long
참고: 이 속성은 지원 중단되었습니다.

기금의 금액입니다.
snippet.fanFundingEventDetails.currency string
참고: 이 속성은 지원 중단되었습니다.

기금이 적립된 통화입니다.
snippet.fanFundingEventDetails.amountDisplayString string
참고: 이 속성은 지원 중단되었습니다.

사용자에게 금액과 통화를 표시하는 렌더링된 문자열입니다.
snippet.fanFundingEventDetails.userComment string
참고: 이 속성은 지원 중단되었습니다.

사용자가 이 크리에이터 후원 이벤트에 추가한 댓글입니다.
snippet.textMessageDetails object
이 객체는 문자 메시지에 대한 세부정보를 포함합니다. message type이 textMessageEvent인 경우에만 존재합니다.
snippet.textMessageDetails.messageText string
사용자의 메시지입니다.
snippet.messageDeletedDetails object
이 객체에는 채팅 운영자 또는 실시간 방송 채널 소유자가 삭제한 메시지에 대한 세부정보가 포함됩니다. message type이 messageDeletedEvent인 경우에만 존재합니다.
snippet.messageDeletedDetails.deletedMessageId string
삭제된 메시지를 고유하게 식별하는 ID입니다. 값은 원본 텍스트 메시지의 id 속성 값과 동일합니다. 예를 들어 textMessageEvent의 id 속성 값이 123이고 이후 메시지가 삭제되면 해당 메시지의 snippet.messageDeletedDetails.deletedMessageId 값은 123입니다.

채팅 메시지를 가져온 후 캐시하는 경우 이 속성의 값을 사용하여 더 이상 표시되어서는 안 되는 메시지를 식별합니다.
snippet.userBannedDetails object
이 객체에는 채팅에서 차단된 사용자에 대한 세부정보가 포함됩니다. 차단 자체에 관한 세부정보도 포함되어 있습니다. 사용자가 채팅에서 영구적으로 또는 일시적으로 차단될 수 있습니다.
snippet.userBannedDetails.bannedUserDetails object
이 객체에는 차단된 사용자에 대한 정보가 포함되어 있습니다.
snippet.userBannedDetails.bannedUserDetails.channelId string
차단된 사용자의 YouTube 채널 ID입니다.
snippet.userBannedDetails.bannedUserDetails.channelUrl string
차단된 사용자의 YouTube 채널 URL입니다.
snippet.userBannedDetails.bannedUserDetails.displayName string
차단된 사용자의 YouTube 채널 표시 이름입니다.
snippet.userBannedDetails.bannedUserDetails.profileImageUrl string
차단된 사용자의 YouTube 채널 아바타입니다.
snippet.userBannedDetails.banType string
차단 유형입니다. 이 속성에 유효한 값은 다음과 같습니다.
  • 완전히
  • 일시적
snippet.userBannedDetails.banDurationSeconds unsigned long
차단 기간 이 속성은 snippet.userBannedDetails.banType 속성 값이 temporary인 경우에만 존재합니다.
snippet.memberMilestoneChatDetails object
이 객체에는 멤버십 기념 이벤트에 대한 세부정보가 포함됩니다. message type이 memberMilestoneChatEvent인 경우에만 존재합니다.
snippet.memberMilestoneChatDetails.userComment string
회원이 멤버십 기념 메시지에 추가한 댓글입니다. 회원의 댓글이 없는 메시지의 경우 이 필드는 비어 있습니다.
snippet.memberMilestoneChatDetails.memberMonth unsigned integer
시청자가 멤버십 기념 메시지를 제공한 회원 자격을 유지한 총 개월 수 (반올림)입니다. YouTube 사용자에게 표시되는 개월 수와 동일합니다.
snippet.memberMilestoneChatDetails.memberLevelName string
뷰어가 구성원인 등급의 이름입니다. 등급 이름은 멤버십을 제공하는 YouTube 채널에서 정의합니다. 이 필드가 채워지지 않는 경우도 있습니다.
snippet.newSponsorDetails object
이 객체에는 신규 회원 공지 이벤트에 대한 세부정보가 포함됩니다. 유형이 newSponsorEvent인 경우에만 설정됩니다. '회원' 는 '스폰서'의 용어입니다.
snippet.newSponsorDetails.memberLevelName string
뷰어가 구성원인 등급의 이름입니다. 등급 이름은 멤버십을 제공하는 YouTube 채널에서 정의합니다. 경우에 따라 이 필드가 채워지지 않을 수도 있습니다.
snippet.newSponsorDetails.isUpgrade bool
뷰어가 낮은 레벨에서 업그레이드했는지 여부를 나타냅니다. 구매 시점에 회원이 아닌 뷰어의 경우 필드 값은 false입니다.
snippet.superChatDetails object
이 객체에는 Super Chat 이벤트에 대한 세부정보가 포함됩니다. message type이 superChatEvent인 경우에만 존재합니다.
snippet.superChatDetails.amountMicros unsigned long
구매 통화의 마이크로 단위로 나타낸 구매액입니다. 예를 들어 구매액이 1달러이면 snippet.amountMicros 속성 값은 1000000입니다.
snippet.superChatDetails.currency string
구매에 사용된 통화입니다. 값은 ISO 4217 통화 코드입니다.
snippet.superChatDetails.amountDisplayString string
$1.00과 같이 구매액과 통화가 포함된 문자열입니다. 문자열은 사용자에게 표시됩니다.
snippet.superChatDetails.userComment string
사용자가 이 Super Chat 이벤트에 추가한 댓글입니다.
snippet.superChatDetails.tier unsigned integer
유료 메시지의 계층입니다. superChatEvent 리소스에서 snippet.messageType 속성에 이 값이 포함되어 있습니다.

등급은 메시지를 구매하는 데 지출한 금액을 기준으로 합니다. 실시간 채팅 UI에서 메시지를 강조 표시하는 데 사용되는 색상, 최대 메시지 길이, 메시지가 티커에 고정되는 시간도 결정합니다.

Super Chat 등급은 YouTube 고객센터에 설명되어 있습니다. (Super Chat 구매 세부정보는 확장 가능한 섹션을 참조하세요.) 이 목록에서 구매액이 가장 낮은 계층이 계층 1이고 다음으로 낮은 금액이 계층 2인 식입니다.
snippet.superStickerDetails object
이 객체에는 Super Sticker 이벤트에 대한 세부정보가 포함됩니다. message type이 superStickerEvent인 경우에만 존재합니다.
snippet.superStickerDetails.superStickerMetadata object
Super Sticker에 관한 세부정보입니다.
snippet.superStickerDetails.superStickerMetadata.stickerId string
스티커 이미지를 식별하는 고유 ID입니다. 이 이미지는 사용자가 YouTube에서 채팅 창을 볼 때만 Super Sticker 메시지의 일부로 표시됩니다. 그러나 API를 사용하여 이미지 URL을 사용할 수는 없습니다. 이 CSV 파일에서 Super Sticker와 관련된 스티커 ID를 확인할 수 있습니다.
snippet.superStickerDetails.superStickerMetadata.altText string
스티커를 설명하는 텍스트 문자열입니다. snippet.superStickerDetails.superStickerMetadata.language 필드는 텍스트의 언어를 나타냅니다. liveChatMessages.list 메서드를 호출할 때 hl 매개변수 값을 텍스트에 선택된 언어로 설정합니다.
snippet.superStickerDetails.superStickerMetadata.language string
snippet.superStickerDetails.superStickerMetadata.altText 속성 값의 언어입니다.
snippet.superStickerDetails.amountMicros unsigned long
구매 통화의 마이크로 단위로 나타낸 구매액입니다. 예를 들어 구매액이 1달러이면 snippet.amountMicros 속성 값은 1000000입니다.
snippet.superStickerDetails.currency string
구매에 사용된 통화입니다. 값은 ISO 4217 통화 코드입니다.
snippet.superStickerDetails.amountDisplayString string
$1.00과 같이 구매액과 통화가 포함된 문자열입니다. 문자열은 사용자에게 표시됩니다.
snippet.superStickerDetails.tier unsigned integer
유료 메시지의 계층입니다. superChatEvent 리소스에서 snippet.messageType 속성에 이 값이 포함되어 있습니다.

등급은 메시지를 구매하는 데 지출한 금액을 기준으로 합니다. 실시간 채팅 UI에서 메시지를 강조 표시하는 데 사용되는 색상, 메시지 최대 길이, 메시지가 티커에 고정되는 시간도 결정합니다.

Super Sticker도 적용되는 Super Chat 등급은 YouTube 고객센터에 설명되어 있습니다. (Super Chat 구매 세부정보는 확장 가능한 섹션을 참조하세요.) 이 목록에서 구매액이 가장 낮은 계층이 계층 1이고 다음으로 낮은 금액이 계층 2인 식입니다.
snippet.pollDetails object
이 객체에는 설문조사 이벤트에 대한 세부정보가 포함됩니다. message type이 pollEvent인 경우에만 존재합니다.
snippet.pollDetails.metadata object
설문조사 이벤트에 대한 세부정보입니다.
snippet.pollDetails.metadata.options object
실시간 설문조사의 옵션입니다.
snippet.pollDetails.metadata.options.optionText string
실시간 설문조사 옵션의 텍스트입니다.
snippet.pollDetails.metadata.options.questionText string
실시간 설문조사 질문의 텍스트입니다.
snippet.pollDetails.metadata.status enum
실시간 설문조사 이벤트의 상태입니다. 이 속성에 유효한 값은 다음과 같습니다.
  • unknown
  • active
  • closed
snippet.membershipGiftingDetails object
이 객체에는 멤버십 선물하기 이벤트에 대한 세부정보가 포함됩니다. message type이 membershipGiftingEvent인 경우에만 존재합니다.
snippet.membershipGiftingDetails.giftMembershipsCount integer
사용자가 구매한 멤버십 선물 수입니다.
snippet.membershipGiftingDetails.giftMembershipsLevelName string
사용자가 구매한 멤버십 선물 등급의 이름입니다. 등급 이름은 멤버십을 제공하는 YouTube 채널에서 정의합니다. 경우에 따라 이 필드가 채워지지 않을 수도 있습니다.
snippet.giftMembershipReceivedDetails object
이 객체에는 멤버십 선물 수신 이벤트에 대한 세부정보가 포함되어 있습니다. message type이 giftMembershipReceivedEvent인 경우에만 존재합니다.
snippet.giftMembershipReceivedDetails.memberLevelName string
뷰어가 구성원인 등급의 이름입니다. 연결된 멤버십 선물하기 메시지의 snippet.membershipGiftingDetails.giftMembershipsLevelName와 일치합니다. 등급 이름은 멤버십을 제공하는 YouTube 채널에서 정의합니다. 경우에 따라 이 필드가 채워지지 않을 수도 있습니다.
snippet.giftMembershipReceivedDetails.gifterChannelId string
멤버십 선물하기를 구매한 사용자의 ID입니다. 연결된 멤버십 선물하기 메시지의 snippet.authorChannelId와 일치합니다.
snippet.giftMembershipReceivedDetails.associatedMembershipGiftingMessageId string
이 멤버십 선물과 관련된 멤버십 선물하기 메시지의 ID입니다. 이 ID는 항상 type가 membershipGiftingEvent인 메시지를 참조합니다.
authorDetails object
authorDetails 객체에는 이 메시지를 게시한 사용자에 대한 추가 세부정보가 포함됩니다.
authorDetails.channelId string
작성자의 YouTube 채널 ID입니다.
authorDetails.channelUrl string
작성자의 YouTube 채널 URL입니다.
authorDetails.displayName string
작성자의 YouTube 채널의 표시 이름입니다.
authorDetails.profileImageUrl string
작성자 YouTube 채널의 아바타 URL입니다.
authorDetails.isVerified boolean
이 값은 YouTube에서 작성자의 신원을 확인했는지 여부를 나타냅니다.
authorDetails.isChatOwner boolean
이 값은 작성자가 실시간 채팅의 소유자인지 여부를 나타냅니다.
authorDetails.isChatSponsor boolean
이 값은 작성자가 실시간 채팅의 스폰서인지 여부를 나타냅니다.
authorDetails.isChatModerator boolean
이 값은 작성자가 실시간 채팅의 운영자인지 여부를 나타냅니다.