Sự kiện là những thông báo mà trợ lý ảo có thể gửi và nhận. Có 3 loại sự kiện:
- Do máy chủ tạo: Do nền tảng RBM gửi đến nhân viên hỗ trợ của bạn
- Do người dùng tạo: Được gửi đến trợ lý ảo của bạn từ thiết bị của người dùng
- Do nhân viên tạo: Do nhân viên của bạn gửi cho người dùng
Sự kiện do máy chủ tạo
Nền tảng RBM gửi các sự kiện để thông báo cho nhân viên hỗ trợ của bạn về các bản cập nhật ở cấp máy chủ, chẳng hạn như thời gian hết hạn của tin nhắn.
Để biết các lựa chọn về định dạng và giá trị, hãy xem ServerEvent.
Trạng thái ra mắt nhân viên hỗ trợ đã thay đổi
Nền tảng RBM sẽ gửi một AgentLaunchEvent cho mọi thay đổi về trạng thái ra mắt của nhân viên hỗ trợ. Ví dụ: khi trạng thái của hãng hàng không thay đổi từ PENDING thành LAUNCHED sau khi hãng vận chuyển phê duyệt, bạn sẽ nhận được sự kiện AgentLaunchEvent để cho biết sự thay đổi này. Những sự kiện này được gửi cho tất cả các tác nhân RBM, cho tất cả các thay đổi về trạng thái khởi chạy của nhà mạng.
Cấu hình webhook
Bạn có thể sử dụng webhook ở cấp độ đối tác hoặc cấp độ nhân viên hỗ trợ để nhận những thông báo này.
Điều kiện tiên quyết
- Định cấu hình webhook cho tính năng nhắn tin RBM (đây là yêu cầu bắt buộc để nhận tin nhắn của người dùng và sự kiện do người dùng tạo).
- Để phân biệt giữa các sự kiện do người dùng tạo và các sự kiện trạng thái khởi chạy của tác nhân, hãy kiểm tra đường dẫn
message.attributes.typeđể biết giá trịagent_launch_event.
Cấu trúc tải sự kiện
AgentLaunchEvent được gửi dưới dạng một thông báo Pub/Sub. Ví dụ:
{
"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"
}
Trường AgentLaunchEvent.LaunchState trong tải trọng sự kiện cho biết trạng thái khởi chạy mới của tác nhân.
Sau đây là các giá trị có thể có:
| Giá trị | Trạng thái ra mắt nhân viên hỗ trợ | Thông tin chi tiết |
|---|---|---|
UNLAUNCHED |
Chưa ra mắt | Được phép chỉnh sửa. |
PENDING |
Đang chờ xử lý | Yêu cầu đã được gửi đến một hãng vận chuyển để xem xét. |
LAUNCHED |
Đã ra mắt | Tin nhắn được phép gửi trên một nhà mạng nhất định. |
REJECTED |
Bị từ chối trên một hãng vận chuyển cụ thể | Lý do từ chối được nêu trong phần nhận xét. |
SUSPENDED |
Bị tạm ngưng trên một hãng vận chuyển cụ thể | Lý do tạm ngưng được nêu trong phần bình luận. |
Trường dữ liệu chứa một đối tượng JSON được mã hoá Base64 với thông tin chi tiết về trạng thái khởi chạy. Dưới đây là ví dụ về JSON đã giải mã:
{
"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"
}
Bảng sau đây cho biết các trạng thái khởi chạy của tác nhân và những hành động kích hoạt các trạng thái đó:
| Trạng thái khởi chạy cũ | Trạng thái ra mắt mới | Yếu tố thúc đẩy sự thay đổi |
|---|---|---|
PENDING |
LAUNCHED |
Đang chờ nhân viên hỗ trợ được phê duyệt. |
PENDING |
REJECTED |
Nhân viên hỗ trợ đang chờ xử lý bị từ chối. |
LAUNCHED |
SUSPENDED |
Nhân viên hỗ trợ đã ra mắt bị tạm ngưng. |
SUSPENDED |
LAUNCHED |
Nhân viên hỗ trợ bị tạm ngưng đã được kích hoạt lại. |
SUSPENDED |
TERMINATED |
Nhân viên hỗ trợ bị tạm ngưng đã bị chấm dứt. |
TERMINATED |
LAUNCHED |
Nhân viên hỗ trợ đã chấm dứt được ra mắt. |
Tin nhắn đã hết hạn; thu hồi thành công
Thông báo đã hết hạn và bị thu hồi thành công. Sự kiện này sẽ là một điều kiện kích hoạt phù hợp cho chiến lược nhắn tin dự phòng của bạn.
{ "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] }
Tin nhắn đã hết hạn; không thu hồi được
Thông báo đã hết hạn nhưng chưa bị thu hồi.
{ "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] }
Không đảm bảo gửi được thư.
- Nếu thư đã được gửi, bạn sẽ nhận được sự kiện
DELIVEREDtại webhook của mình. - Nếu thông báo không được gửi, hãy sử dụng API thu hồi để gửi yêu cầu thu hồi.
Nếu thông báo có tính chất khẩn cấp, chẳng hạn như OTP hoặc cảnh báo gian lận, thì tốt nhất là bạn nên gửi thông báo qua một kênh thay thế như SMS ngay cả khi điều này dẫn đến việc người dùng nhận được thông báo trùng lặp.
Sự kiện do người dùng tạo
Giống như tin nhắn của người dùng và các bước kiểm tra khả năng, nhân viên hỗ trợ của bạn sẽ nhận được các sự kiện của người dùng dưới dạng JSON.
Để biết các lựa chọn về định dạng và giá trị, hãy xem UserEvent.
Người dùng nhận được tin nhắn của nhân viên hỗ trợ
Sự kiện này cho biết rằng một thông báo đã được gửi.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "DELIVERED",
"eventId": "EVENT_ID",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID"
}Người dùng đọc tin nhắn của nhân viên hỗ trợ
Sự kiện này cho biết một tin nhắn đã được mở hoặc xác nhận.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "READ",
"eventId": "EVENT_ID",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID"
}Người dùng bắt đầu nhập
Sự kiện này cho biết người dùng đang nhập dữ liệu.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "IS_TYPING",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}Người dùng gửi tin nhắn văn bản
{
"senderPhoneNumber": "PHONE_NUMBER",
"text": "Hi",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}Người dùng gửi một tệp
{ "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" }
Người dùng nhấn vào một câu trả lời được đề xuất
Khi người dùng nhấn vào một câu trả lời được đề xuất, nhân viên hỗ trợ của bạn sẽ nhận được một sự kiện có dữ liệu và văn bản postback của câu trả lời đó.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID",
"suggestionResponse": {
"postbackData": "postback_1234",
"text": "Hello there!"
}
}Người dùng nhấn vào một hành động được đề xuất
Khi người dùng nhấn vào một hành động được đề xuất, tác nhân của bạn sẽ nhận được một sự kiện kèm theo dữ liệu gửi lại của hành động đó.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID",
"suggestionResponse": {
"postbackData": "postback_1234"
}
}Người dùng huỷ đăng ký nhận thông báo về cuộc trò chuyện
Nếu không muốn nhận tin nhắn không thiết yếu của một doanh nghiệp, chẳng hạn như tin nhắn quảng bá, người dùng có thể huỷ đăng ký nhận tin nhắn RBM trong Google Tin nhắn.
Sự kiện UNSUBSCRIBE cho biết người dùng đã huỷ đăng ký cuộc trò chuyện với nhân viên hỗ trợ của bạn và doanh nghiệp mà nhân viên đó đại diện. Sau đây là ví dụ về tải trọng JSON:
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "UNSUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}Cách hoạt động
- Lựa chọn Huỷ đăng ký luôn có trong trình đơn trò chuyện. Đối với các tác nhân quảng bá và tác nhân đa năng, lựa chọn này cũng xuất hiện ngay trong cuộc trò chuyện sau một số lượng tin nhắn chưa đọc nhất định (các quy tắc cụ thể sẽ khác nhau tuỳ theo quốc gia).
Khi bạn chọn Huỷ đăng ký, hai hành động sẽ diễn ra đồng thời: Google Tin nhắn gửi một từ khoá theo quốc gia (ví dụ: "DỪNG") đến tác nhân của bạn và nền tảng RBM gửi một sự kiện HUỶ ĐĂNG KÝ đến webhook của bạn.
Từ khoá được xác định bằng mã quốc gia gồm 2 chữ cái trong số điện thoại của người dùng. Bảng sau đây liệt kê các từ khoá cho từng quốc gia được hỗ trợ.
Quốc gia (mã quốc gia) Từ khoá huỷ đăng ký Hoa Kỳ (US), Ấn Độ (IN), Vương quốc Anh (GB), Đức (DE) DỪNG Tây Ban Nha (ES), Mexico (MX) BAJA Pháp (FR) DỪNG Brazil (BR) parar Sau khi người dùng huỷ đăng ký, cuộc trò chuyện vẫn nằm trong hộp thư đến của họ, trừ phi bị báo cáo là tin nhắn rác. Trong trường hợp đó, cuộc trò chuyện sẽ chuyển đến thư mục Tin nhắn rác và bị chặn.
Để xác định các lỗi vi phạm chính sách và quy tắc kinh doanh, Google sẽ giám sát các mẫu tin nhắn sau khi người dùng huỷ đăng ký.
Quy tắc kinh doanh
- Là đối tác RBM quản lý cuộc trò chuyện này, bạn có trách nhiệm tuân thủ yêu cầu huỷ đăng ký của người dùng.
- Nếu không thể huỷ đăng ký trong chuỗi tin nhắn, bạn phải gửi ngay một tin nhắn xác nhận kèm theo đường liên kết trực tiếp đến trang web hoặc ứng dụng nơi người dùng có thể quản lý lựa chọn ưu tiên về việc đăng ký.
- Sau khi người dùng huỷ đăng ký, bạn không được phép gửi tin nhắn không thiết yếu.
- Bạn vẫn được phép gửi những tin nhắn quan trọng. Những trường hợp này bao gồm:
- Thông tin xác thực, chẳng hạn như mật khẩu một lần (OTP)
- Thông báo về một dịch vụ cụ thể mà người dùng đã yêu cầu và đồng ý
- Xác nhận yêu cầu huỷ đăng ký của người dùng, kèm theo thông tin để quản lý thêm các lựa chọn ưu tiên về thông tin liên lạc
Ví dụ:
Nếu người dùng huỷ đăng ký nhận thông tin từ một hãng hàng không có trường hợp sử dụng là nhiều mục đích, bạn phải ngừng gửi thư tiếp thị. Tuy nhiên, bạn có thể gửi thông tin cập nhật về chuyến bay nếu người dùng đã đồng ý rõ ràng nhận thông tin cập nhật cho chuyến bay cụ thể đó.
Lý do huỷ đăng ký
Khi huỷ đăng ký nhận thông tin từ nhân viên hỗ trợ của bạn, người dùng có thể chọn một lý do trong số các lựa chọn sau:
- Không đăng ký
- Quá nhiều tin nhắn
- Không còn quan tâm
- Tin nhắn rác
- Khác
Hiện tại, chúng tôi không chia sẻ lý do huỷ đăng ký với đối tác hoặc nhà mạng.
Người dùng đăng ký lại cuộc trò chuyện
Người dùng có thể đăng ký lại một cuộc trò chuyện mà họ đã huỷ đăng ký trước đó trong Google Tin nhắn.
Sự kiện SUBSCRIBE cho biết rằng người dùng muốn nhận tin nhắn từ đặc vụ của bạn, bao gồm cả nội dung không thiết yếu như nội dung quảng bá. Sau đây là một ví dụ về tải trọng JSON:
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "SUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}Cách hoạt động
- Tuỳ chọn Đăng ký (có trong cả trình đơn trò chuyện và đường liên kết trong cuộc trò chuyện) cho phép người dùng đăng ký lại một cuộc trò chuyện mà họ đã huỷ đăng ký.
Khi bạn chọn Đăng ký, hai hành động sẽ diễn ra đồng thời: Google Tin nhắn gửi một từ khoá theo quốc gia (ví dụ: "BẮT ĐẦU") đến nhân viên hỗ trợ của bạn và nền tảng RBM gửi một sự kiện ĐĂNG KÝ đến webhook của bạn.
Từ khoá cụ thể được xác định bằng mã quốc gia gồm 2 chữ cái của số điện thoại người dùng. Bảng sau đây liệt kê các từ khoá cho từng quốc gia được hỗ trợ.
Quốc gia (mã quốc gia) Từ khoá đăng ký Hoa Kỳ (US), Ấn Độ (IN), Vương quốc Anh (GB), Đức (DE) BẮT ĐẦU Tây Ban Nha (ES), Mexico (MX) ALTA Pháp (FR) Démarrer Brazil (BR) começar
Quy tắc kinh doanh
- Là đối tác RBM quản lý cuộc trò chuyện này, bạn có trách nhiệm tuân thủ yêu cầu đăng ký lại của người dùng.
- Việc đăng ký lại áp dụng cho tất cả các loại thông báo, bao gồm cả nội dung không thiết yếu như chương trình khuyến mãi.
- Nếu người dùng nhắn tin cho doanh nghiệp của bạn sau khi huỷ đăng ký, thì đây có thể được coi là yêu cầu đăng ký lại.
- Nếu người dùng đăng ký lại bên ngoài kênh nhắn tin (ví dụ: trên trang web của bạn), thì bạn, với tư cách là đối tác RBM, có trách nhiệm cập nhật trạng thái của họ và tiếp tục gửi tin nhắn cho phù hợp.
Sự kiện do tác nhân tạo
Nhân viên hỗ trợ của bạn gửi các sự kiện để mô phỏng hoạt động tương tác của con người và đảm bảo với người dùng rằng nhân viên hỗ trợ của bạn đang tương tác với tin nhắn của họ. Đối với người dùng, các sự kiện sẽ xuất hiện dưới dạng thông báo trong cuộc trò chuyện của họ.
Để biết các lựa chọn về định dạng và giá trị, hãy xem phones.agentEvents.
Nhân viên hỗ trợ gửi một sự kiện READ
Đối với người dùng, sự kiện này xuất hiện dưới dạng thông báo đã đọc cho một tin nhắn cụ thể. Thông báo cho người dùng biết rằng nền tảng RBM đã gửi tin nhắn của họ và nhân viên hỗ trợ đang xử lý tin nhắn đó.
Đoạn mã sau đây sẽ gửi một sự kiện READ cho một thông báo có messageId trùng khớp.
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);
Java
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");
Python
# 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)
C#
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");
Nhân viên hỗ trợ gửi một sự kiện IS_TYPING
Đối với người dùng, sự kiện này xuất hiện dưới dạng chỉ báo nhập và cho họ biết rằng tác nhân của bạn đang soạn tin nhắn. Chỉ báo nhập hết hạn sau một khoảng thời gian ngắn (khoảng 20 giây) hoặc khi thiết bị của người dùng nhận được tin nhắn mới từ trợ lý ảo của bạn. Tác nhân của bạn có thể gửi nhiều sự kiện IS_TYPING để đặt lại bộ tính giờ hết hạn của chỉ báo nhập.
Đoạn mã sau đây sẽ gửi một sự kiện 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!'); });
Java
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");
Python
# 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')
C#
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");