LiveChatMessages

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

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

방법

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

list
특정 채팅의 실시간 채팅 메시지를 나열합니다. 지금 사용해보기
삽입
실시간 채팅에 메시지를 추가합니다. 지금 사용해보기
삭제
채팅 메시지를 삭제합니다. 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
    },
    "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 – 사용자가 멤버십 선물을 받았습니다.
snippet.liveChatId string
메시지가 연결된 실시간 채팅을 고유하게 식별하는 ID입니다. 방송과 연결된 실시간 채팅 ID는 liveBroadcast 리소스의 snippet.liveChatId 속성에 반환됩니다.
snippet.authorChannelId string
메시지를 작성한 사용자의 ID입니다. 이 필드는 다음 메시지 유형에 대해서만 채워집니다.
  • 메시지 유형이 textMessageEvent인 경우 속성 값은 메시지를 작성한 사용자를 식별합니다.
  • 메시지 유형이 fanFundingEvent인 경우 속성 값은 방송 자금을 지원한 사용자를 식별합니다.
  • 메시지 유형이 messageDeletedEvent인 경우 속성 값은 메시지를 삭제한 운영자를 식별합니다.
  • 메시지 유형이 newSponsorEvent인 경우 속성 값은 방금 스폰서가 된 사용자를 식별합니다.
  • 메시지 유형이 memberMilestoneChatEvent인 경우 속성 값은 메시지를 보낸 구성원을 식별합니다.
  • 메시지 유형이 userBannedEvent인 경우 속성 값으로 사용자를 차단한 운영자를 식별합니다.
  • 메시지 유형이 membershipGiftingEvent인 경우 속성 값은 멤버십 선물하기 구매를 한 사용자를 식별합니다.
  • 메시지 유형이 giftMembershipReceivedEvent인 경우 속성 값은 멤버십 선물을 받은 사용자를 식별합니다.
snippet.publishedAt datetime
메시지가 처음 게시된 날짜와 시간입니다. 값은 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 형식으로 지정됩니다.
snippet.hasDisplayContent boolean
메시지에 사용자에게 표시해야 하는 표시 콘텐츠가 있는지 여부를 나타냅니다.
snippet.displayMessage string
사용자에게 표시되는 문자열을 포함합니다. 메시지 유형이 chatEndedEvent 또는 tombstone인 경우에는 이 필드가 없습니다.
snippet.fanFundingEventDetails object
참고: 이 객체와 하위 속성은 지원 중단되었습니다. 2017년 2월 28일부터 liveChatMessage 리소스에서 더 이상 팬 후원 이벤트의 세부정보를 반환하지 않습니다.

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

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

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

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

사용자가 이 팬 후원 이벤트에 추가한 댓글입니다.
snippet.textMessageDetails object
이 객체에는 SMS에 대한 세부정보가 포함됩니다. 메시지 유형이 textMessageEvent인 경우에만 존재합니다.
snippet.textMessageDetails.messageText string
사용자의 메시지입니다.
snippet.messageDeletedDetails object
이 객체에는 채팅 운영자 또는 실시간 방송 채널 소유자가 삭제한 메시지에 대한 세부정보가 포함됩니다. 메시지 유형이 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
이 객체에는 멤버십 기념 이벤트에 대한 세부정보가 포함됩니다. 메시지 유형이 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 이벤트에 대한 세부정보가 포함됩니다. 메시지 유형이 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 이벤트에 대한 세부정보가 포함됩니다. 메시지 유형이 superStickerEvent인 경우에만 존재합니다.
snippet.superStickerDetails.superStickerMetadata object
Super Sticker 세부정보입니다.
snippet.superStickerDetails.superStickerMetadata.stickerId string
스티커 이미지를 식별하는 고유 ID입니다. 이미지는 사용자가 YouTube에서 채팅 창을 볼 때만 Super Sticker 메시지의 일부로 표시됩니다. 하지만 API를 통해서는 이미지 URL을 사용할 수 없습니다. 참고로 이 CSV 파일에서 어떤 스티커 ID와 어떤 Super Sticker와 연결되어 있는지 확인할 수 있습니다.
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.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
이 값은 작성자가 실시간 채팅의 운영자인지 여부를 나타냅니다.