LiveChatMessages

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

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

الطُرق

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

list
تعرض هذه الطريقة رسائل المحادثة المباشرة لمحادثة معيّنة. التجربة الآن
streamList
تتيح هذه السمة إنشاء اتصال لبث المحتوى من الخادم بهدف تلقّي رسائل المحادثة المباشرة في محادثة معيّنة بزمن انتقال منخفض. التجربة الآن
insert
إضافة رسالة أو استطلاع إلى محادثة مباشرة التجربة الآن
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
    },
    "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
  },
}

الخصائص

يحدّد الجدول التالي السمات التي تظهر في هذا المرجع:

الخصائص
kind string
تحدّد هذه السمة نوع مورد واجهة برمجة التطبيقات. ستكون القيمة youtube#liveChatMessage.
etag etag
تمثّل هذه السمة علامة Etag لهذا المورد.
id string
المعرّف الذي يخصّصه YouTube لتحديد الرسالة بشكل فريد.
ملاحظة: بالنسبة إلى giftEvents، يمكن إعادة استخدام المعرّف نفسه لتعديل عدد الهدايا المتتالية.
snippet object
يحتوي العنصر snippet على تفاصيل أساسية حول رسالة المحادثة.
snippet.type string
نوع الرسالة تكون هذه السمة متوفّرة دائمًا، وتحدّد قيمتها الحقول المتوفّرة في المورد.

في ما يلي القيم الصالحة لهذه السمة:
  • ‫chatEndedEvent: انتهت المحادثة ولا يمكن إدراج المزيد من الرسائل بعد هذه الرسالة. سيحدث ذلك بشكل طبيعي بعد فترة قصيرة من انتهاء البث. لا يتم إرسال هذا النوع من الرسائل للمحادثات المباشرة في البث التلقائي للقناة.
  • ‫sponsorOnlyModeEndedEvent: لم تعُد المحادثة في وضع "الرعاة فقط"، ما يعني أنّه أصبح بإمكان المستخدمين غير الرعاة إرسال الرسائل. لا يتضمّن هذا الحدث أي محتوى للعرض.
  • sponsorOnlyModeStartedEvent: تم تفعيل وضع "الجهات الراعية فقط" في الدردشة، ما يعني أنّه يمكن للجهات الراعية فقط إرسال الرسائل. لا يتضمّن هذا الحدث أي محتوى للعرض.
  • ‫newSponsorEvent: قدّم مستخدم جديد عرض رعاية للقناة التي تملك المحادثة المباشرة. تحتوي حقول author على تفاصيل الراعي الجديد.
  • memberMilestoneChatEvent – أرسل مستخدم رسالة محادثة مميّزة خاصة بالأعضاء.
  • ‫superChatEvent: اشترى مستخدم رسالة Super Chat.
  • ‫superStickerEvent: اشترى مستخدم ملصق Super Sticker.
  • textMessageEvent: أرسل مستخدم رسالة نصية.
  • tombstone – يشير هذا الرمز إلى أنّ الرسالة كانت تتضمّن هذا المعرّف ووقت النشر، ولكن تم حذفها منذ ذلك الحين. ولا يتم إرسالها عند حذف رسالة، بل يتم عرضها للإشارة إلى مكان الرسالة قبل حذفها. لا تتوفّر سوى الحقول snippet.liveChatId وsnippet.type وsnippet.publishedAt في هذا النوع من الرسائل.
  • userBannedEvent: تم حظر مستخدم من قِبل مشرف. يحتوي الحقل author على تفاصيل المشرف.
  • ‫membershipGiftingEvent: اشترى مستخدم عضويات لمشاهدين آخرين.
  • ‫giftMembershipReceivedEvent: تلقّى مستخدم عضوية مقدَّمة كهدية.
  • ‫pollDetails: أنشأ مستخدم استطلاعًا مباشرًا.
  • ‫giftEvent: استبدل مستخدم "الجواهر" بهدية.
snippet.liveChatId string
المعرّف الفريد للمحادثة المباشرة المرتبطة بالرسالة. يتم عرض معرّف المحادثة المباشرة المرتبط ببث في السمة snippet.liveChatId للمورد liveBroadcast.
snippet.authorChannelId string
رقم تعريف المستخدم الذي كتب الرسالة لا يتم ملء هذا الحقل إلا لأنواع الرسائل التالية:
  • إذا كان نوع الرسالة هو textMessageEvent، تحدّد قيمة السمة المستخدم الذي كتب الرسالة.
  • إذا كان نوع الرسالة هو fanFundingEvent، تحدّد قيمة السمة المستخدم الذي موّل البث.
  • إذا كان نوع الرسالة هو newSponsorEvent، تحدّد قيمة السمة المستخدم الذي أصبح راعيًا للتو.
  • إذا كان نوع الرسالة هو memberMilestoneChatEvent، تحدّد قيمة السمة العضو الذي أرسل الرسالة.
  • إذا كان نوع الرسالة هو userBannedEvent، تحدّد قيمة السمة المشرف الذي حظر المستخدم.
  • إذا كان نوع الرسالة هو membershipGiftingEvent، تحدّد قيمة السمة المستخدم الذي اشترى إهداء العضوية.
  • إذا كان نوع الرسالة هو giftMembershipReceivedEvent، تحدّد قيمة السمة المستخدم الذي تلقّى العضوية المقدَّمة كهدية.
  • إذا كان نوع الرسالة هو pollEvent، تحدّد قيمة السمة المستخدم الذي أنشأ استطلاعًا مباشرًا.
  • إذا كان نوع الرسالة هو giftEvent، تحدّد قيمة السمة المستخدم الذي أرسل الهدية.
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.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
تمثّل هذه السمة مستوى الرسالة المدفوعة. يُرجى العِلم أنّ السمة snippet.messageType في مورد superChatEvent تحتوي على هذه القيمة.

تستند الفئة إلى المبلغ الذي تم إنفاقه لشراء الرسالة. يحدّد هذا المستوى أيضًا اللون المستخدَم لإبراز الرسالة في واجهة مستخدم المحادثة المباشرة، والحد الأقصى لطول الرسالة، ومدة تثبيت الرسالة في شريط التمرير.

يمكنك الاطّلاع على مستويات Super Chat في مركز مساعدة YouTube. (راجِع القسم القابل للتوسيع حول تفاصيل شراء Super Chat). في هذه القائمة، تكون الفئة التي تتضمّن أقل مبلغ شراء هي الفئة 1، والمبلغ التالي الأقل هو الفئة 2، وهكذا.
snippet.superStickerDetails object
يحتوي هذا العنصر على تفاصيل حول حدث Super Sticker. ويظهر فقط إذا كان نوع الرسالة هو superStickerEvent.
snippet.superStickerDetails.superStickerMetadata object
تفاصيل حول Super Sticker
snippet.superStickerDetails.superStickerMetadata.stickerId string
معرّف فريد يحدّد صورة الملصق يُرجى العِلم أنّ الصورة لا تظهر إلا كجزء من رسالة Super Sticker عندما يشاهد المستخدمون نافذة المحادثة على YouTube. ومع ذلك، لا يتوفّر عنوان URL للصورة باستخدام واجهة برمجة التطبيقات. للاطّلاع فقط، يمكنك العثور على معرّفات الملصقات المرتبطة بملصقات Super Stickers في ملف 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
تمثّل هذه السمة مستوى الرسالة المدفوعة. يُرجى العِلم أنّ السمة snippet.messageType في مورد superChatEvent تحتوي على هذه القيمة.

تستند الفئة إلى المبلغ الذي تم إنفاقه لشراء الرسالة. ويحدّد أيضًا اللون المستخدَم لإبراز الرسالة في واجهة مستخدم المحادثة المباشرة، والحدّ الأقصى لطول الرسالة، والمدة التي يتم فيها تثبيت الرسالة في شريط الأخبار.

يتم توثيق مستويات 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.
snippet.giftDetails object
يحتوي هذا العنصر على تفاصيل حول حدث تقديم هدية. لا تظهر هذه السمة إلا إذا كانت قيمة message type هي giftEvent.
snippet.giftDetails.jewelsAmount integer
تمثّل هذه السمة عدد "الجواهر" التي تمّ تحصيل قيمتها مقابل الهدية.
snippet.giftDetails.giftName string
تمثّل هذه السمة اسم الهدية.
snippet.giftDetails.giftUrl string
عنوان URL لمادة عرض الهدية
snippet.giftDetails.giftDuration object
مدة عرض عنوان URL للهدية.
snippet.giftDetails.giftDuration.seconds integer
عدد الثواني التي سيتم فيها عرض عنوان URL الخاص بالهدية.
snippet.giftDetails.giftDuration.nanos integer
عدد النانو ثانية لعرض عنوان URL الخاص بالهدية.
snippet.giftDetails.hasVisualEffect boolean
ما إذا كانت الهدية تتضمّن تأثيرًا بصريًا
snippet.giftDetails.comboCount integer
عدد الهدايا المجمّعة، ويتم ضبطه على 0 إذا لم تكن هدية مجمّعة.
snippet.giftDetails.altText string
سلسلة نصية تصف الهدية
snippet.giftDetails.language string
لغة قيمة السمة altText.
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
تشير هذه القيمة إلى ما إذا كان المؤلف مشرفًا على المحادثة المباشرة.