Events are notifications that your agent can send and receive. There are three types of events:
- Server-generated: Sent to your agent by the RBM platform
- User-generated: Sent to your agent by the user's device
- Agent-generated: Sent by your agent to the user
Server-generated events
The RBM platform sends events to notify your agent about server-level updates such as message expirations.
For formatting and value options, see
ServerEvent.
Message has expired; revocation succeeded
The message has expired and was successfully revoked. This event would be a good trigger for your fallback messaging strategy.
{ "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] }
Message has expired; revocation failed
The message has expired, but it was not revoked.
{ "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] }
Message delivery is not guaranteed.
- If the message was delivered, you'll receive a
DELIVEREDevent at your webhook. - If the message was not delivered, use the revoke API to send a revocation request.
If the message is time-sensitive, like an OTP or a fraud alert, it's best to send the message through an alternate channel like SMS even if this results in duplicate messages to the user.
User-generated events
As with user messages and capability checks, your agent receives user events as JSON.
For formatting and value options, see
UserEvent.
User receives agent message
This event indicates that a message has been delivered.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "DELIVERED",
"eventId": "EVENT_ID",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID"
}User reads agent message
This event indicates that a message has been opened or acknowledged.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "READ",
"eventId": "EVENT_ID",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID"
}User starts typing
This event indicates that a user is typing.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "IS_TYPING",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}User sends a text message
{
"senderPhoneNumber": "PHONE_NUMBER",
"text": "Hi",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}User sends a file
{ "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" }
User taps a suggested reply
When a user taps a suggested reply, your agent receives an event with the reply's postback data and text.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID",
"suggestionResponse": {
"postbackData": "postback_1234",
"text": "Hello there!"
}
}User taps a suggested action
When a user taps a suggested action, your agent receives an event with the action's postback data.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID",
"suggestionResponse": {
"postbackData": "postback_1234"
}
}User unsubscribes from the conversation
If a user doesn't want to receive non-essential messages from a business, such as promotions, they can unsubscribe from the RBM conversation in Google Messages.
The UNSUBSCRIBE event indicates that the user has unsubscribed from their
conversation with your agent and the business it represents. Here's an example
of the JSON payload:
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "UNSUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}How it works
- An Unsubscribe option is always available within the chat menu. For promotional and multi-use agents, this option also appears directly in the chat after a certain number of unread messages (specific rules vary by country).
- Selecting Unsubscribe triggers Google Messages to send a "STOP"
message from the user's number to the RBM agent. Simultaneously, the RBM
platform sends an
UNSUBSCRIBEevent to the agent's webhook. - After the user unsubscribes, the conversation remains in their inbox unless reported as spam, in which case it moves to the Spam & blocked folder.
- To identify policy and business rule violations, Google monitors message patterns after a user unsubscribes.
Business rules
- As the RBM partner who manages this conversation, it's your responsibility to comply with the user's request to unsubscribe.
- If you can't perform the unsubscription within the message thread, you must immediately send a message of acknowledgement with a direct link to the website or app where users can manage their subscription preferences.
- After the user unsubscribes, sending non-essential messages is prohibited.
- Essential messages are still permitted. These include:
- Authentications, such as one-time passwords (OTPs)
- Notifications about a specific service the user has requested and consented to
- Confirmation of the user's unsubscribe request, with information to further manage their communications preferences
Example
If a user unsubscribes from an airline agent whose use case is multi-use, you must stop sending marketing messages. However, you may send flight updates if the user has provided explicit consent to receive updates for that specific flight.
Unsubscribe reasons
When a user unsubscribes from your agent, they can select a reason from the following options:
- Not signed up
- Too many messages
- No longer interested
- Spam
- Other
Currently, unsubscribe reasons are not shared with partners or carriers.
User resubscribes to the conversation
Users can resubscribe to a conversation they previously unsubscribed from in Google Messages.
The SUBSCRIBE event indicates that a user wants to receive messages from your
agent, including non-essential content like promotions. Here's an example of the
JSON payload:
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "SUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}How it works
- A Subscribe option, available from both the chat menu and an in-chat link, allows users to resubscribe to a conversation they had unsubscribed from.
- Selecting Subscribe triggers Google Messages to send a "START" message
from the user's number to the RBM agent. Simultaneously, the RBM platform
sends a
SUBSCRIBEevent to the agent's webhook.
Business rules
- As the RBM partner who manages this conversation, it's your responsibility to comply with the user's request to resubscribe.
- Resubscription applies to all message types, including non-essential content like promotions.
- If a user messages your business after unsubscribing, this can be considered a resubscribe request.
- If a user resubscribes outside the messaging channel (for example, on your website), it's your responsibility as RBM partner to update their status and resume sending messages accordingly.
Agent-generated events
Your agent sends events to simulate human interactions and assure the user that your agent is engaging with their messages. For users, events display as notifications within their conversations.
For formatting and value options, see
phones.agentEvents.
Agent sends a READ event
To users, this event appears as a read receipt for a specific message. It lets the user know that the RBM platform delivered their message and the agent is processing it.
The following code sends a READ event for a message with a matching
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);
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");
Agent sends an IS_TYPING event
To users, this event appears as a typing indicator and lets them know that your
agent is composing a message. The typing indicator expires after a short time
(approximately 20 seconds) or when the user's device receives a new message from
your agent. Your agent can send multiple IS_TYPING events to reset the typing
indicator's expiration timer.
The following code sends an IS_TYPING event.
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");