به‌روزرسانی‌ها : یادداشت‌های انتشار را برای ویژگی‌های جدید و به‌روزرسانی‌های محصول بررسی کنید. ، روز رسانی : یادداشت های انتشار را برای ویژگی های جدید و به روز رسانی محصول بررسی کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

رویداد

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

ایجاد شده توسط سرور : توسط پلت فرم RBM برای نماینده شما ارسال می شود
ایجاد شده توسط کاربر : توسط دستگاه کاربر برای نماینده شما ارسال می شود
Agent-generated : توسط نماینده شما برای کاربر ارسال می شود

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

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

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

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

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

پیکربندی Webhook

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

پیش نیازها

وب هوک خود را برای پیام رسانی RBM پیکربندی کنید (این یک الزام برای دریافت پیام های کاربر و رویدادهای تولید شده توسط کاربر است).
برای تمایز بین رویدادهای تولید شده توسط کاربر و رویدادهای وضعیت راه‌اندازی عامل، مسیر message.attributes.type را برای مقدار agent_launch_event بررسی کنید.

ساختار محموله رویداد

AgentLaunchEvent به عنوان یک پیام Pub/Sub تحویل داده می شود. در اینجا یک مثال است:

{
  "message": {
    "attributes": {
      "business_id": "[email protected]",
      "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 در بار رویداد، وضعیت راه اندازی جدید عامل را نشان می دهد. در اینجا مقادیر احتمالی وجود دارد:

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

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

    {
      "eventId": "rbm-chatbot-id/0a7ed168-676e-4a56-b422-b23434",
      "agentId": "[email protected]",
      "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": "[email protected]",
      "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 در وب هوک خود دریافت خواهید کرد.
اگر پیام تحویل داده نشد، از Revoke API برای ارسال درخواست لغو استفاده کنید.

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

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

مانند پیام‌های کاربر و بررسی قابلیت، نماینده شما رویدادهای کاربر را به‌عنوان 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"
}

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

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

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

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

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

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

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

مهم: برای کمک به برنامه‌نویسان برای انتقال به رویدادهای جدید UNSUBSCRIBE و SUBSCRIBE ، Google Messages همچنین پیام‌های «STOP» و «START» را در کنار رویدادهای webhook ارسال می‌کند. در حالی که در حال حاضر می توانید به منطق STOP/START موجود خود تکیه کنید، ما قویاً توصیه می کنیم منطق خود را برای مدیریت رویدادهای UNSUBSCRIBE و SUBSCRIBE روز کنید، زیرا این موارد مطابق با مشخصات GSMA اجباری خواهند شد.

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

رویداد UNSUBSCRIBE نشان می دهد که کاربر اشتراک خود را از مکالمه خود با نماینده شما و کسب و کاری که نمایندگی می کند لغو کرده است. در اینجا نمونه ای از بار JSON آورده شده است:

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

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

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

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

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

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

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

قوانین تجارت

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

مثال

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

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

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

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

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

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

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

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

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

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

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

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

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

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

قوانین تجارت

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

رویدادهای عامل ایجاد شده

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

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

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

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

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

CURL

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'
}"

Node.js

// 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

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',
}"

Node.js

// 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 است.

قبلی

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

بعدی

بررسی قابلیت ها

رویداد با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

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

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

پیکربندی Webhook

پیش نیازها

ساختار محموله رویداد

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

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

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

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

کاربر پیام عامل را می خواند

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

کاربر پیامک ارسال می کند

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

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

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

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

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

قوانین تجارت

مثال

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

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

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

قوانین تجارت

رویدادهای عامل ایجاد شده

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

CURL

Node.js

جاوا

پایتون

سی شارپ

نماینده یک رویداد IS_TYPING ارسال می کند

CURL

Node.js

جاوا

پایتون

سی شارپ

رویداد

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

نماینده یک رویداد `IS_TYPING` ارسال می کند