Sự kiện là những thông báo mà tác nhân của bạn có thể gửi và nhận. Có ba loại sự kiện:
- Do máy chủ tạo: Được gửi đến đại lý của bạn bởi nền tảng RBM
- Do người dùng tạo: Được gửi đến đại lý của bạn thông qua thiết bị của người dùng
- Do tác nhân tạo ra: Được tác nhân của bạn gửi đến 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 tác nhân của bạn về các cập nhật cấp máy chủ như ngày hết hạn tin nhắn.
Để biết các tùy chọn định dạng và giá trị, hãy xem ServerEvent.
Trạng thái khởi chạy tác nhân đã thay đổi
Nền tảng RBM sẽ gửi AgentLaunchEvent cho mọi thay đổi về trạng thái khởi chạy của tác nhân. Ví dụ: khi trạng thái của đại lý thay đổi từ PENDING thành LAUNCHED sau khi nhà mạng chấp thuận, bạn sẽ nhận được sự kiện AgentLaunchEvent để biểu thị thay đổi. Các 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 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 đại lý để nhận những thông báo này.
Điều kiện tiên quyết
- Cấu hình webhook để nhắn tin RBM (đây là yêu cầu để 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 sự kiện do người dùng tạo và sự kiện trạng thái khởi chạy 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 trọng sự kiện
AgentLaunchEvent được gửi dưới dạng tin nhắn 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 dữ liệu 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 khởi chạy tác nhân | 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 nhà mạng để 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 nhà mạng nhất định | Lý do từ chối được nêu trong phần nhận xét. |
SUSPENDED |
Bị treo trên một tàu sân bay nhất định | Lý do tạm ngưng được nêu trong phần bình luận. |
Trường dữ liệu chứa đối tượng JSON được mã hóa theo chuẩn Base64 với thông tin chi tiết về trạng thái khởi chạy. Sau đây là một 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 | Động lực cho sự thay đổi |
|---|---|---|
PENDING |
LAUNCHED |
Đại lý đang chờ phê duyệt. |
PENDING |
REJECTED |
Đại lý đang chờ xử lý đã bị từ chối. |
LAUNCHED |
SUSPENDED |
Đã ra mắt tác nhân bị đình chỉ. |
SUSPENDED |
LAUNCHED |
Chất tác nhân bị đình chỉ đã được kích hoạt lại. |
SUSPENDED |
TERMINATED |
Đại lý bị đình chỉ đã bị chấm dứt. |
TERMINATED |
LAUNCHED |
Đã đưa ra tác nhân bị chấm dứt. |
Tin nhắn đã hết hạn; việc thu hồi đã thành công
Tin nhắn đã hết hạn và đã được thu hồi thành công. Sự kiện này sẽ là bước khởi đầu tốt 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; việc thu hồi không thành công
Tin nhắn đã hết hạn nhưng chưa được 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 tin nhắn sẽ được gửi đi.
- Nếu tin nhắn đã được gửi, bạn sẽ nhận được sự kiện
DELIVEREDtại webhook của mình. - Nếu tin nhắn 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 tin nhắn có giới hạn thời gian, như OTP hoặc cảnh báo gian lận, tốt nhất là gửi tin nhắn qua kênh khác như SMS ngay cả khi điều này khiến người dùng nhận được tin nhắn trùng lặp.
Sự kiện do người dùng tạo
Tương tự như tin nhắn người dùng và kiểm tra khả năng, tác nhân của bạn sẽ nhận các sự kiện của người dùng dưới dạng JSON.
Để biết các tùy chọn định dạng và giá trị, hãy xem UserEvent.
Người dùng nhận được tin nhắn của tác nhân
Sự kiện này cho biết tin nhắn đã đượ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 tác nhân
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 tin
{ "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 chạm vào câu trả lời được đề xuất
Khi người dùng chạm vào câu trả lời được đề xuất, tác nhân của bạn sẽ nhận được sự kiện có dữ liệu phản hồi và văn bản 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 chạm vào một hành động được đề xuất, tác nhân của bạn sẽ nhận được sự kiện có dữ liệu phản hồi của hành động đó.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID",
"suggestionResponse": {
"postbackData": "postback_1234"
}
}Người dùng hủy đăng ký khỏi cuộc trò chuyện
Nếu người dùng không muốn nhận tin nhắn không cần thiết từ doanh nghiệp, chẳng hạn như tin nhắn khuyến mại, họ có thể hủy đăng ký cuộc trò chuyện RBM trong Google Messages.
Sự kiện UNSUBSCRIBE cho biết người dùng đã hủy đăng ký cuộc trò chuyện với đại lý của bạn và doanh nghiệp mà đại lý đó đại diện. Sau đây là một ví dụ về dữ liệu JSON:
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "UNSUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}Cách hoạt động
- Tùy chọn Hủy đăng ký luôn có sẵn trong menu trò chuyện. Đối với các tác nhân quảng cáo và đa mục đích, tùy chọn này cũng xuất hiện trực tiếp trong cuộc trò chuyện sau một số lượng tin nhắn chưa đọc nhất định (quy tắc cụ thể khác nhau tùy theo quốc gia).
Việc chọn Hủy đăng ký sẽ kích hoạt hai hành động đồng thời: Google Messages gửi từ khóa cụ thể theo quốc gia (ví dụ: "DỪNG") đến đại lý của bạn và nền tảng RBM gửi sự kiện HỦY ĐĂ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ừ tác nhân của bạn, bao gồm cả nội dung không thiết yếu như nội dung quảng cáo. Sau đây là 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, kể 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 đang nhập sẽ hết hạn sau một 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ừ đại lý 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ộ đếm thời gian 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");