LiveChatMessages

يمثّل مورد liveChatMessage رسالة محادثة في محادثة مباشرة على YouTube. يمكن أن يحتوي المرجع على تفاصيل حول عدة أنواع من الرسائل، بما في ذلك رسالة نصية تم نشرها حديثًا أو حدث تمويل من المعجبين.

يتم تفعيل ميزة "المحادثة المباشرة" تلقائيًا لعمليات البث المباشر وتكون متاحة أثناء نشاط الحدث المباشر. (بعد انتهاء الحدث، لن تتوفّر ميزة المحادثة المباشرة لهذا الحدث).

الطُرق

تتيح واجهة برمجة التطبيقات الطرق التالية لموارد liveChatMessages:

list

تعرض هذه الطريقة رسائل المحادثة المباشرة لمحادثة معيّنة. التجربة الآن

streamList

تتيح هذه السمة إنشاء اتصال لبث المحتوى من الخادم بهدف تلقّي رسائل المحادثة المباشرة في محادثة معيّنة بوقت استجابة بطيء. التجربة الآن

إدراج

إضافة رسالة أو استطلاع إلى محادثة مباشرة التجربة الآن

transition

تغيير حالة رسالة مباشرة التجربة الآن

حذف

لحذف رسالة محادثة يجب أن يوافق مالك القناة أو مشرف المحادثة المباشرة على طلب البيانات من واجهة برمجة التطبيقات. التجربة الآن

تمثيل الموارد

تعرض بنية 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 تحدّد هذه السمة نوع مورد واجهة برمجة التطبيقات. ستكون القيمة youtube#liveChatMessage.
etag	etag تمثّل هذه السمة علامة Etag الخاصة بهذا المرجع.
id	string المعرّف الذي يحدّده YouTube لتحديد الرسالة بشكل فريد.
snippet	object يحتوي العنصر snippet على التفاصيل الأساسية حول رسالة المحادثة.
snippet.type	string نوع الرسالة. تكون هذه السمة متوفّرة دائمًا، وتحدّد قيمتها الحقول المتوفّرة في المرجع. القيم الصالحة لهذه السمة هي: chatEndedEvent: انتهت المحادثة ولا يمكن إدراج المزيد من الرسائل بعد هذه الرسالة. سيحدث ذلك تلقائيًا بعد فترة قصيرة من انتهاء البث. لا يتم إرسال هذا النوع من الرسائل للمحادثات المباشرة في البث التلقائي للقناة. messageDeletedEvent: تم حذف رسالة من قِبل مشرف. يحتوي الحقل author على تفاصيل المشرف. لا يحتوي هذا الحدث على أي محتوى معروض. sponsorOnlyModeEndedEvent: لم يعُد وضع "لأعضاء القناة فقط" مفعّلاً في المحادثة، ما يعني أنّه يمكن للمستخدمين غير الأعضاء إرسال الرسائل الآن. لا يحتوي هذا الحدث على أي محتوى معروض. sponsorOnlyModeStartedEvent – تم تفعيل وضع "الجهات الراعية فقط" في المحادثة، ما يعني أنّه يمكن للجهات الراعية فقط إرسال الرسائل. لا يتضمّن هذا الحدث أي محتوى للعرض. newSponsorEvent: قدّم مستخدم جديد عرضَ رعاية للقناة التي تملك المحادثة المباشرة. تحتوي الحقول author على تفاصيل الراعي الجديد. memberMilestoneChatEvent: أرسل أحد المستخدمين رسالة محادثة مميّزة خاصة بالأعضاء. superChatEvent: اشترى أحد المستخدمين رسالة Super Chat. superStickerEvent: اشترى مستخدم ملصق Super Sticker. ‫textMessageEvent: أرسل مستخدم رسالة نصية. ‫tombstone: يشير هذا الرمز إلى أنّ الرسالة كانت متوفّرة سابقًا بهذا المعرّف ووقت النشر، ولكن تم حذفها منذ ذلك الحين. لا يتم إرسالها عند حذف رسالة، بل يتم عرضها للإشارة إلى المكان الذي كانت الرسالة فيه قبل حذفها. تتضمّن هذه الأنواع من الرسائل الحقول snippet.liveChatId وsnippet.type وsnippet.publishedAt فقط. userBannedEvent: تم حظر مستخدم من قِبل مشرف. يحتوي الحقل author على تفاصيل المشرف. membershipGiftingEvent: اشترى مستخدم عضويات للمشاهدين الآخرين. ‫giftMembershipReceivedEvent: تلقّى مستخدم عضوية مقدَّمة كهدية. pollDetails: أنشأ مستخدم استطلاعًا مباشرًا.
snippet.liveChatId	string المعرّف الذي يحدّد بشكل فريد المحادثة المباشرة المرتبطة بالرسالة. يتم عرض معرّف المحادثة المباشرة المرتبط ببث في السمة snippet.liveChatId الخاصة بمورد liveBroadcast.
snippet.authorChannelId	string معرّف المستخدم الذي أنشأ الرسالة. يتم ملء هذا الحقل لأنواع الرسائل التالية فقط: إذا كان نوع الرسالة 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 ملاحظة: تم إيقاف هذا العنصر وخصائصه الفرعية نهائيًا. اعتبارًا من 28 شباط (فبراير) 2017، لن تعرض موارد 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 لرسالة SMS الأصلية. على سبيل المثال، إذا كانت الرسالة textMessageEvent تتضمّن قيمة الخاصية id وهي 123، وتم حذف هذه الرسالة لاحقًا، ستكون قيمة snippet.messageDeletedDetails.deletedMessageId هي 123 لهذه الرسالة. إذا كنت تخزّن رسائل المحادثة مؤقتًا بعد استردادها، استخدِم قيمة هذه الخاصية لتحديد الرسالة التي يجب ألا يتم عرضها بعد الآن.
snippet.userBannedDetails	object يحتوي هذا العنصر على تفاصيل حول مستخدم تم حظره من المحادثة. وتتضمّن أيضًا تفاصيل حول الحظر نفسه. يمكن حظر المستخدمين من محادثة بشكل دائم أو مؤقت.
snippet.userBannedDetails.bannedUserDetails	object يحتوي هذا العنصر على معلومات حول المستخدم المحظور.
snippet.userBannedDetails.bannedUserDetails.channelId	string معرّف قناة المستخدم المحظور على YouTube
snippet.userBannedDetails.bannedUserDetails.channelUrl	string تمثّل هذه السمة عنوان URL الخاص بقناة المستخدم المحظور على YouTube.
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 تمثّل هذه السمة مبلغ الشراء بوحدة الميكرو من عملة الشراء. على سبيل المثال، إذا كان مبلغ الشراء دولارًا واحدًا، تكون قيمة السمة 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 على هذه القيمة. يستند المستوى إلى المبلغ الذي تم إنفاقه لشراء الرسالة. يحدّد هذا المستوى أيضًا اللون المستخدَم لإبراز الرسالة في واجهة مستخدم المحادثة المباشرة، والحد الأقصى لطول الرسالة، ومدة تثبيت الرسالة في شريط التمرير. يمكنك الاطّلاع على مستويات Super Chat في مركز مساعدة YouTube. (اطّلِع على القسم القابل للتوسيع حول تفاصيل شراء رسائل Super Chat). في هذه القائمة، يكون المستوى الذي يتضمّن أدنى مبلغ شراء هو المستوى 1، والمستوى الذي يتضمّن ثاني أدنى مبلغ هو المستوى 2، وهكذا.
snippet.superStickerDetails	object يحتوي هذا العنصر على تفاصيل حول حدث "ملصقات Super Stickers". تظهر هذه السمة فقط إذا كان نوع الرسالة هو superStickerEvent.
snippet.superStickerDetails.superStickerMetadata	object تفاصيل حول "الملصق العجيب"
snippet.superStickerDetails.superStickerMetadata.stickerId	string معرّف فريد يحدّد صورة الملصق. يُرجى العِلم أنّ الصورة لا تظهر إلا كجزء من رسالة "الملصق العجيب" عندما يعرض المستخدمون نافذة المحادثة على YouTube. ومع ذلك، لا يتوفّر عنوان URL للصورة باستخدام واجهة برمجة التطبيقات. للمرجعية فقط، يمكنك الاطّلاع على أرقام تعريف الملصقات المرتبطة بالملصقات العجيبة في ملف CSV هذا.
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 تمثّل هذه السمة مبلغ الشراء بوحدة الميكرو من عملة الشراء. على سبيل المثال، إذا كان مبلغ الشراء دولارًا واحدًا، تكون قيمة السمة snippet.amountMicros هي 1000000.
snippet.superStickerDetails.currency	string تمثّل هذه السمة العملة التي تمّت بها عملية الشراء. القيمة هي رمز عملة ISO 4217.
snippet.superStickerDetails.amountDisplayString	استبدِل string بسلسلة، مثل $1.00، تحتوي على مبلغ الشراء والعملة. والغرض من السلسلة هو عرضها للمستخدم.
snippet.superStickerDetails.tier	unsigned integer تمثّل هذه السمة مستوى الرسالة المدفوعة. يُرجى العِلم أنّه في مورد superChatEvent، تحتوي السمة snippet.messageType على هذه القيمة. يستند المستوى إلى المبلغ الذي تم إنفاقه لشراء الرسالة. ويحدّد أيضًا اللون المستخدَم لإبراز الرسالة في واجهة مستخدم المحادثة المباشرة، والحدّ الأقصى لطول الرسالة، ومدة تثبيت الرسالة في شريط التمرير. يمكنك الاطّلاع على مستويات Super Chat، التي تشمل أيضًا Super Stickers، في مركز مساعدة 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 تمثّل هذه السمة عدد الأصوات التي حصل عليها خيار الاستطلاع المباشر. لا يظهر عدد الأصوات إلا إذا كان طلب البيانات من واجهة برمجة التطبيقات مصرحًا به من قِبل مالك القناة.
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 تمثّل هذه السمة رقم تعريف المستخدم الذي أجرى عملية شراء هدايا العضوية. يتطابق هذا الرمز مع snippet.authorChannelId في رسالة إهداء العضوية المرتبطة به.
snippet.giftMembershipReceivedDetails.associatedMembershipGiftingMessageId	string تمثّل هذه السمة معرّف الرسالة التي تم إرسالها لإهداء العضوية. سيشير هذا المعرّف دائمًا إلى رسالة يكون type فيها هو membershipGiftingEvent.
authorDetails	object يحتوي العنصر authorDetails على تفاصيل إضافية حول المستخدم الذي نشر هذه الرسالة.
authorDetails.channelId	string تمثّل هذه السمة معرّف قناة المؤلف على YouTube.
authorDetails.channelUrl	string تمثّل هذه السمة عنوان URL الخاص بقناة المؤلف على YouTube.
authorDetails.displayName	string الاسم المعروض لقناة المؤلف على YouTube
authorDetails.profileImageUrl	string تمثّل هذه السمة عنوان URL الخاص بأفاتار قناة المؤلف على YouTube.
authorDetails.isVerified	boolean تشير هذه القيمة إلى ما إذا كان YouTube قد تحقّق من هوية المؤلف.
authorDetails.isChatOwner	boolean تشير هذه القيمة إلى ما إذا كان المؤلف هو مالك المحادثة المباشرة.
authorDetails.isChatSponsor	boolean تشير هذه القيمة إلى ما إذا كان المؤلف راعيًا للمحادثة المباشرة.
authorDetails.isChatModerator	boolean تشير هذه القيمة إلى ما إذا كان المؤلف مشرفًا على المحادثة المباشرة.