LiveChatMessages

Tài nguyên liveChatMessage đại diện cho một tin nhắn trò chuyện trong Trò chuyện trong sự kiện phát trực tiếp trên YouTube. Tài nguyên này có thể chứa thông tin chi tiết về một số loại tin nhắn, bao gồm cả tin nhắn văn bản mới đăng hoặc sự kiện tài trợ của người hâm mộ.

Tính năng trò chuyện trực tiếp được bật theo mặc định cho các sự kiện phát sóng trực tiếp và hoạt động trong suốt thời gian diễn ra sự kiện trực tiếp. (Sau khi sự kiện kết thúc, tính năng trò chuyện trực tiếp sẽ không còn hoạt động cho sự kiện đó nữa.)

Phương thức

API này hỗ trợ các phương thức sau cho tài nguyên liveChatMessages:

list
Liệt kê tin nhắn trò chuyện trong cuộc trò chuyện qua Live cụ thể. Thử ngay.
streamList
Cho phép thiết lập một kết nối truyền phát trực tiếp trên máy chủ để nhận tin nhắn trò chuyện trực tiếp cho một cuộc trò chuyện cụ thể với độ trễ thấp. Thử ngay.
insert
Thêm tin nhắn hoặc cuộc thăm dò ý kiến vào Trò chuyện trong sự kiện phát trực tiếp. Thử ngay.
transition
Chuyển đổi trạng thái của một thông báo trực tiếp. Thử ngay.
xóa
Xoá tin nhắn trò chuyện. Yêu cầu API phải được chủ sở hữu kênh hoặc người kiểm duyệt Trò chuyện trong sự kiện phát trực tiếp cho phép. Thử ngay.

Cách trình bày tài nguyên

Cấu trúc JSON sau đây cho thấy định dạng của tài nguyên 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
    },
    "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
    },
    "giftDetails": {
      "jewelsAmount": integer,
      "giftName": string,
      "giftUrl": string,
      "giftDuration": object,
      "seconds": integer,
      "nanos": integer,
      "hasVisualEffect": boolean,
      "comboCount": integer,
      "altText": string,
      "language": string
    },
  },
  "authorDetails": {
    "channelId": string,
    "channelUrl": string,
    "displayName": string,
    "profileImageUrl": string,
    "isVerified": boolean,
    "isChatOwner": boolean,
    "isChatSponsor": boolean,
    "isChatModerator": boolean
  },
}

Thuộc tính

Bảng sau đây xác định các thuộc tính xuất hiện trong tài nguyên này:

Thuộc tính
kind string
Xác định loại tài nguyên của API. Giá trị sẽ là youtube#liveChatMessage.
etag etag
Etag của tài nguyên này.
id string
Mã nhận dạng duy nhất mà YouTube chỉ định cho thông báo.
Lưu ý: Đối với giftEvents, bạn có thể sử dụng lại cùng một mã nhận dạng để cập nhật số lượng kết hợp.
snippet object
Đối tượng snippet chứa thông tin chi tiết cốt lõi về tin nhắn trò chuyện.
snippet.type string
Loại thông báo. Thuộc tính này luôn xuất hiện và giá trị của thuộc tính này xác định những trường xuất hiện trong tài nguyên.

Các giá trị hợp lệ cho thuộc tính này là:
  • chatEndedEvent – Cuộc trò chuyện đã kết thúc và không thể chèn thêm tin nhắn nào sau tin nhắn này. Việc này sẽ diễn ra tự nhiên sau một khoảng thời gian ngắn kể từ khi chương trình phát sóng kết thúc. Loại thông báo này không được gửi cho Trò chuyện trong sự kiện phát trực tiếp trong chương trình phát sóng mặc định của một kênh.
  • sponsorOnlyModeEndedEvent – Cuộc trò chuyện không còn ở chế độ chỉ dành cho người tài trợ, tức là những người dùng không phải là người tài trợ hiện có thể gửi tin nhắn. Sự kiện này không có nội dung hiển thị.
  • sponsorOnlyModeStartedEvent – Cuộc trò chuyện đã chuyển sang chế độ chỉ dành cho người tài trợ, tức là chỉ người tài trợ mới có thể gửi tin nhắn. Sự kiện này không có nội dung hiển thị.
  • newSponsorEvent – Một người dùng mới đã tài trợ cho kênh sở hữu Trò chuyện trong sự kiện phát trực tiếp. Các trường author chứa thông tin chi tiết về nhà tài trợ mới.
  • memberMilestoneChatEvent – Một người dùng đã gửi Tin nhắn ghi nhận cột mốc làm hội viên.
  • superChatEvent – Người dùng đã mua Super Chat.
  • superStickerEvent – Người dùng đã mua một hình Super Sticker.
  • textMessageEvent – Người dùng đã gửi một tin nhắn văn bản.
  • tombstone – Tombstone cho biết rằng một thông báo từng tồn tại với mã nhận dạng và thời gian xuất bản này, nhưng sau đó đã bị xoá. Thông báo này không được gửi khi xoá tin nhắn, mà được hiển thị để cho biết vị trí của tin nhắn trước khi bị xoá. Chỉ các trường snippet.liveChatId, snippet.type và snippet.publishedAt mới xuất hiện trong loại thông báo này.
  • userBannedEvent – Người kiểm duyệt đã cấm một người dùng. Trường author chứa thông tin chi tiết về người kiểm duyệt.
  • membershipGiftingEvent – Một người dùng đã mua gói hội viên cho người xem khác.
  • giftMembershipReceivedEvent – Một người dùng đã nhận được quà tặng gói hội viên.
  • pollDetails – Người dùng đã tạo một cuộc thăm dò ý kiến trực tiếp.
  • giftEvent – Một người dùng đã dùng Ngọc để mua quà tặng.
snippet.liveChatId string
Mã nhận dạng duy nhất của cuộc trò chuyện qua Live có liên kết với tin nhắn. Mã Trò chuyện trong sự kiện phát trực tiếp liên kết với một sự kiện phát sóng được trả về trong thuộc tính snippet.liveChatId của tài nguyên liveBroadcast.
snippet.authorChannelId string
Mã nhận dạng của người dùng đã soạn tin nhắn. Trường này chỉ được điền cho các loại thông báo sau:
  • Nếu loại thông báo là textMessageEvent, thì giá trị thuộc tính sẽ xác định người dùng đã viết thông báo.
  • Nếu loại thông báo là fanFundingEvent, thì giá trị thuộc tính sẽ xác định người dùng đã tài trợ cho sự kiện phát sóng.
  • Nếu loại thông báo là newSponsorEvent, thì giá trị thuộc tính sẽ xác định người dùng vừa trở thành nhà tài trợ.
  • Nếu loại thông báo là memberMilestoneChatEvent, thì giá trị thuộc tính sẽ xác định thành viên đã gửi thông báo.
  • Nếu loại thông báo là userBannedEvent, thì giá trị thuộc tính sẽ xác định người kiểm duyệt đã cấm người dùng.
  • Nếu loại thông báo là membershipGiftingEvent, thì giá trị thuộc tính sẽ xác định người dùng đã thực hiện giao dịch mua Tặng gói hội viên.
  • Nếu loại thông báo là giftMembershipReceivedEvent, thì giá trị thuộc tính sẽ xác định người dùng nhận được quà tặng gói hội viên.
  • Nếu loại thông báo là pollEvent, thì giá trị thuộc tính sẽ xác định người dùng đã tạo cuộc thăm dò ý kiến trực tiếp.
  • Nếu loại tin nhắn là giftEvent, thì giá trị thuộc tính sẽ xác định người dùng đã gửi quà tặng.
snippet.publishedAt datetime
Ngày và giờ xuất bản thông báo ban đầu. Giá trị được chỉ định theo định dạng ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
snippet.hasDisplayContent boolean
Cho biết liệu thông báo có nội dung hiển thị mà người dùng nên thấy hay không.
snippet.displayMessage string
Chứa một chuỗi hiển thị cho người dùng. Trường này không xuất hiện nếu loại thông báo là chatEndedEvent hoặc tombstone.
snippet.fanFundingEventDetails object
Lưu ý: Đối tượng này và các thuộc tính con của đối tượng này không còn được dùng nữa. Kể từ ngày 28 tháng 2 năm 2017, tài nguyên liveChatMessage sẽ không còn trả về thông tin chi tiết về các sự kiện Tài trợ của người hâm mộ.

Đối tượng này chứa thông tin chi tiết về sự kiện tài trợ. Trường này chỉ xuất hiện nếu loại thông báo là fanFundingEvent.
snippet.fanFundingEventDetails.amountMicros unsigned long
Lưu ý: Thuộc tính này không còn được dùng nữa.

Số tiền của quỹ.
snippet.fanFundingEventDetails.currency string
Lưu ý: Thuộc tính này không được dùng nữa.

Đơn vị tiền tệ mà quỹ được tạo ra.
snippet.fanFundingEventDetails.amountDisplayString string
Lưu ý: Thuộc tính này không còn được dùng nữa.

Một chuỗi hiển thị số tiền và đơn vị tiền tệ cho người dùng.
snippet.fanFundingEventDetails.userComment string
Lưu ý: Thuộc tính này không còn được dùng nữa.

Bình luận mà người dùng thêm vào sự kiện tài trợ của người hâm mộ này.
snippet.textMessageDetails object
Đối tượng này chứa thông tin chi tiết về tin nhắn văn bản. Trường này chỉ xuất hiện nếu loại thông báo là textMessageEvent.
snippet.textMessageDetails.messageText string
Tin nhắn của người dùng.
snippet.userBannedDetails object
Đối tượng này chứa thông tin chi tiết về một người dùng đã bị cấm tham gia cuộc trò chuyện. Trang này cũng chứa thông tin chi tiết về lệnh cấm. Người dùng có thể bị cấm tham gia cuộc trò chuyện vĩnh viễn hoặc tạm thời.
snippet.userBannedDetails.bannedUserDetails object
Đối tượng này chứa thông tin về người dùng bị cấm.
snippet.userBannedDetails.bannedUserDetails.channelId string
Mã nhận dạng kênh YouTube của người dùng bị cấm.
snippet.userBannedDetails.bannedUserDetails.channelUrl string
URL của kênh YouTube của người dùng bị cấm.
snippet.userBannedDetails.bannedUserDetails.displayName string
Tên hiển thị của kênh YouTube của người dùng bị cấm.
snippet.userBannedDetails.bannedUserDetails.profileImageUrl string
Hình đại diện của kênh YouTube của người dùng bị cấm.
snippet.userBannedDetails.banType string
Loại lệnh cấm. Các giá trị hợp lệ cho thuộc tính này là:
  • vĩnh viễn
  • tạm thời
snippet.userBannedDetails.banDurationSeconds unsigned long
Thời hạn lệnh cấm. Thuộc tính này chỉ xuất hiện nếu giá trị thuộc tính snippet.userBannedDetails.banType là temporary.
snippet.memberMilestoneChatDetails object
Đối tượng này chứa thông tin chi tiết về sự kiện Cột mốc của hội viên. Trường này chỉ xuất hiện nếu loại thông báo là memberMilestoneChatEvent.
snippet.memberMilestoneChatDetails.userComment string
Bình luận mà hội viên thêm vào Tin nhắn ghi nhận cột mốc làm hội viên này. Trường này trống đối với những tin nhắn không có bình luận của hội viên.
snippet.memberMilestoneChatDetails.memberMonth unsigned integer
Tổng số tháng (làm tròn lên) mà người xem đã làm hội viên để nhận được Tin nhắn ghi nhận cột mốc làm hội viên này. Đây là số tháng mà người dùng YouTube nhìn thấy.
snippet.memberMilestoneChatDetails.memberLevelName string
Tên của cấp độ mà người xem là hội viên. Tên cấp độ do kênh YouTube cung cấp chương trình hội viên đặt ra. Trong một số trường hợp, trường này không được điền.
snippet.newSponsorDetails object
Đối tượng này chứa thông tin chi tiết về sự kiện Thông báo thành viên mới. Trường này chỉ được đặt nếu loại là newSponsorEvent. "Hội viên" là thuật ngữ thay thế cho "người tài trợ".
snippet.newSponsorDetails.memberLevelName string
Tên của cấp độ mà người xem là hội viên. Tên cấp độ do kênh YouTube cung cấp gói hội viên xác định. Trong một số trường hợp, trường này không được điền sẵn.
snippet.newSponsorDetails.isUpgrade bool
Cho biết người xem có vừa nâng cấp từ một cấp thấp hơn hay không. Đối với những người xem không phải là hội viên tại thời điểm mua, giá trị của trường này là false.
snippet.superChatDetails object
Đối tượng này chứa thông tin chi tiết về một sự kiện Super Chat. Trường này chỉ xuất hiện nếu loại thông báo là superChatEvent.
snippet.superChatDetails.amountMicros unsigned long
Số tiền mua, tính bằng micro của đơn vị tiền tệ mua. Ví dụ: nếu số tiền mua là 1 đô la, thì giá trị của thuộc tính snippet.amountMicros là 1000000.
snippet.superChatDetails.currency string
Đơn vị tiền tệ dùng để mua hàng. Giá trị là mã tiền tệ theo ISO 4217.
snippet.superChatDetails.amountDisplayString string
Một chuỗi, chẳng hạn như $1.00, chứa số tiền mua và đơn vị tiền tệ. Chuỗi này dùng để hiển thị cho người dùng.
snippet.superChatDetails.userComment string
Bình luận do người dùng thêm vào sự kiện Super Chat này.
snippet.superChatDetails.tier unsigned integer
Cấp của tin nhắn trả phí. Xin lưu ý rằng trong tài nguyên superChatEvent, thuộc tính snippet.messageType chứa giá trị này.

Cấp độ dựa trên số tiền đã chi để mua thông báo. Giá trị này cũng xác định màu sắc dùng để làm nổi bật tin nhắn trong giao diện người dùng của Trò chuyện trong sự kiện phát trực tiếp, độ dài tối đa của tin nhắn và khoảng thời gian tin nhắn được ghim vào đầu cuộc trò chuyện.

Các cấp Super Chat được ghi lại trong Trung tâm trợ giúp của YouTube. (Xem phần có thể mở rộng về chi tiết giao dịch mua Super Chat.) Trong danh sách đó, cấp có số tiền mua thấp nhất là cấp 1, số tiền thấp tiếp theo là cấp 2, v.v.
snippet.superStickerDetails object
Đối tượng này chứa thông tin chi tiết về một sự kiện Super Sticker. Trường này chỉ xuất hiện nếu loại thông báo là superStickerEvent.
snippet.superStickerDetails.superStickerMetadata object
Thông tin chi tiết về Super Stickers.
snippet.superStickerDetails.superStickerMetadata.stickerId string
Mã nhận dạng duy nhất xác định hình ảnh của hình dán. Xin lưu ý rằng hình ảnh này chỉ xuất hiện trong tin nhắn Super Stickers khi người dùng xem cửa sổ trò chuyện trên YouTube. Tuy nhiên, bạn không thể sử dụng API để lấy URL hình ảnh. Bạn có thể tham khảo tệp CSV này để biết mã Hình dán đặc biệt nào tương ứng với Super Stickers nào.
snippet.superStickerDetails.superStickerMetadata.altText string
Chuỗi văn bản mô tả hình dán. Trường snippet.superStickerDetails.superStickerMetadata.language xác định ngôn ngữ của văn bản. Khi gọi phương thức liveChatMessages.list, hãy đặt giá trị tham số hl thành ngôn ngữ đã chọn cho văn bản.
snippet.superStickerDetails.superStickerMetadata.language string
Ngôn ngữ của giá trị thuộc tính snippet.superStickerDetails.superStickerMetadata.altText.
snippet.superStickerDetails.amountMicros unsigned long
Số tiền mua, tính bằng micro của đơn vị tiền tệ mua. Ví dụ: nếu số tiền mua hàng là 1 đô la, thì giá trị thuộc tính snippet.amountMicros là 1000000.
snippet.superStickerDetails.currency string
Đơn vị tiền tệ mà bạn dùng để mua hàng. Giá trị này là mã tiền tệ theo chuẩn ISO 4217.
snippet.superStickerDetails.amountDisplayString string
Một chuỗi, chẳng hạn như $1.00, chứa số tiền mua và đơn vị tiền tệ. Chuỗi này dùng để hiển thị cho người dùng.
snippet.superStickerDetails.tier unsigned integer
Cấp của tin nhắn trả phí. Xin lưu ý rằng trong tài nguyên superChatEvent, thuộc tính snippet.messageType chứa giá trị này.

Cấp độ dựa trên số tiền đã chi để mua tin nhắn. Hệ thống cũng xác định màu dùng để làm nổi bật tin nhắn trong giao diện người dùng của Trò chuyện trong sự kiện phát trực tiếp, độ dài tối đa của tin nhắn và khoảng thời gian tin nhắn được ghim vào đầu cuộc trò chuyện.

Các cấp Super Chat (cũng áp dụng cho Super Stickers) được ghi trong Trung tâm trợ giúp của YouTube. (Xem phần có thể mở rộng về chi tiết giao dịch mua Super Chat.) Trong danh sách đó, cấp có số tiền mua hàng thấp nhất là cấp 1, số tiền thấp nhất tiếp theo là cấp 2, v.v.
snippet.pollDetails object
Đối tượng này chứa thông tin chi tiết về một sự kiện thăm dò ý kiến. Trường này chỉ xuất hiện nếu loại thông báo là pollEvent.
snippet.pollDetails.metadata object
Thông tin chi tiết về sự kiện thăm dò ý kiến.
snippet.pollDetails.metadata.options object
Các lựa chọn trong cuộc thăm dò ý kiến trực tiếp.
snippet.pollDetails.metadata.options.optionText string
Văn bản của lựa chọn trong cuộc thăm dò ý kiến trực tiếp.
snippet.pollDetails.metadata.options.tally string
Số phiếu của lựa chọn trong cuộc thăm dò ý kiến trực tiếp. Số lượng này chỉ xuất hiện nếu yêu cầu API được chủ sở hữu kênh cho phép.
snippet.pollDetails.metadata.questionText string
Nội dung câu hỏi trong cuộc thăm dò ý kiến trực tiếp.
snippet.pollDetails.metadata.status enum
Trạng thái của sự kiện thăm dò ý kiến trực tiếp. Các giá trị hợp lệ cho thuộc tính này là:
  • unknown
  • active
  • closed
snippet.membershipGiftingDetails object
Đối tượng này chứa thông tin chi tiết về một sự kiện Tặng gói hội viên. Thông tin này chỉ xuất hiện nếu message type là membershipGiftingEvent.
snippet.membershipGiftingDetails.giftMembershipsCount integer
Số quà tặng gói hội viên mà người dùng đã mua.
snippet.membershipGiftingDetails.giftMembershipsLevelName string
Tên của cấp độ quà tặng gói hội viên mà người dùng đã mua. Tên cấp độ do kênh YouTube cung cấp gói hội viên xác định. Trong một số trường hợp, trường này không được điền sẵn.
snippet.giftMembershipReceivedDetails object
Đối tượng này chứa thông tin chi tiết về sự kiện Nhận quà tặng gói hội viên. Trường này chỉ xuất hiện nếu message type là giftMembershipReceivedEvent.
snippet.giftMembershipReceivedDetails.memberLevelName string
Tên của cấp độ mà người xem là hội viên. Điều này phù hợp với snippet.membershipGiftingDetails.giftMembershipsLevelName của thông báo tặng gói hội viên có liên quan. Tên cấp độ do kênh YouTube cung cấp gói hội viên xác định. Trong một số trường hợp, trường này không được điền sẵn.
snippet.giftMembershipReceivedDetails.gifterChannelId string
Mã nhận dạng của người dùng đã mua quà tặng gói hội viên. Giá trị này khớp với snippet.authorChannelId của thông báo tặng gói hội viên có liên quan.
snippet.giftMembershipReceivedDetails.associatedMembershipGiftingMessageId string
Mã nhận dạng của thông báo tặng gói hội viên có liên quan đến quà tặng gói hội viên này. Mã nhận dạng này sẽ luôn đề cập đến một thông báo có type là membershipGiftingEvent.
snippet.giftDetails object
Đối tượng này chứa thông tin chi tiết về một sự kiện tặng quà. Trường này chỉ xuất hiện nếu message type là giftEvent.
snippet.giftDetails.jewelsAmount integer
Số Ngọc đã dùng để đổi quà.
snippet.giftDetails.giftName string
Tên của quà tặng.
snippet.giftDetails.giftUrl string
URL của thành phần quà tặng.
snippet.giftDetails.giftDuration object
Thời lượng hiển thị URL quà tặng.
snippet.giftDetails.giftDuration.seconds integer
Số giây hiển thị URL quà tặng.
snippet.giftDetails.giftDuration.nanos integer
Số nano giây để hiển thị URL quà tặng.
snippet.giftDetails.hasVisualEffect boolean
Quà tặng có hiệu ứng hình ảnh hay không.
snippet.giftDetails.comboCount integer
Số lượng quà tặng trong combo; 0 nếu không phải là combo.
snippet.giftDetails.altText string
Chuỗi văn bản mô tả quà tặng.
snippet.giftDetails.language string
Ngôn ngữ của giá trị thuộc tính altText.
authorDetails object
Đối tượng authorDetails chứa thông tin chi tiết khác về người dùng đã đăng thông báo này.
authorDetails.channelId string
Mã nhận dạng kênh YouTube của tác giả.
authorDetails.channelUrl string
URL của kênh YouTube của tác giả.
authorDetails.displayName string
Tên hiển thị của kênh YouTube của tác giả.
authorDetails.profileImageUrl string
URL hình đại diện của kênh YouTube của tác giả.
authorDetails.isVerified boolean
Giá trị này cho biết danh tính của tác giả đã được YouTube xác minh hay chưa.
authorDetails.isChatOwner boolean
Giá trị này cho biết liệu tác giả có phải là chủ sở hữu của Trò chuyện trong sự kiện phát trực tiếp hay không.
authorDetails.isChatSponsor boolean
Giá trị này cho biết liệu tác giả có phải là nhà tài trợ của Trò chuyện trong sự kiện phát trực tiếp hay không.
authorDetails.isChatModerator boolean
Giá trị này cho biết liệu tác giả có phải là người kiểm duyệt của Trò chuyện trong sự kiện phát trực tiếp hay không.