LiveChatMessages

منبع liveChatMessage نشان‌دهنده پیام گپ در گپ مستقیم YouTube است. این منبع می‌تواند حاوی جزئیاتی درباره انواع مختلف پیام‌ها باشد، ازجمله پیام متنی جدیداً پست‌شده یا رویداد تأمین بودجه طرفداران.

ویژگی گپ مستقیم به‌طور پیش‌فرض برای پخش‌های زنده فعال است و درحین فعال بودن رویداد زنده دردسترس است. (پس‌از پایان رویداد، گپ مستقیم دیگر برای آن رویداد دردسترس نیست.)

روش‌ها

«میانای برنامه‌سازی کاربردی» از روش‌های زیر برای منابع liveChatMessages پشتیبانی می‌کند:

فهرست
پیام‌های گپ مستقیم را برای گپ خاصی فهرست می‌کند. اکنون امتحان کنید.
streamList
اتصال جاری‌سازی سرور را برای دریافت پیام‌های گپ مستقیم برای گپ خاصی با تأخیر کم فعال می‌کند. اکنون امتحان کنید.
درج
پیام یا نظرسنجی را به گپ مستقیم اضافه می‌کند. اکنون امتحان کنید.
transition
وضعیت پیام مستقیم را تغییر می‌دهد. اکنون امتحان کنید.
حذف
پیام گپ را حذف می‌کند. درخواست API باید توسط مالک کانال یا یک مدیر گپ زنده مجاز شود. اکنون امتحان کنید.

وکالت منابع

ساختار 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
توجه: این شیء و ویژگی‌های فرزند آن منسوخ شده‌اند. از تاریخ ۲۸ فوریه ۲۰۱۷، 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
نشانی وب کانال 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 را ببینید.) در این فهرست، سطحی که کمترین مبلغ خرید را دارد سطح ۱ است، مبلغ بعدی سطح ۲ است، و به همین ترتیب.
snippet.superStickerDetails object
این شیء حاوی جزئیات مربوط به رویداد Super Sticker است. این فیلد فقط درصورتی وجود دارد که نوع پیام superStickerEvent باشد.
snippet.superStickerDetails.superStickerMetadata object
جزئیات مربوط به Super Sticker.
snippet.superStickerDetails.superStickerMetadata.stickerId string
شناسه یکتایی که تصویر برچسب را شناسایی می‌کند. توجه داشته باشید که تصویر فقط به‌عنوان بخشی از پیام Super Sticker نمایش داده می‌شود زمانی که کاربران پنجره گپ را در YouTube مشاهده می‌کنند. بااین‌حال، نشانی وب تصویر بااستفاده از API دردسترس نیست. فقط برای مرجع، می‌توانید در این فایل CSV ببینید کدام شناسه‌های برچسب به کدام Super Sticker مربوط می‌شوند.
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 را ببینید.) در آن فهرست، سطح با کمترین مقدار خرید سطح ۱، سطح با مقدار خرید بعدی سطح ۲، و به همین ترتیب ادامه می‌یابد.
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
تعداد آرای گزینه نظرسنجی زنده. این شمارش تنها زمانی وجود دارد که درخواست API توسط مالک کانال مجاز شده باشد.
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
نشانی وب دارایی هدیه.
snippet.giftDetails.giftDuration object
مدت زمان نمایش نشانی وب هدیه.
snippet.giftDetails.giftDuration.seconds integer
تعداد ثانیه‌هایی که نشانی وب هدیه نمایش داده می‌شود.
snippet.giftDetails.giftDuration.nanos integer
تعداد نانوثانیه‌ها برای نمایش نشانی وب هدیه.
snippet.giftDetails.hasVisualEffect boolean
اینکه هدیه جلوه دیداری دارد یا نه.
snippet.giftDetails.comboCount integer
تعداد مجموعه هدیه؛ اگر مجموعه هدیه نباشد، ۰ است.
snippet.giftDetails.altText string
رشته نوشتاری که هدیه را توصیف می‌کند.
snippet.giftDetails.language string
زبان مقدار خصوصیت altText.
authorDetails object
شیء authorDetails حاوی جزئیات بیشتری درباره کاربری است که این پیام را پست کرده است.
authorDetails.channelId string
شناسه کانال YouTube نویسنده.
authorDetails.channelUrl string
نشانی وب کانال YouTube نویسنده.
authorDetails.displayName string
نام نمایشی کانال YouTube نویسنده.
authorDetails.profileImageUrl string
نشانی وب چهرک کانال YouTube نویسنده.
authorDetails.isVerified boolean
این مقدار نشان می‌دهد که آیا هویت نویسنده توسط YouTube تأیید شده است یا خیر.
authorDetails.isChatOwner boolean
این مقدار نشان می‌دهد که آیا نویسنده مالک گپ مستقیم است یا نه.
authorDetails.isChatSponsor boolean
این مقدار نشان می‌دهد که آیا نویسنده حامی مالی گپ مستقیم است یا نه.
authorDetails.isChatModerator boolean
این مقدار نشان می‌دهد که آیا نویسنده گرداننده گپ مستقیم است یا نه.