Cómo recibir eventos

Tu agente recibe eventos de webhook de la plataforma de RBM, que te notifican sobre las interacciones de los usuarios y las actualizaciones a nivel de la plataforma.

Estos eventos se clasifican según su origen:

• Eventos de usuario: Son notificaciones que se envían desde el dispositivo de un usuario a tu agente y que indican una interacción con él.
• Eventos de la plataforma: Notificaciones sobre los cambios de estado de lanzamiento del agente y los vencimientos de los mensajes que envía la plataforma de RBM.

Para obtener detalles sobre los eventos de estado que tu agente envía al dispositivo del usuario, consulta Cómo enviar eventos.

Para obtener detalles sobre cómo controlar los mensajes de los usuarios, como texto, archivos, ubicaciones y otros, consulta Recibe mensajes.

Eventos del usuario

Los eventos de usuario son notificaciones del dispositivo del usuario que informan el estado de los mensajes o los cambios en la suscripción (es decir, si el usuario canceló la suscripción o volvió a suscribirse en Mensajes de Google).

Para ver todas las opciones de formato y valor, consulta la referencia de UserEvent.

El usuario recibe el mensaje del agente

Este evento indica que se entregó correctamente un mensaje al dispositivo del usuario.

{
  "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 una respuesta.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "IS_TYPING",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

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 la acción.

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

El usuario cancela la suscripción a la conversación

Este evento indica que el usuario anuló la suscripción para recibir mensajes no esenciales, como promociones, de tu agente y de la empresa que representa. Los usuarios activan este evento cuando anulan la suscripción a la conversación de RBM en Mensajes de Google.

Importante: Para ayudar a los desarrolladores a realizar la transición a los nuevos eventos de webhook UNSUBSCRIBE y SUBSCRIBE, Mensajes de Google también envía mensajes de "STOP" y "START" junto con los eventos de webhook. Si bien puedes confiar en tu lógica STOP/START existente por ahora, te recomendamos que actualices tu lógica para controlar los eventos UNSUBSCRIBE y SUBSCRIBE, ya que estos serán obligatorios de conformidad con la especificación de la GSMA.

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 cancelación de la suscripción

• La opción Anular la suscripción siempre está disponible en el menú de chat. En el caso de los agentes promocionales y de usos múltiples, 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 por 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 cancelar la suscripción
  Alemania (DE), Estados Unidos (US), India (IN), Países Bajos (NL) y Reino Unido (GB)	DETENER
  España (ES) y México (MX)	BAJA
  Francia (FR)	STOP
  Brasil (BR)	parar

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

• Para identificar los incumplimientos de las políticas y las reglas de la empresa, 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 la conversación, debes enviar de inmediato un mensaje de confirmación con un vínculo directo al sitio web o la app en la que los usuarios puedan administrar sus preferencias de suscripción.
• Después de que el usuario anule la suscripción, se prohíbe el envío de mensajes no esenciales.
• Aún se permiten los mensajes esenciales. Por ejemplo:
  • 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 la suscripción del usuario, con información para administrar aún más sus preferencias de comunicación

Ejemplo

Si un usuario cancela la suscripción a un agente de aerolínea cuyo caso de uso es de uso múltiple, debes dejar de enviarle 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 de la anulación de la suscripción

Cuando un usuario anula la suscripción a tu agente, puede seleccionar un motivo entre las siguientes opciones:

• Demasiados mensajes
• Nunca me registré para obtener este servicio
• Ya no me interesa
• Parece una estafa
• Otro

Para reducir el sesgo de selección, las primeras cuatro opciones se muestran en un orden aleatorio para cada usuario. Este orden se mantiene constante en todas las visitas del usuario, y la opción Otro permanece fija en la parte inferior.

Los motivos de cancelación de la suscripción se agregan y se muestran en la Descripción general de Analytics para ayudarte a comprender por qué los usuarios cancelan sus suscripciones.

El usuario vuelve a suscribirse a la conversación

Este evento indica que un usuario quiere volver a recibir mensajes de tu agente, incluido el contenido no esencial, como las promociones. Los usuarios pueden activar este evento volviendo a suscribirse a una conversación de la que se habían dado de baja anteriormente en Mensajes de Google.

Importante: Para ayudar a los desarrolladores a realizar la transición a los nuevos eventos de webhook UNSUBSCRIBE y SUBSCRIBE, Mensajes de Google también envía mensajes de "STOP" y "START" junto con los eventos de webhook. Si bien puedes confiar en tu lógica STOP/START existente por ahora, te recomendamos que actualices tu lógica para controlar los eventos UNSUBSCRIBE y SUBSCRIBE, ya que estos serán obligatorios de conformidad con la especificación de la GSMA.

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 para volver a suscribirse

• La opción Suscribirse, disponible en el menú del chat y en un vínculo en el chat, permite que los usuarios vuelvan a suscribirse a una conversación de la que se habían dado de baja.

• Si seleccionas Suscribirse, se activan dos acciones simultáneas: Mensajes de Google envía una palabra clave específica del país (por ejemplo, "START") a tu agente, y la plataforma de RBM envía un evento SUBSCRIBE a tu webhook. La palabra clave específica se determina por 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 suscribirse
  Alemania (DE), Estados Unidos (US), India (IN), Países Bajos (NL) y Reino Unido (GB)	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 cumplir con la solicitud del usuario de 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 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 de plataforma

La plataforma de RBM envía eventos de plataforma para notificar a tu agente sobre los cambios en el estado de lanzamiento del agente o los vencimientos de los mensajes.

Cambió el estado de 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. El evento se entrega como un mensaje de Pub/Sub. Para diferenciarlo de otros eventos, verifica la ruta de acceso message.attributes.type para el valor agent_launch_event.

Configuración de webhook

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

Requisitos previos

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

Estructura de carga útil de eventos

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

Advertencia: Los eventos de Pub/Sub siempre se unen, y el contenido del mensaje principal se ubica en el campo message. No implementes una validación de esquema estricta en los campos de wrapper, ya que la plataforma de RCS para empresas no los controla. Si necesitas validar el esquema, impleméntalo a nivel del campo message.

Por ejemplo:

{
  "message": {
    "attributes": {
      "business_id": "[e-mail]",
      "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 lanzamiento del agente. Estos son los valores posibles:

Valor	Estado de lanzamiento del agente	Detalles
PENDING	Pendiente	Se envió la solicitud a un operador para que la revise.
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	Suspendido en un operador determinado	El motivo de la suspensión se especifica en el comentario.
UNLAUNCHED	Sin lanzar	Se permite la edición de los agentes que se inhabilitaron de todos los operadores.

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

 {
      "eventId": "rbm-chatbot-id/0a7ed168-676e-4a56-b422-b23434",
      "agentId": "[e-mail]",
      "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": "[e-mail]",
      "comment": "Carrier has rejected the launch: policy violation",
      "sendTime": "2025-03-05T18:50:19.386436Z"
}

Cambios en el estado de lanzamiento iniciado por el operador

Estas son transiciones permitidas que los operadores suelen controlar durante el proceso de revisión y aplicación de medidas por incumplimiento:

Estado de lanzamiento anterior	Nuevo estado de lanzamiento	Acción de activación
PENDING	LAUNCHED	Aprobar una solicitud de lanzamiento
PENDING	REJECTED	Rechazar una solicitud de lanzamiento
LAUNCHED	SUSPENDED	Suspender por motivos de aplicación de medidas por incumplimiento o de administración
SUSPENDED	LAUNCHED	Restablece el estado activo de un agente.
SUSPENDED	UNLAUNCHED	Finaliza un agente.
REJECTED	LAUNCHED	Aprobar una solicitud de lanzamiento que se rechazó anteriormente

Cambios en el estado de lanzamiento iniciados por el socio

Estas son transiciones permitidas que suelen controlar los socios:

Estado de lanzamiento anterior	Nuevo estado de lanzamiento	Acción de activación
UNSPECIFIED	PENDING	Envía el material para que lo revisemos.
PENDING	UNLAUNCHED	Cancela una solicitud de lanzamiento pendiente.
UNLAUNCHED	PENDING	Envía el material para que lo revisemos.
REJECTED	PENDING	Vuelve a enviarlo para su revisión.
SUSPENDED	PENDING	Vuelve a enviarla para su revisión.

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

Este evento indica que el tiempo de actividad (TTL) del mensaje venció y que el mensaje se revocó correctamente. Este es un buen activador para tu estrategia de mensajería de resguardo.

Para ver todas las opciones de formato y valor, consulta la referencia de ServerEvent.

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

El mensaje venció; no se pudo revocar

Este evento indica que el TTL del mensaje venció, pero no se revocó correctamente.

Para ver todas las opciones de formato y valor, consulta la referencia de ServerEvent.

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

No se garantiza la entrega de mensajes.

• Si se entregó el mensaje, recibirás un evento DELIVERED en 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.