LiveChatMessages

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

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

메서드

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

list
특정 채팅의 실시간 채팅 메시지를 나열합니다. 지금 사용해보기
insert
실시간 채팅에 메시지를 추가합니다. 지금 사용해 보세요.
삭제
채팅 메시지를 삭제합니다. 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
이 객체에는 문자 메시지에 대한 세부정보가 포함됩니다. 메시지 유형이 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 메시지의 일부로 표시됩니다. 그러나 이미지 URL은 API를 통해 사용할 수 없습니다. 참고로 이 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
이 객체에는 설문조사 이벤트에 대한 세부정보가 포함됩니다. 메시지 유형이 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
이 값은 작성자가 실시간 채팅의 운영자인지 여부를 나타냅니다.