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

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

این رویدادها بر اساس منشأ آنها طبقه‌بندی می‌شوند:

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

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

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

رویدادهای کاربر، اعلان‌هایی از دستگاه کاربر هستند که وضعیت پیام یا تغییرات اشتراک را گزارش می‌دهند (مثلاً کاربر در پیام‌های گوگل اشتراک خود را لغو یا دوباره اشتراک گرفته است).

برای گزینه‌های کامل قالب‌بندی و مقداردهی، به مرجع 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",
  "text": "Hi",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

کاربر یک فایل ارسال می‌کند 

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "userFile": {
    "payload": {
      "mimeType": "image/gif",
      "fileSizeBytes": 127806,
      "fileUri": "https://storage.googleapis.com/copper_test/77ddb795-24ad-4607-96ae-b08b4d86406a/d2dcc67ab888d34ee272899c020b13402856f81597228322079eb007e8c9",
      "fileName": "4_animated.gif"
    }
  },
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

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

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

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234",
    "text": "Hello there!"
  }
}

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

وقتی کاربری روی یک اقدام پیشنهادی ضربه می‌زند، عامل شما رویدادی حاوی داده‌های postback آن اقدام دریافت می‌کند.

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

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

این رویداد نشان می‌دهد که کاربر از دریافت پیام‌های غیرضروری، مانند تبلیغات، از نماینده شما و کسب‌وکاری که نماینده آن است، انصراف داده است. کاربران با لغو اشتراک از مکالمه RBM در پیام‌های گوگل، این رویداد را فعال می‌کنند.

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

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

نحوه لغو اشتراک

  • گزینه لغو اشتراک همیشه در منوی چت موجود است. برای نمایندگان تبلیغاتی و چندمنظوره، این گزینه همچنین پس از تعداد مشخصی از پیام‌های خوانده نشده، مستقیماً در چت ظاهر می‌شود (قوانین خاص در هر کشور متفاوت است).

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

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

    کشور (کد کشور) لغو اشتراک، کلمه کلیدی
    ایالات متحده، هند، بریتانیا، آلمان ایست
    اسپانیا (ES)، مکزیک (MX) باخا
    فرانسه (FR) ایست
    برزیل (BR) پارار

  • پس از لغو اشتراک کاربر، مکالمه در صندوق ورودی او باقی می‌ماند، مگر اینکه به عنوان هرزنامه گزارش شود که در این صورت به پوشه هرزنامه و مسدود شده منتقل می‌شود.

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

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

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

مثال

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

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

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

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

دلایل لغو اشتراک در نمای کلی آنالیتیکس نشان داده شده است تا به شرکا کمک کند دلیل لغو اشتراک کاربران را درک کنند.

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

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

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

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

نحوه‌ی کار اشتراک مجدد

  • گزینه اشتراک ، که هم از منوی چت و هم از طریق لینک درون چت در دسترس است، به کاربران این امکان را می‌دهد که دوباره در مکالمه‌ای که از آن لغو اشتراک کرده‌اند، مشترک شوند.

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

    کشور (کد کشور) کلمه کلیدی عضویت
    ایالات متحده، هند، بریتانیا، آلمان شروع
    اسپانیا (ES)، مکزیک (MX) آلتا
    فرانسه (FR) دمارر
    برزیل (BR) کامچار

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

  • به عنوان شریک 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 در event payload وضعیت جدید راه‌اندازی عامل را نشان می‌دهد. مقادیر ممکن به شرح زیر است:

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

فیلد داده شامل یک شیء 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 TERMINATED مامور تعلیق شده اخراج شد.
TERMINATED LAUNCHED نماینده‌ی اخراج‌شده راه‌اندازی شد.

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

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

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

{
  "phoneNumber": "[phone number]" ,
  "messageId": "[RCS message ID]",
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

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

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

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

{
  "phoneNumber": "[phone number]",
  "messageId": "[RCS message ID]",
  "agentId": "[bot ID]",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

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

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

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

قبلی
ارسال رویدادها
بعدی
بررسی قابلیت ها