Cómo recibir eventos

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

Estos eventos se clasifican según su origen:

  • Eventos de usuario: Son las notificaciones que se envían desde el dispositivo de un usuario a tu agente y que indican una interacción con tu agente o sus mensajes.
  • Eventos de la plataforma: Son notificaciones sobre los cambios en el estado de lanzamiento del agente y el vencimiento 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ío de eventos.

Eventos del usuario

Los eventos del usuario son notificaciones del dispositivo del usuario que informan el estado de los mensajes o los cambios en las suscripciones (es decir, el usuario se dio de baja o se volvió a suscribir en Mensajes de Google).

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

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 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 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

Este evento indica que el usuario anuló la suscripción para dejar de recibir mensajes no esenciales, como promociones, de tu agente y la empresa que representa. Los usuarios activan este evento cuando cancelan 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 activarán dos acciones simultáneas: Mensajes de Google enviará una palabra clave específica del país (por ejemplo, “DETENER”) a tu agente, y la plataforma de RBM enviará 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 las políticas y las 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.
  • Aún se permiten 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ínea 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 anulación de la suscripción

Cuando un usuario se da de baja de 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 la anulación de la suscripción se muestran en el Resumen de Analytics para ayudar a los socios a comprender por qué los usuarios anulan la suscripción.

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

  • 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 de plataforma

La plataforma de RBM envía eventos de la plataforma para notificar a tu agente sobre los cambios en el estado de lanzamiento del agente o los vencimientos de 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 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 y eventos de usuarios).
  • Para diferenciar entre los eventos del usuario y los eventos de estado de inicio del agente, verifica la ruta 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 de 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 una empresa de transporte determinada 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 lanzamiento 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

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 mensajes de resguardo.

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

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

El mensaje venció y no se pudo revocar

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

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

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

Anterior
Enviar eventos
Siguiente
Verificaciones de capacidades