Los eventos son notificaciones que tu agente puede enviar y recibir. Existen tres tipos de eventos:
- Generado por el servidor: Lo envía la plataforma de RBM a tu agente.
- Generado por el usuario: El dispositivo del usuario lo envía a tu agente.
- Generado por el agente: Lo envió tu agente al usuario.
Eventos generados por el servidor
La plataforma de RBM envía eventos para notificar a tu agente sobre actualizaciones a nivel del servidor, como los vencimientos de mensajes.
Para ver las opciones de formato y valor, consulta ServerEvent.
El mensaje venció; la revocación se realizó correctamente
El mensaje caducó y se revocó correctamente. Este evento sería un buen activador para tu estrategia de mensajes de resguardo.
{ "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] }
El mensaje venció; se produjo un error de revocación
El mensaje caducó, pero no se revocó.
{ "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] }
No se garantiza la entrega de mensajes.
- Si se entregó el mensaje, recibirás un evento
DELIVEREDen tu webhook. - Si el mensaje no se entregó, usa la API de revocación para enviar una solicitud de revocación.
Si el mensaje es urgente, como una OTP o una alerta de fraude, es mejor enviarlo a través de un canal alternativo, como SMS, incluso si esto genera mensajes duplicados para el usuario.
Eventos generados por el usuario
Al igual que con los mensajes del usuario y las verificaciones de capacidad, tu agente recibe los eventos de usuario como JSON.
Para ver las opciones de formato y valor, consulta UserEvent.
El usuario recibe el mensaje del agente.
Este evento indica que se entregó un mensaje.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "DELIVERED",
"eventId": "EVENT_ID",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID"
}El usuario lee el mensaje del agente.
Este evento indica que un mensaje se abrió o se confirmó.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "READ",
"eventId": "EVENT_ID",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID"
}El usuario comienza a escribir
Este evento indica que un usuario está escribiendo.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "IS_TYPING",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}El usuario envía un mensaje de texto
{
"senderPhoneNumber": "PHONE_NUMBER",
"text": "Hi",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}El usuario envía un archivo
{ "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" }
El usuario presiona una respuesta sugerida.
Cuando un usuario presiona una respuesta sugerida, tu agente recibe un evento con los datos de notificación de conversión y el texto de la respuesta.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID",
"suggestionResponse": {
"postbackData": "postback_1234",
"text": "Hello there!"
}
}El usuario presiona una acción sugerida
Cuando un usuario presiona una acción sugerida, el agente recibe un evento con los datos de notificación de conversión de la acción.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID",
"suggestionResponse": {
"postbackData": "postback_1234"
}
}El usuario anula la suscripción a la conversación.
Si un usuario no desea recibir mensajes no esenciales de una empresa, como promociones, puede anular la suscripción a la conversación de RBM en Mensajes de Google.
El evento UNSUBSCRIBE indica que el usuario anuló la suscripción a su conversación con tu agente y la empresa que representa. Este es un ejemplo de la carga útil de JSON:
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "UNSUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}Cómo funciona
- La opción Anular la suscripción siempre está disponible en el menú del chat. Para los agentes promocionales y multiuso, esta opción también aparece directamente en el chat después de una cierta cantidad de mensajes no leídos (las reglas específicas varían según el país).
- Si seleccionas Anular la suscripción, Mensajes de Google enviará un mensaje "DETENER" desde el número del usuario al agente de RBM. Al mismo tiempo, la plataforma de RBM envía un evento
UNSUBSCRIBEal webhook del agente. - Después de que el usuario anule la suscripción, la conversación permanecerá en su carpeta Recibidos, a menos que se informe como spam, en cuyo caso se moverá a la carpeta Spam y bloqueadas.
- Para identificar incumplimientos de políticas y de reglas comerciales, Google supervisa los patrones de mensajes después de que un usuario anula la suscripción.
Reglas de negocio
- Como socio de RBM que administra esta conversación, es tu responsabilidad cumplir con la solicitud del usuario para anular la suscripción.
- Si no puedes anular la suscripción dentro de la conversación, debes enviar inmediatamente un mensaje de confirmación con un vínculo directo al sitio web o la app donde los usuarios pueden administrar sus preferencias de suscripción.
- Una vez que el usuario anula la suscripción, se prohíbe el envío de mensajes no esenciales.
- Todavía se permiten los mensajes esenciales. Estos son algunos de ellos:
- Autenticaciones, como contraseñas de un solo uso (OTP)
- Notificaciones sobre un servicio específico que el usuario solicitó y dio su consentimiento
- Confirmación de la solicitud de anulación de suscripción del usuario, con información para administrar aún más sus preferencias de comunicación
Ejemplo
Si un usuario anula la suscripción a un agente de una aerolínea cuyo caso de uso es multiuso, debes dejar de enviar mensajes de marketing. Sin embargo, puedes enviar actualizaciones de vuelos si el usuario otorgó su consentimiento explícito para recibir actualizaciones de ese vuelo específico.
Motivos para anular la suscripción
Cuando un usuario anula la suscripción a tu agente, puede seleccionar un motivo entre las siguientes opciones:
- No me registré en él
- Demasiados mensajes
- Ya no me interesa
- Spam
- Otro
El usuario vuelve a suscribirse a la conversación.
Los usuarios pueden volver a suscribirse a una conversación a la que ya habían anulado la suscripción en Mensajes de Google.
El evento SUBSCRIBE indica que un usuario quiere recibir mensajes de tu agente, incluido el contenido no esencial, como las promociones. Este es un ejemplo de la carga útil de JSON:
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "SUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}Cómo funciona
- La opción Suscribirse, disponible en el menú del chat y en un vínculo en el chat, permite a los usuarios volver a suscribirse a una conversación a la que anularon la suscripción.
- Si seleccionas Suscribirse, Mensajes de Google enviará un mensaje de "COMENZAR" desde el número del usuario al agente de RBM. Al mismo tiempo, la plataforma de RBM envía un evento
SUBSCRIBEal webhook del agente.
Reglas de negocio
- Como socio de RBM que administra esta conversación, es tu responsabilidad cumplir con la solicitud del usuario para volver a suscribirse.
- La nueva suscripción se aplica a todos los tipos de mensajes, incluido el contenido no esencial, como las promociones.
- Si un usuario envía un mensaje a tu empresa después de anular la suscripción, se puede considerar una solicitud para volver a suscribirse.
- Si un usuario se vuelve a suscribir fuera del canal de mensajería (por ejemplo, en tu sitio web), es tu responsabilidad como socio de RBM actualizar su estado y reanudar el envío de mensajes según corresponda.
Eventos generados por el agente
Tu agente envía eventos para simular interacciones humanas y asegurarle al usuario que tu agente interactúa con sus mensajes. Para los usuarios, los eventos se muestran como notificaciones en sus conversaciones.
Para ver las opciones de formato y valor, consulta phones.agentEvents.
El agente envía un evento READ
Para los usuarios, este evento aparece como confirmación de lectura de un mensaje específico. Le informa al usuario que la plataforma RBM entregó su mensaje y que el agente lo está procesando.
El siguiente código envía un evento READ para un mensaje con un messageId
coincidente.
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");
El agente envía un evento IS_TYPING
Para los usuarios, este evento aparece como un indicador de escritura y les permite saber que tu agente está redactando un mensaje. El indicador de escritura expira después de un tiempo breve (aproximadamente 20 segundos) o cuando el dispositivo del usuario recibe un mensaje nuevo de tu agente. Tu agente puede enviar varios eventos IS_TYPING para restablecer el temporizador de vencimiento del indicador de escritura.
El siguiente código envía un evento 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");