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

속성

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

속성
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 – 삭제된 항목은 이 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
사용자에게 표시되는 문자열을 포함합니다. 메시지 유형이 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에서 채팅 창을 볼 때만 슈퍼 스티커 메시지의 일부로 표시됩니다. 그러나 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.pollDetails object
이 객체에는 설문조사 이벤트에 관한 세부정보가 포함됩니다. 메시지 유형이 pollEvent인 경우에만 표시됩니다.
snippet.pollDetails.metadata object
설문조사 이벤트에 대한 세부정보입니다.
snippet.pollDetails.metadata.options object
실시간 설문조사의 옵션입니다.
snippet.pollDetails.metadata.options.optionText string
실시간 설문조사 옵션의 텍스트입니다.
snippet.pollDetails.metadata.options.tally string
실시간 설문조사 옵션의 집계입니다. 집계는 채널 소유자가 API 요청을 승인한 경우에만 표시됩니다.
snippet.pollDetails.metadata.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
이 값은 작성자가 실시간 채팅의 운영자인지 여부를 나타냅니다.