LiveChatMessages

Tài nguyên liveChatMessage đại diện cho một tin nhắn trò chuyện trong cuộc trò chuyện trực tiếp trên YouTube. Tài nguyên này có thể chứa thông tin chi tiết về nhiều loại tin nhắn, bao gồm cả tin nhắn văn bản mới đăng hoặc sự kiện ủng hộ 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 chương trình phát sóng trực tiếp và hoạt động trong khi sự kiện trực tiếp đang diễn ra. (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 đối với sự kiện đó.)

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 trực tiếp cho một cuộc trò chuyện cụ thể. Thử ngay.

streamList

Cho phép kết nối truyền phát trực tiếp từ 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.

chèn

Thêm tin nhắn hoặc cuộc thăm dò ý kiến vào cuộc trò chuyện trực tiếp. Thử ngay.

transition

Chuyển đổi trạng thái của một thông báo chính thức. Thử ngay.

xóa

Xoá một tin nhắn trò chuyện. Chủ sở hữu kênh hoặc người kiểm duyệt cuộc trò chuyện trực tiếp phải uỷ quyền cho yêu cầu API. 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
    },
    "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
  },
}

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 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.
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 tin nhắn. 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 có 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 sau tin nhắn này. Việc này sẽ diễn ra tự nhiên sau khi một 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 cuộc trò chuyện trực tiếp trong chương trình phát sóng mặc định của một kênh. messageDeletedEvent – Một tin nhắn đã bị người kiểm duyệt xoá. Trường author chứa thông tin chi tiết về người kiểm duyệt. Sự kiện này không có nội dung hiển thị. sponsorOnlyModeEndedEvent – Cuộc trò chuyện không còn ở chế độ chỉ dành cho nhà tài trợ nữa, tức là những người dùng không phải là nhà 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 nhà tài trợ, tức là chỉ nhà 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 cuộc trò chuyện trực tiếp. Các trường author chứa thông tin chi tiết của 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 Super Stickers. textMessageEvent – Một người dùng đã gửi tin nhắn văn bản. tombstone – Tombstone cho biết rằng trước đây đã từng có một thông báo với mã nhận dạng và thời gian xuất bản này, nhưng thông báo đó đã bị xoá. Thông báo này không được gửi khi bạn xoá một tin nhắn, mà xuất hiện để 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 có trong loại thông báo này. userBannedEvent – Người dùng đã bị người kiểm duyệt cấm. 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 – Người dùng đã nhận được một gói hội viên được tặng. pollDetails – Người dùng đã tạo một cuộc thăm dò ý kiến trực tiếp.
snippet.liveChatId	string Mã nhận dạng duy nhất của cuộc trò chuyện trực tiếp mà tin nhắn được liên kết. Mã nhận dạng cuộc trò chuyện trực tiếp liên kết với một chương trình 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 tin nhắn 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, giá trị thuộc tính sẽ xác định người dùng đã tài trợ cho chương trình phát sóng. Nếu loại thông báo là messageDeletedEvent, thì giá trị thuộc tính sẽ xác định người kiểm duyệt đã xoá thông báo. 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, giá trị thuộc tính sẽ xác định người dùng đã thực hiện giao dịch mua quà tặng 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 thành 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 một cuộc thăm dò ý kiến trực tiếp.
snippet.publishedAt	datetime Ngày và giờ xuất bản thông báo lần đầu. Giá trị được chỉ định ở đị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 dùng nữa. Kể từ ngày 28 tháng 2 năm 2017, tài nguyên liveChatMessage sẽ không trả về thông tin chi tiết về các sự kiện Ủng hộ người hâm mộ nữa. Đối tượng này chứa thông tin chi tiết về sự kiện gây quỹ. Tham số 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 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 dùng nữa. Một chuỗi được hiển thị cho người dùng thấy số tiền và đơn vị tiền tệ của quỹ.
snippet.fanFundingEventDetails.userComment	string Lưu ý: Thuộc tính này không được dùng nữa. Bình luận do người dùng thêm vào sự kiện ủng hộ 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. Tham số 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.messageDeletedDetails	object Đối tượng này chứa thông tin chi tiết về một tin nhắn bị người kiểm duyệt cuộc trò chuyện hoặc chủ sở hữu kênh của sự kiện phát trực tiếp xoá. Tham số này chỉ xuất hiện nếu loại thông báo là messageDeletedEvent.
snippet.messageDeletedDetails.deletedMessageId	string Mã nhận dạng duy nhất của thông báo đã bị xoá. Giá trị này giống với giá trị thuộc tính id của tin nhắn văn bản ban đầu. Ví dụ: nếu textMessageEvent có giá trị thuộc tính id là 123 và thông báo đó bị xoá sau đó, thì giá trị snippet.messageDeletedDetails.deletedMessageId sẽ là 123 cho thông báo đó. Nếu bạn lưu tin nhắn trò chuyện vào bộ nhớ đệm sau khi truy xuất, hãy dùng giá trị của thuộc tính này để xác định thông báo không còn được hiển thị nữa.
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 một 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ề một sự kiện Mốc quan trọng của thành viên. Tham số 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 do 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 sẽ trống đối với những tin nhắn không có bình luận của thành 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 giống như 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 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	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. Bạn chỉ đặt thuộc tính này nếu loại là newSponsorEvent. "Thành viên" là thuật ngữ dùng để chỉ "nhà 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à thành 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. Tham số 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 phần triệu của đơn vị tiền tệ mua. Ví dụ: nếu số tiền mua là 1 đô la, thì giá trị thuộc tính snippet.amountMicros là 1000000.
snippet.superChatDetails.currency	string Đơn vị tiền tệ mà bạn dùng để mua hàng. Giá trị này là mã đơn vị tiền tệ theo chuẩn 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 mà 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 có tính 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. Hệ thống 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 cuộc trò chuyện 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 bảng tin chạy chữ. 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 mua Super Chat.) Trong danh sách đó, cấp có số tiền mua thấp nhất là cấp 1, cấp có 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 Hình dán đặc biệt. Tham số 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ề Hình dán đặc biệt.
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 có Hình dán đặc biệt khi người dùng xem cửa sổ trò chuyện trên YouTube. Tuy nhiên, URL hình ảnh không có sẵn khi dùng API này. Bạn có thể xem mã Super Stickers tương ứng với từng mã Sticker trong tệp CSV này (chỉ để tham khảo).
snippet.superStickerDetails.superStickerMetadata.altText	string Một 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 phần triệu của đơn vị tiền tệ mua. Ví dụ: nếu số tiền mua 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ã đơn vị 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 có tính 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. 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 cuộc trò chuyện 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 bảng tin. Các cấp Super Chat (cũng áp dụng cho Super Stickers) được nêu trong Trung tâm trợ giúp của YouTube. (Xem phần có thể mở rộng về chi tiết mua Super Chat.) Trong danh sách đó, cấp có số tiền mua thấp nhất là cấp 1, cấp có số tiền thấp 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. Tham số 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ố liệu thống kê chỉ xuất hiện nếu chủ sở hữu kênh cho phép yêu cầu API.
snippet.pollDetails.metadata.questionText	string Văn bản của 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 quà hội viên. Tham số này chỉ xuất hiện nếu message type là membershipGiftingEvent.
snippet.membershipGiftingDetails.giftMembershipsCount	integer Số lượng gói hội viên được tặng mà người dùng đã mua.
snippet.membershipGiftingDetails.giftMembershipsLevelName	string Tên của Cấp độ gói hội viên được người dùng mua làm quà tặng. 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 thành viên. Tham số 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. Mã này khớ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 hội viên. Mã 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ã của thông báo tặng gói hội viên liên quan đến gói hội viên được tặng 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.
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 liệu 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 cuộc trò chuyện 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 cuộc trò chuyện trực tiếp hay không.
authorDetails.isChatModerator	boolean Giá trị này cho biết tác giả có phải là người kiểm duyệt của cuộc trò chuyện trực tiếp hay không.