رویداد

رویدادها اعلان‌هایی هستند که نماینده شما می‌تواند ارسال و دریافت کند. سه نوع رویداد وجود دارد:

رویدادهای تولید شده توسط سرور

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

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

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

پلتفرم RBM برای هر تغییر در وضعیت راه‌اندازی اپراتور شما، یک AgentLaunchEvent ارسال می‌کند. برای مثال، وقتی وضعیت اپراتور شما پس از تأیید اپراتور از PENDING به LAUNCHED تغییر می‌کند، شما یک رویداد AgentLaunchEvent دریافت می‌کنید تا این تغییر را نشان دهد. این رویدادها برای همه اپراتورهای RBM و برای همه تغییرات وضعیت راه‌اندازی اپراتور ارسال می‌شوند.

پیکربندی وب‌هوک

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

پیش‌نیازها

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

رویداد 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 نماینده‌ی اخراج‌شده راه‌اندازی شد.

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

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

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

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

پیام منقضی شده است، اما لغو نشده است.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

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

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

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

رویدادهای ایجاد شده توسط کاربر

همانند پیام‌های کاربر و بررسی قابلیت‌ها، عامل شما رویدادهای کاربر را به صورت JSON دریافت می‌کند.

برای گزینه‌های قالب‌بندی و مقداردهی، به 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 در Google Messages لغو اشتراک کند.

رویداد UNSUBSCRIBE نشان می‌دهد که کاربر از مکالمه خود با نماینده شما و کسب‌وکاری که نماینده آن است، انصراف داده است. در اینجا مثالی از محتوای JSON آورده شده است: 

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

چگونه کار می‌کند؟

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

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

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

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

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

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

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

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

مثال

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

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

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

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

در حال حاضر، دلایل لغو اشتراک با شرکا یا اپراتورهای تلفن همراه به اشتراک گذاشته نمی‌شود.

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

کاربران می‌توانند دوباره در مکالمه‌ای که قبلاً در Google Messages از آن لغو اشتراک کرده بودند، مشترک شوند.

رویداد SUBSCRIBE نشان می‌دهد که کاربر می‌خواهد از نماینده شما پیام دریافت کند، از جمله محتوای غیرضروری مانند تبلیغات. در اینجا مثالی از محتوای JSON آورده شده است: 

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

چگونه کار می‌کند؟

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

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

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

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

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

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

رویدادهای تولید شده توسط عامل

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

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

عامل یک رویداد READ ارسال می‌کند

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

کد زیر یک رویداد READ برای پیامی با messageId منطبق ارسال می‌کند.

حلقه 

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'READ',
  'messageId': 'MESSAGE_ID'
}"

نود جی اس 

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage('+12223334444', messageId);
 این کد گزیده‌ای از یک عامل نمونه RBM است.

جاوا 

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage(messageId, "+12223334444");
 این کد گزیده‌ای از یک عامل نمونه RBM است.

پایتون 

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that message_id was read
rbm_service.send_read_event('+12223334444', message_id)
 این کد گزیده‌ای از یک عامل نمونه RBM است.

سی شارپ 

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that messageId has been read
rbmApiHelper.SendReadMessage(messageId, "+12223334444");
 این کد گزیده‌ای از یک عامل نمونه RBM است.

عامل یک رویداد IS_TYPING ارسال می‌کند

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

کد زیر یک رویداد IS_TYPING ارسال می‌کند.

حلقه 

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'IS_TYPING',
}"

نود جی اس 

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage('+12223334444', function() {
    console.log('Typing event sent!');
});
 این کد گزیده‌ای از یک عامل نمونه RBM است.

جاوا 

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage("+12223334444");
 این کد گزیده‌ای از یک عامل نمونه RBM است.

پایتون 

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that the agent is typing
rbm_service.send_is_typing_event('+12223334444')
 این کد گزیده‌ای از یک عامل نمونه RBM است.

سی شارپ 

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that the agent is typing
rbmApiHelper.SendIsTypingMessage(messageId, "+12223334444");
 این کد گزیده‌ای از یک عامل نمونه RBM است.
قبلی
پیام ها را دریافت کنید
بعدی
بررسی قابلیت ها