LiveChatMessages

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

라이브 채팅 기능은 라이브 방송에 기본적으로 사용 설정되어 있으며 라이브 이벤트가 활성 상태일 때 사용할 수 있습니다. (이벤트가 종료되면 해당 이벤트의 실시간 채팅은 더 이상 사용할 수 없습니다.)

메서드

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

list
특정 채팅의 실시간 채팅 메시지를 나열합니다. 지금 사용해보기
streamList
지연 시간이 짧은 특정 채팅의 실시간 채팅 메시지를 수신하기 위한 서버 스트리밍 연결을 사용 설정합니다. 지금 사용해보기
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 – 채팅이 VIP 회원 전용 모드로 전환되어 VIP 회원만 메시지를 보낼 수 있습니다. 이 이벤트에는 표시 콘텐츠가 없습니다.
  • 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 Stickers와 관련이 있는지 확인할 수 있습니다.
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
이 값은 작성자가 실시간 채팅의 관리자인지 여부를 나타냅니다.