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 plataforma: Son notificaciones sobre los cambios en el 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 Envía 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 del usuario son notificaciones del dispositivo del usuario que informan el estado de los mensajes o los cambios en la suscripción (es decir, el usuario anuló o restableció la suscripción en Mensajes de Google).

Para obtener información completa sobre el formato y las opciones de valores, consulta la UserEvent referencia.

El usuario recibe un 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 un mensaje del agente

Este evento indica que se abrió o se 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 llamada 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

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

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 anulació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 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), Alemania (DE) y Países Bajos (NL) DETENER
    España (ES) y México (MX) BAJA
    Francia (FR) DETENER
    Brasil (BR) parar

  • Después de que el usuario anula 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 bloqueados.

  • Para identificar incumplimientos de políticas y reglas de negocio, 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 de anular la suscripción.
  • Si no puedes anular la suscripción dentro del hilo de mensajes, 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 pueden administrar sus preferencias de suscripción.
  • Después de que el usuario anula la suscripción, se prohíbe enviar mensajes no esenciales.
  • Aún se permiten los mensajes esenciales. Estos incluyen lo siguiente:
    • 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 anulació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 anula la suscripción a un agente de aerolínea cuyo caso de uso es de uso múltiple, debes dejar de enviar mensajes de marketing. Sin embargo, puedes enviar actualizaciones de vuelos si el usuario dio su consentimiento explícito para recibirlas en relación con ese vuelo específico.

Motivos de anulación de la suscripción

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

  • Spam
  • Usuarios que nunca se registraron
  • Demasiados mensajes
  • Ya no me interesa
  • Otro

Los motivos de anulación de la suscripción se muestran en la descripción general de Analytics para ayudar a los socios a comprender por qué los usuarios anulan la suscripción.

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

Este evento indica que un usuario quiere volver a recibir mensajes de tu agente, incluido contenido no esencial, como promociones. Los usuarios pueden activar este evento si restablecen la suscripción a una conversación de la que habían anulado la suscripción anteriormente en Mensajes de Google.

Este es un ejemplo de la carga útil de JSON:

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

Cómo funciona volver a suscribirse

  • Una opción Suscribirse, disponible en el menú de chat y en un vínculo en el chat, permite que los usuarios vuelvan a suscribirse 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 para suscribirse
    Estados Unidos (US), India (IN), Reino Unido (GB), Alemania (DE) y Países Bajos (NL) 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 restablecer la suscripción.
  • El restablecimiento de la 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, esto se puede considerar una solicitud para volver a suscribirse.
  • Si un usuario restablece la suscripción 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 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 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 de usuario).
  • Para diferenciar entre los eventos de usuario y los eventos de estado de lanzamiento 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. 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 de 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 una empresa de transporte para su revisión.
LAUNCHED Lanzado Se permiten los mensajes en una empresa de transporte determinada.
REJECTED Rechazado en una empresa de transporte determinada El motivo del rechazo se especifica en el comentario.
SUSPENDED Suspendido en una empresa de transporte determinada El motivo de la suspensión se especifica en el comentario.
UNLAUNCHED No lanzado Se permite la edición para los agentes que no se lanzaron en todas las empresas de transporte.

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

Cambios en el estado de lanzamiento iniciados por la empresa de transporte

Estas son las transiciones permitidas que suelen controlar las empresas de transporte durante el proceso de revisión y aplicación:

Estado de lanzamiento anterior Estado de lanzamiento nuevo 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 o administración
SUSPENDED LAUNCHED Restablecer un agente al estado activo
SUSPENDED UNLAUNCHED Cancelar un agente

Cambios en el estado de lanzamiento iniciados por el socio

Estas son las transiciones permitidas que suelen controlar los socios:

Estado de lanzamiento anterior Estado de lanzamiento nuevo Acción de activación
UNSPECIFIED PENDING Enviar para revisión
UNLAUNCHED PENDING Enviar para revisión
REJECTED PENDING Volver a enviar para revisión

Venció el mensaje; se revocó correctamente

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

Para obtener información completa sobre el formato y las opciones de valores, consulta la ServerEvent referencia.

{
  "phoneNumber": "[phone number]" ,
  "messageId": "[RCS message ID]",
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

Venció el mensaje; no se revocó

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

Para obtener información completa sobre el formato y las opciones de valores, consulta la ServerEvent referencia.

{
  "phoneNumber": "[phone number]",
  "messageId": "[RCS message ID]",
  "agentId": "[bot ID]",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

No se garantiza la entrega de mensajes.

Si el mensaje es sensible al tiempo, 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.

Anterior
Enviar eventos
Siguiente
Verificaciones de capacidades