Eventos

Los eventos son notificaciones que tu agente puede enviar y recibir. Existen tres tipos de eventos:

Eventos generados por el servidor

La plataforma de RBM envía eventos para notificar a tu agente sobre las actualizaciones a nivel del servidor, como los vencimientos de mensajes.

Para conocer las opciones de formato y valores, consulta ServerEvent.

Cambió el estado del lanzamiento del agente

La plataforma de RBM envía un AgentLaunchEvent por cada cambio en el estado de lanzamiento de tu agente. Por ejemplo, cuando el estado de tu agente cambia de PENDING a LAUNCHED después de la aprobación del operador, recibes un evento AgentLaunchEvent para indicar el cambio. Estos eventos se envían para todos los agentes de RBM y para todos los cambios de estado de lanzamiento del operador.

Configuración de webhook

Puedes usar tu webhook a nivel del socio o del agente para recibir estas notificaciones.

Requisitos previos

  • Configura tu webhook para la mensajería de RBM (este es un requisito para recibir mensajes de usuarios y eventos generados por usuarios).
  • Para diferenciar entre los eventos generados por el usuario y los eventos de estado de inicio del agente, verifica la ruta de message.attributes.type para el valor agent_launch_event.

Estructura de la carga útil del evento

El AgentLaunchEvent se entrega como un mensaje de Pub/Sub. Por ejemplo:

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

El campo AgentLaunchEvent.LaunchState en la carga útil del evento indica el nuevo estado de inicio del agente. Estos son los valores posibles:

Valor Estado del lanzamiento del agente Detalles
UNLAUNCHED Sin lanzar Se permite la edición.
PENDING Pendiente La solicitud se envió a un operador para su revisión.
LAUNCHED Lanzado Se permiten los mensajes en un operador determinado.
REJECTED Se rechazó en un operador determinado El motivo del rechazo se especifica en el comentario.
SUSPENDED Se suspendió en una empresa de transporte determinada El motivo de la suspensión se especifica en el comentario.

El campo de datos contiene un objeto JSON codificado en Base64 con los detalles del estado de lanzamiento. Aquí tienes un ejemplo del JSON decodificado:

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

En la siguiente tabla, se muestran los estados de inicio del agente y las acciones que los activan:

Estado de lanzamiento anterior Nuevo estado de lanzamiento Activador del cambio
PENDING LAUNCHED Se aprobó el agente pendiente.
PENDING REJECTED Se rechazó el agente pendiente.
LAUNCHED SUSPENDED Se suspendió el agente lanzado.
SUSPENDED LAUNCHED Se reactivó el agente suspendido.
SUSPENDED TERMINATED Se canceló el agente suspendido.
TERMINATED LAUNCHED Se inició el agente cancelado.

El mensaje venció y la revocación se realizó correctamente

El mensaje venció 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ó y no se pudo revocar

El mensaje venció, 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 el mensaje es urgente, como un OTP o una alerta de fraude, lo mejor es 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 capacidades, tu agente recibe los eventos del usuario como JSON.

Para conocer las opciones de formato y valores, consulta UserEvent.

El usuario recibe un 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 se abrió o confirmó un mensaje.

{
  "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 devolució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, tu agente recibe un evento con los datos de devolución de llamada de la acción.

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

El usuario se da de baja de la conversación

Si un usuario no quiere recibir mensajes no esenciales de una empresa, como promociones, puede anular su suscripción a la conversación de RBM en Mensajes de Google.

El evento UNSUBSCRIBE indica que el usuario canceló su suscripción a la 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ú de chat. En el caso de los agentes promocionales y de uso múltiple, 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, se activan dos acciones simultáneas: Mensajes de Google envía una palabra clave específica del país (por ejemplo, "DETENER") a tu agente, y la plataforma de RBM envía un evento UNSUBSCRIBE a tu webhook.

    La palabra clave se determina según el código de país de dos letras del número de teléfono del usuario. En la siguiente tabla, se enumeran las palabras clave para cada país admitido.

    País (código de país) Palabra clave para anular la suscripción
    Estados Unidos (US), India (IN), Reino Unido (GB) y Alemania (DE) DETENER
    España (ES) y México (MX) BAJA
    Francia (FR) DETENER
    Brasil (BR) parar

  • Después de que el usuario se da de baja, la conversación permanece en su carpeta de Recibidos, a menos que se denuncie como spam, en cuyo caso se mueve a la carpeta Spam y bloqueadas.

  • Para identificar los incumplimientos de políticas y reglas comerciales, Google supervisa los patrones de mensajes después de que un usuario cancela la suscripción.

Reglas de negocio

  • Como socio de RBM que administra esta conversación, es tu responsabilidad cumplir con la solicitud del usuario de cancelar la suscripción.
  • Si no puedes cancelar la suscripción en el hilo de mensajes, debes enviar de inmediato un mensaje de confirmación con un vínculo directo al sitio web o la app en los que los usuarios puedan administrar sus preferencias de suscripción.
  • Después de que el usuario anula la suscripción, se prohíbe enviar mensajes no esenciales.
  • Se siguen permitiendo los mensajes esenciales. Estas son algunas de ellas:
    • Autenticaciones, como contraseñas de un solo uso (OTP)
    • Notificaciones sobre un servicio específico que el usuario solicitó y aceptó
    • Confirmación de la solicitud de cancelación de suscripción del usuario, con información para administrar aún más sus preferencias de comunicaciones

Ejemplo

Si un usuario anula la suscripción a un agente de aerolíneas cuyo caso de uso es de uso múltiple, debes dejar de enviar mensajes de marketing. Sin embargo, puedes enviar actualizaciones sobre el vuelo si el usuario dio su consentimiento explícito para recibirlas.

Motivos de cancelación de la suscripción

Cuando un usuario se da de baja de tu agente, puede seleccionar un motivo entre las siguientes opciones:

  • No me registré en él
  • Demasiados mensajes
  • Ya no me interesa
  • Spam
  • Otro

Actualmente, los motivos de cancelación de la suscripción no se comparten con los socios ni los operadores.

El usuario vuelve a suscribirse a la conversación

Los usuarios pueden volver a suscribirse a una conversación de la que se habían dado de baja en Mensajes de Google.

El evento SUBSCRIBE indica que un usuario desea 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ú de chat y en un vínculo en el chat, permite que los usuarios se vuelvan a suscribir a una conversación de la que habían anulado la suscripción.

  • Si seleccionas Suscribirse, se activan dos acciones simultáneas: Mensajes de Google envía una palabra clave específica del país (por ejemplo, "INICIAR") a tu agente, y la plataforma de RBM envía un evento SUBSCRIBE a tu webhook.

    La palabra clave específica se determina según el código de país de dos letras del número de teléfono del usuario. En la siguiente tabla, se enumeran las palabras clave para cada país admitido.

    País (código de país) Palabra clave de suscripción
    Estados Unidos (US), India (IN), Reino Unido (GB) y Alemania (DE) INICIAR
    España (ES) y México (MX) ALTA
    Francia (FR) Démarrer
    Brasil (BR) começar

Reglas de negocio

  • Como socio de RBM que administra esta conversación, es tu responsabilidad satisfacer 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 le envía un mensaje a tu empresa después de anular la suscripción, esto se puede considerar como una solicitud de reactivación de la suscripción.
  • Si un usuario vuelve a suscribirse 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 garantizarle al usuario que tu agente está interactuando con sus mensajes. Para los usuarios, los eventos se muestran como notificaciones en sus conversaciones.

Para conocer las opciones de formato y valores, consulta phones.agentEvents.

El agente envía un evento READ

Para los usuarios, este evento aparece como una confirmación de lectura de un mensaje específico. Le permite al usuario saber que la plataforma de 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);
 Este código es un fragmento de un agente de muestra de RBM.

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");
 Este código es un fragmento de un agente de muestra de RBM.

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)
 Este código es un fragmento de un agente de muestra de RBM.

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");
 Este código es un fragmento de un agente de muestra de RBM.

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 vence después de un breve período (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!');
});
 Este código es un fragmento de un agente de muestra de RBM.

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");
 Este código es un fragmento de un agente de muestra de RBM.

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')
 Este código es un fragmento de un agente de muestra de RBM.

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");
 Este código es un fragmento de un agente de muestra de RBM.
Anterior
Recibir mensajes
Siguiente
Verificaciones de capacidades