دریافت رویدادها

نماینده شما رویدادهای وب‌قلاب را از پلاتفرم RBM دریافت می‌کند و شما را از تعاملات کاربر و به‌روزرسانی‌های سطح پلاتفرم مطلع می‌کند.

این رویدادها براساس منشأشان دسته‌بندی می‌شوند:

  • رویدادهای کاربر: اعلان‌هایی که از دستگاه کاربر به نماینده شما ارسال می‌شود و نشان‌دهنده تعامل با نماینده شما است.
  • رویدادهای پلاتفرم: اعلان‌های مربوط به تغییرات وضعیت راه‌اندازی نماینده و انقضای پیام که توسط پلاتفرم RBM ارسال می‌شود.

برای جزئیات مربوط به رویدادهای وضعیتی که نماینده شما به دستگاه کاربر ارسال می‌کند، ارسال رویدادها را ببینید.

برای جزئیات مربوط به نحوه مدیریت پیام‌های کاربر، مانند نوشتار، فایل‌ها، مکان‌ها، و موارد دیگر، به دریافت پیام‌ها مراجعه کنید.

رویدادهای کاربر

رویدادهای کاربر اعلان‌هایی از دستگاه کاربر هستند که وضعیت پیام یا تغییرات اشتراک را گزارش می‌کنند (یعنی کاربر در «پیام‌نگار Google» لغو اشتراک کرده یا دوباره مشترک شده است).

برای مشاهده گزینه‌های کامل قالب‌بندی و مقدار، به مرجع UserEvent مراجعه کنید.

کاربر پیام نماینده را دریافت می‌کند

این رویداد نشان می‌دهد که پیام با موفقیت به دستگاه کاربر ارسال شده است.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "DELIVERED",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

کاربر پیام نماینده را می‌خواند

این رویداد نشان می‌دهد که پیامی باز شده یا تأیید شده است.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "READ",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

کاربر شروع به تایپ می‌کند

این رویداد نشان می‌دهد که کاربر درحال تایپ کردن پاسخ است.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "IS_TYPING",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

کاربر روی کنش پیشنهادی ضربه می‌زند

وقتی کاربر روی کنش پیشنهادی تک‌ضرب می‌زند، نماینده شما رویدادی با داده‌های پس‌فرست کنش دریافت می‌کند.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

کاربر اشتراک مکالمه را لغو می‌کند

این رویداد نشان می‌دهد که کاربر اشتراک خود را برای دریافت پیام‌های غیرضروری، مانند تبلیغات، از نماینده شما و کسب‌وکاری که نماینده آن است لغو کرده است. کاربران با لغو اشتراک از مکالمه «پیام‌نگاری برای کسب‌وکار» در «پیام‌نگار Google» این رویداد را راه‌اندازی می‌کنند.

در اینجا نمونه‌ای از پایه‌بار JSON آورده شده است:

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "UNSUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

نحوه عملکرد لغو اشتراک

  • گزینه لغو اشتراک همیشه در منو گپ دردسترس است. برای نماینده‌های تبلیغاتی و چندمنظوره، این گزینه همچنین مستقیماً در گپ پس‌از تعداد مشخصی پیام خوانده‌نشده ظاهر می‌شود (قوانین خاص براساس کشور متفاوت است).
  • انتخاب لغو اشتراک دو کنش هم‌زمان را راه‌اندازی می‌کند: «پیام‌نگار Google» یک کلیدواژه مختص کشور (برای مثال، «توقف») به نماینده شما ارسال می‌کند، و پلاتفرم RBM یک رویداد UNSUBSCRIBE به وب‌قلاب شما ارسال می‌کند.

    کلیدواژه براساس کد کشور دوحرفی شماره تلفن کاربر تعیین می‌شود. جدول زیر کلیدواژه‌های هر کشور پشتیبانی‌شده را فهرست می‌کند.

    کشور (کد کشور) کلیدواژه لغو اشتراک
    ایالات متحده (US)، پادشاهی متحد (GB)، آلمان (DE)، هلند (NL)، هند (IN) STOP
    اسپانیا (ES)، مکزیک (MX) BAJA
    فرانسه (FR) STOP
    برزیل (BR) parar
  • پس‌از اینکه کاربر لغو اشتراک کرد، مکالمه در صندوق ورودی او باقی می‌ماند مگر اینکه به‌عنوان هرزنامه گزارش شود که دراین‌صورت به پوشه هرزنامه و مسدودشده منتقل می‌شود.

  • برای شناسایی نقض خط‌مشی و قانون کسب‌وکار، Google الگوهای پیام را پس‌از لغو اشتراک کاربر پایش می‌کند.

قوانین کسب‌وکار

  • به‌عنوان شریک RBM که این مکالمه را مدیریت می‌کند، مسئولیت شما است که از درخواست کاربر برای لغو اشتراک پیروی کنید.
  • اگر نمی‌توانید لغو اشتراک را در رشته پیام انجام دهید، باید فوراً پیام تأییدی با پیوند مستقیم به وب‌سایت یا برنامه‌ای که کاربران می‌توانند اولویت‌های اشتراک خود را در آن مدیریت کنند ارسال کنید.
  • پس‌از لغو اشتراک کاربر، ارسال پیام‌های غیرضروری ممنوع است.
  • پیام‌های ضروری همچنان مجاز است. این موارد عبارت‌اند از:
    • اصالت‌سنجی‌ها، مانند گذرواژه‌های یک‌بارمصرف (OTP)
    • اعلان‌های مربوط به سرویس خاصی که کاربر درخواست کرده و با آن موافقت کرده است
    • تأیید درخواست لغو اشتراک کاربر، با اطلاعاتی برای مدیریت بیشتر اولویت‌های ارتباطی او

مثال

اگر کاربری اشتراک خود را از نماینده خطوط هوایی که مورد استفاده آن چندمنظوره است لغو کند، باید ارسال پیام‌های بازاریابی را متوقف کنید. بااین‌حال، اگر کاربر صریحاً با دریافت به‌روزرسانی‌های مربوط به پرواز خاصی موافقت کرده باشد، می‌توانید به‌روزرسانی‌های پرواز را ارسال کنید.

دلایل لغو اشتراک

وقتی کاربری اشتراک خود را از نماینده شما لغو می‌کند، می‌تواند دلیلی را از گزینه‌های زیر انتخاب کند:

  • تعداد پیام‌ها خیلی زیاد است
  • من هرگز برای این ثبت‌نام نکرده‌ام
  • دیگر علاقه ندارم
  • به‌نظر می‌رسد فریبکاری باشد
  • غیره

برای کاهش سوگیری انتخاب، چهار گزینه اول به‌صورت تصادفی برای هر کاربر نمایش داده می‌شود. این ترتیب در بازدیدهای کاربر ثابت می‌ماند و سایر در پایین ثابت می‌ماند.

دلایل لغو اشتراک جمع‌آوری می‌شود و در نمای کلی Analytics نشان داده می‌شود تا به شما کمک کند دلیل لغو اشتراک کاربران را متوجه شوید.

کاربر دوباره در مکالمه مشترک می‌شود

این رویداد نشان می‌دهد که کاربر می‌خواهد دوباره از نماینده شما پیام دریافت کند، ازجمله محتوای غیرضروری مانند تبلیغات. کاربران می‌توانند با مشترک شدن مجدد در مکالمه‌ای که قبلاً در «پیام‌نگار Google» اشتراک آن را لغو کرده‌اند، این رویداد را راه‌اندازی کنند.

در اینجا نمونه‌ای از پایه‌بار JSON آورده شده است:

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "SUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

نحوه عملکرد ازسرگرفتن اشتراک

  • گزینه مشترک شدن که هم از منو گپ و هم از پیوند درون گپ دردسترس است، به کاربران امکان می‌دهد دوباره در مکالمه‌ای که اشتراک آن را لغو کرده بودند مشترک شوند.
  • با انتخاب مشترک شدن، دو کنش هم‌زمان راه‌اندازی می‌شود: «پیام‌نگار Google» کلیدواژه مختص کشور (برای مثال، «START») را به نماینده‌تان ارسال می‌کند، و پلاتفرم RBM رویداد «مشترک شدن» را به وب‌قلاب شما ارسال می‌کند. کلیدواژه خاص با کد کشور دوحرفی شماره تلفن کاربر تعیین می‌شود. جدول زیر کلیدواژه‌های هر کشور پشتیبانی‌شده را فهرست می‌کند.

    کشور (کد کشور) کلیدواژه مشترک شدن
    ایالات متحده (US)، پادشاهی متحد (GB)، آلمان (DE)، هلند (NL)، هند (IN) شروع
    اسپانیا (ES)، مکزیک (MX) ALTA
    فرانسه (FR) Démarrer
    برزیل (BR) começar

قوانین کسب‌وکار

  • به‌عنوان شریک RBM که این مکالمه را مدیریت می‌کند، مسئولیت شما است که از درخواست کاربر برای ازسرگرفتن اشتراک پیروی کنید.
  • ازسرگیری اشتراک برای همه انواع پیام، ازجمله محتوای غیرضروری مثل عرضه‌های ترویجی، اعمال می‌شود.
  • اگر کاربری پس‌از لغو اشتراک به کسب‌وکار شما پیام دهد، این پیام می‌تواند به‌عنوان درخواست ازسرگرفتن اشتراک درنظر گرفته شود.
  • اگر کاربری خارج از کانال پیام‌رسانی (مثلاً در وب‌سایت شما) اشتراک را ازسر بگیرد، مسئولیت شما به‌عنوان شریک RBM است که وضعیت او را به‌روز کنید و ارسال پیام‌ها را مطابق با آن ازسر بگیرید.

رویدادهای پلاتفرم

پلاتفرم RBM رویدادهای پلاتفرم را ارسال می‌کند تا به نماینده شما درباره تغییرات در وضعیت راه‌اندازی نماینده یا انقضای پیام اطلاع دهد.

وضعیت راه‌اندازی نماینده تغییر کرده است

پلاتفرم RBM برای هر تغییری در وضعیت راه‌اندازی نماینده‌تان، AgentLaunchEvent ارسال می‌کند. برای مثال، وقتی وضعیت نماینده‌تان از PENDING به LAUNCHED تغییر می‌کند. رویداد به‌عنوان پیام Pub/Sub ارسال می‌شود. برای متمایز کردن این رویداد از رویدادهای دیگر، مسیر message.attributes.type را برای مقدار agent_launch_event بررسی کنید.

پیکربندی وب‌قلاب

می‌توانید از وب‌قلاب سطح شریک یا سطح نماینده برای دریافت این اعلان‌ها استفاده کنید.

پیش‌نیازها

ساختار بار داده رویداد

AgentLaunchEvent به‌عنوان پیام Pub/Sub ارسال می‌شود.

مثالی در اینجا ارائه شده است:

{
  "message": {
    "attributes": {
      "business_id": "rbm-chatbot-id@rbm.goog",
      "event_type": "REJECTED",
      "product": "RBM",
      "project_number": "3338881441851",
      "type": "agent_launch_event"
    },
    "data": "....BASE64-encoded-JSON-with-notification...",
    "messageId": "14150481888479752",
    "message_id": "14150481888479752",
    "publishTime": "2025-03-05T18:50:21.88Z",
    "publish_time": "2025-03-05T18:50:21.88Z"
  },
  "subscription": "projects/rbm-partner-gcp/subscriptions/rbm-sub"
}

فیلد AgentLaunchEvent.LaunchState در بار داده رویداد نشان‌دهنده وضعیت راه‌اندازی جدید نماینده است. مقادیر ممکن از این قرار است:

مقدار وضعیت راه‌اندازی عامل جزئیات
PENDING درانتظار درخواست برای بررسی به شرکت مخابراتی ارسال شده است.
LAUNCHED راه‌اندازی‌شده پیام‌ها در شرکت مخابراتی خاصی مجاز است.
REJECTED در شرکت مخابراتی مشخصی رد شده است دلیل رد شدن در نظر مشخص شده است.
SUSPENDED در شرکت مخابراتی خاصی تعلیق شده است دلیل تعلیق در نظر مشخص شده است.
UNLAUNCHED راه‌اندازی‌نشده ویرایش برای نمایندگانی که از همه شرکت‌های مخابراتی لغو راه‌اندازی شده‌اند مجاز است.

فیلد داده حاوی شیء JSON با کدبندی Base64 با جزئیات وضعیت راه‌اندازی است. در اینجا نمونه‌ای از JSON رمزگشایی‌شده آورده شده است:

 {
      "eventId": "rbm-chatbot-id/0a7ed168-676e-4a56-b422-b23434",
      "agentId": "rbm-chatbot-id@rbm.goog",
      "botDisplayName": "RBM Welcome Bot 7 - RBM Chatbot name",
      "brandId": "bd38fbff-392a-437b-a6f2-7f2e43745b56",
      "brandDisplayName": "Chatbots brand",
      "regionId": "/v1/regions/fi-rcs",
      "oldLaunchState": "PENDING",
      "newLaunchState": "REJECTED",
      "actingParty": "rbm-support@google.com",
      "comment": "Carrier has rejected the launch: policy violation",
      "sendTime": "2025-03-05T18:50:19.386436Z"
}

تغییرات وضعیت راه‌اندازی شروع‌شده توسط شرکت مخابراتی

این‌ها انتقال‌های مجاز هستند که معمولاً توسط شرکت‌های مخابراتی درطول فرایند بازبینی و اجرا انجام می‌شوند:

وضعیت راه‌اندازی قدیمی وضعیت راه‌اندازی جدید راه‌اندازی کنش
PENDING LAUNCHED درخواست راه‌اندازی را تأیید کنید.
PENDING REJECTED رد کردن درخواست راه‌اندازی.
LAUNCHED SUSPENDED به‌دلایل اجرایی/سرپرستی تعلیق کنید.
SUSPENDED LAUNCHED بازگرداندن عامل به وضعیت فعال.
SUSPENDED UNLAUNCHED عاملی را فسخ کنید.
REJECTED LAUNCHED تأیید درخواست راه‌اندازی که قبلاً رد شده است.

تغییرات وضعیت راه‌اندازی شروع‌شده توسط شریک

این‌ها انتقال‌های مجاز هستند که معمولاً توسط «شرکا» انجام می‌شوند:

وضعیت راه‌اندازی قدیمی وضعیت راه‌اندازی جدید راه‌اندازی کنش
UNSPECIFIED PENDING برای بازبینی ارسال کنید.
PENDING UNLAUNCHED لغو کردن درخواست راه‌اندازی معلقه.
UNLAUNCHED PENDING برای بازبینی ارسال کنید.
REJECTED PENDING برای بازبینی دوباره ارسال کنید.
SUSPENDED PENDING برای بازبینی دوباره ارسال کنید.

پیام منقضی شده است؛ لغو با موفقیت انجام شد

این رویداد نشان می‌دهد که زمان زندگی (TTL) پیام منقضی شده است و پیام با موفقیت لغو شده است. این محرک خوبی برای استراتژی پیام‌رسانی جایگزین شما است.

برای مشاهده گزینه‌های کامل قالب‌بندی و مقدار، به مرجع ServerEvent مراجعه کنید.

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

پیام منقضی شده است؛ لغو ناموفق بود

این رویداد نشان می‌دهد که TTL پیام منقضی شده است، اما با موفقیت لغو نشده است.

برای مشاهده گزینه‌های کامل قالب‌بندی و مقدار، به مرجع ServerEvent مراجعه کنید.

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

تحویل پیام تضمین نمی‌شود.

  • اگر پیام تحویل داده شده باشد، رویداد DELIVERED را در وب‌قلاب خود دریافت خواهید کرد.
  • اگر پیام تحویل داده نشده است، از API لغو برای ارسال درخواست لغو استفاده کنید.

اگر پیام حساس به زمان است، مثل گذرواژه یک‌بارمصرف یا هشدار کلاهبرداری، بهتر است پیام را ازطریق کانال جایگزینی مثل پیامک ارسال کنید، حتی اگر این کار منجر به ارسال پیام‌های تکراری به کاربر شود.