LiveChatMessages

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

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

الطُرق

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

list

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

إدراج

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

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 – اشترى مستخدم ملصقًا عجيبًا. 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 للرسالة النصية الأصلية. على سبيل المثال، إذا كانت قيمة سمة id في textMessageEvent هي 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 يحتوي هذا العنصر على تفاصيل عن حدث "ملصق رائع". ولا تظهر هذه السمة إلا إذا كان نوع الرسالة هو 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 على هذه القيمة. يستند المستوى إلى المبلغ الذي تم إنفاقه لشراء الرسالة. ويحدّد هذا المبلغ أيضًا اللون المستخدَم لإبراز الرسالة في واجهة مستخدم المحادثة المباشرة والحد الأقصى لطول الرسالة والمدة التي يتم فيها تثبيت الرسالة في شريط الأسعار. يمكنك الاطّلاع على مركز مساعدة YouTube للاطّلاع على فئات Super Chat التي تشمل أيضًا "الملصقات العجيبة". (اطّلِع على القسم القابل للتمديد حول تفاصيل شراء رسائل 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 تشير هذه القيمة إلى ما إذا كان المؤلف مشرفًا في المحادثة المباشرة.