LiveChatMessages

Tài nguyên liveChatMessage biểu thị một tin nhắn trò chuyện trong một cuộc trò chuyện trực tiếp trên YouTube. Tài liệu này có thể chứa thông tin chi tiết về một số loại tin nhắn, trong đó 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ộ.

Theo mặc định, tính năng trò chuyện trực tiếp sẽ được bật cho các buổi phát sóng trực tiếp và sẽ hoạt động 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 trong 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ê các tin nhắn trò chuyện trực tiếp cho một cuộc trò chuyện cụ thể. 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 đang hoạt động. 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 của cuộc trò chuyện trực tiếp uỷ quyền. Thử ngay.

Biểu diễn 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,
          "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 mà YouTube gán để nhận dạng chính xác 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 tồn tại 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à bạn không thể chèn thêm tin nhắn sau cuộc trò chuyện này. Quá trình này sẽ diễn ra tự nhiên sau giây lát sau khi chương trình phát sóng kết thúc. Loại tin nhắn này không gửi được cho cuộc trò chuyện trực tiếp trên chương trình phát sóng mặc định của kênh.
  • messageDeletedEvent – Người kiểm duyệt đã xóa một bài viết. 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ị nào.
  • sponsorOnlyModeEndedEvent – Cuộc trò chuyện không còn ở chế độ chỉ dành cho nhà tài trợ, nghĩa là những người dùng không phải là nhà tài trợ giờ đây có thể gửi tin nhắn. Sự kiện này không có nội dung hiển thị nào.
  • 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 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 – Một người dùng đã mua Super Chat.
  • superStickerEvent – Một người dùng đã mua một Super Stickers.
  • textMessageEvent – Một người dùng đã gửi một tin nhắn văn bản.
  • tombstone – Tombstone cho biết một thư 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á. Tin nhắn không được gửi khi tin nhắn bị xoá, mà được hiển thị để biểu thị vị trí của tin nhắn trước khi bị xoá. Loại thông báo này chỉ có các trường snippet.liveChatId, snippet.typesnippet.publishedAt.
  • userBannedEvent – Một 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 những người xem khác.
  • giftMembershipReceivedEvent – Một người dùng đã được nhận quà tặng gói hội viên.
  • pollDetails – Một người dùng đã tạo cuộc thăm dò ý kiến trực tiếp.
snippet.liveChatId string
Mã nhận dạng giúp xác định chính xác cuộc trò chuyện trực tiếp có liên kết với tin nhắn đó. Mã 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 đã tạo thông báo. Trường này chỉ được điền cho những loại thông báo sau đây:
  • 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 đã cấp tiền 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 đã xóa tin nhắn đó.
  • 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 quà tặng gói hội viên.
  • Nếu loại thông báo là giftMembershipReceivedEvent, thì giá trị của 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.
snippet.publishedAt datetime
Ngày và giờ xuất bản thông báo lần đầu. Giá trị này đượ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ị cần được hiển thị cho người dùng hay không.
snippet.displayMessage string
Chứa một chuỗi mà người dùng nhìn thấy. Trường này sẽ không xuất hiện nếu loại thông báochatEndedEvent 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 trả về thông tin chi tiết về các sự kiện Tài trợ của người hâm mộ nữa.

Đối tượng này chứa thông tin chi tiết về sự kiện tài trợ. Thông số này chỉ xuất hiện nếu loại thông báofanFundingEvent.
snippet.fanFundingEventDetails.amountMicros unsigned long
Lưu ý: Tài sản này không được dùng nữa.

Số tiền của quỹ.
snippet.fanFundingEventDetails.currency string
Lưu ý: Tài sản này không còn được dùng nữa.

Đơn vị tiền tệ dùng để tạo quỹ.
snippet.fanFundingEventDetails.amountDisplayString string
Lưu ý: Tài sản này không còn được dùng nữa.

Một chuỗi được hiển thị hiển thị số tiền và đơn vị tiền tệ cho người dùng.
snippet.fanFundingEventDetails.userComment string
Lưu ý: Tài sản 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. Thông số này chỉ xuất hiện nếu loại thông báotextMessageEvent.
snippet.textMessageDetails.messageText string
Thông báo 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 chương trình phát trực tiếp xoá. Thông số này chỉ xuất hiện nếu loại thông báomessageDeletedEvent.
snippet.messageDeletedDetails.deletedMessageId string
Mã nhận dạng xác định duy nhất thư đã 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 gốc. Ví dụ: nếu textMessageEvent có giá trị thuộc tính id123 và tin nhắn đó sau đó bị xoá, thì giá trị snippet.messageDeletedDetails.deletedMessageId sẽ là 123 cho tin nhắn đó.

Nếu bạn lưu tin nhắn trò chuyện vào bộ nhớ đệm sau khi truy xuất, hãy sử dụng giá trị của thuộc tính này để xác định tin nhắn không còn 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. Bài viết 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 kênh YouTube của người dùng bị cấm.
snippet.userBannedDetails.bannedUserDetails.displayName string
Tên hiển thị trên kênh YouTube của người dùng bị cấm.
snippet.userBannedDetails.bannedUserDetails.profileImageUrl string
Hình đại diện trên 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 gian cấm. Thuộc tính này chỉ xuất hiện nếu giá trị thuộc tính snippet.userBannedDetails.banTypetemporary.
snippet.memberMilestoneChatDetails object
Đối tượng này chứa thông tin chi tiết về một sự kiện ghi nhận cột mốc làm hội viên. Thông số này chỉ xuất hiện nếu loại thông báomemberMilestoneChatEvent.
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ó nhận xét của thành viên.
snippet.memberMilestoneChatDetails.memberMonth unsigned integer
Tổng số tháng (làm tròn) mà người xem làm hội viên đã gửi Tin nhắn ghi nhận cột mốc làm hội viên này cho họ. Đây cũng 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 độ là 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.
snippet.newSponsorDetails object
Đối tượng này chứa thông tin chi tiết về sự kiện Thông báo cho thành viên mới. Thông tin này chỉ được thiết lập nếu kiểu là newSponsorEvent. "Thành viên" là thuật ngữ có nghĩa là "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 độ là 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.
snippet.newSponsorDetails.isUpgrade bool
Cho biết liệu 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 hàng, 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. Thông số này chỉ xuất hiện nếu loại thông báosuperChatEvent.
snippet.superChatDetails.amountMicros unsigned long
Số tiền mua, tính bằng phần triệu đơn vị tiền tệ của giao dịch mua. Ví dụ: Nếu số tiền mua là 1 đô la Mỹ, thì giá trị của tài sản snippet.amountMicros1000000.
snippet.superChatDetails.currency string
Đơn vị tiền tệ dùng để thực hiện giao dịch mua. Giá trị là mã đơn vị tiền tệ 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 sẽ được 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 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 được xác định dựa trên số tiền đã chi tiêu để mua tin nhắn. Đây cũng là 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, thời lượng tin nhắn tối đa và khoảng thời gian ghim đầu tin nhắn.

Bạn có thể xem thông tin về các bậc Super Chat trong Trung tâm trợ giúp của YouTube. (Xem phần 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 thấp nhất 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 Stickers. Thông số này chỉ xuất hiện nếu loại thông báosuperStickerEvent.
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 giúp nhận dạng hình ảnh có 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 sẽ không thể dùng URL hình ảnh khi dùng API. Bạn có thể xem những mã hình dán liên quan đến Super Stickers trong tệp CSV này để tham khả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 phần triệu đơn vị tiền tệ của giao dịch mua. Ví dụ: Nếu số tiền mua là 1 đô la Mỹ, thì giá trị của tài sản snippet.amountMicros1000000.
snippet.superStickerDetails.currency string
Đơn vị tiền tệ dùng để thực hiện giao dịch mua. Giá trị là mã đơn vị tiền tệ 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 sẽ được 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 được xác định dựa trên số tiền đã chi tiêu để mua tin nhắn. Chỉ số 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 trò chuyện trực tiếp, thời lượng tin nhắn tối đa và khoảng thời gian ghim đầu tin nhắn.

Các bậc Super Chat (bao gồm cả Super Stickers) được trình bày trong Trung tâm trợ giúp của YouTube. (Xem phần 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 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 trong cuộc thăm dò ý kiến. Thông số này chỉ xuất hiện nếu loại thông báopollEvent.
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.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. Giá trị này chỉ xuất hiện nếu message typemembershipGiftingEvent.
snippet.membershipGiftingDetails.giftMembershipsCount integer
Số lượng quà tặng gói hội viên mà người dùng đã mua.
snippet.membershipGiftingDetails.giftMembershipsLevelName string
Tên cấp độ của quà tặng gói hội viên mà người dùng đã mua. Tên cấp độ là 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.
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. Giá trị này chỉ xuất hiện nếu message typegiftMembershipReceivedEvent.
snippet.giftMembershipReceivedDetails.memberLevelName string
Tên của Cấp độ mà người xem đang là hội viên. Mã này khớp với snippet.membershipGiftingDetails.giftMembershipsLevelName của tin nhắn tặng gói hội viên có liên quan. Tên cấp độ là 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.
snippet.giftMembershipReceivedDetails.gifterChannelId string
Mã nhận dạng của người dùng đã thực hiện giao dịch mua quà tặng gói hội viên. Mã này khớp với snippet.authorChannelId của tin nhắn tặng gói hội viên có liên quan.
snippet.giftMembershipReceivedDetails.associatedMembershipGiftingMessageId string
Mã của tin nhắn 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 tham chiếu đến một thông báo có typemembershipGiftingEvent.
authorDetails object
Đối tượng authorDetails chứa thông tin chi tiết bổ sung về người dùng đã đăng tin nhắn này.
authorDetails.channelId string
Mã nhận dạng kênh YouTube của tác giả.
authorDetails.channelUrl string
URL kênh YouTube của tác giả.
authorDetails.displayName string
Tên hiển thị 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 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 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 cuộc trò chuyện trực tiếp hay không.