Recibir mensajes

Después de registrarte en Business Messages, puedes recibir mensajes en nombre de tu agente de prueba. Puedes recibir mensajes de las marcas que administras después de crear, verificar y, también, iniciar agentes para esas marcas.

Cuando un cliente envía un mensaje a un agente que administras, Business Messages envía una carga útil de JSON a tu webhook que contiene varios ID, información de ubicación y contenido de mensajes.

Usa la página de registros de la consola para desarrolladores de Business Communications a fin de depurar los problemas de entrega de mensajes.

Administra mensajes entrantes

La forma en que tu agente maneja y responde los mensajes de los usuarios depende en gran medida de tu lógica empresarial. Sin embargo, por lo general, los pasos para responder a un mensaje del usuario son coherentes.

Nota: En caso de que falte un campo en una carga útil de mensaje, tu agente debe procesar el mensaje de la mejor manera posible.

Confirma el mensaje

Para confirmar un mensaje recibido por tu webhook, muestra una respuesta HTTP válida para los mensajes enviados a tu webhook.

Si un mensaje no se puede entregar debido al tiempo de espera de entrega, la accesibilidad del webhook, el redireccionamiento o los problemas de permisos, Google almacena y reenvía el mensaje, con varios reintentos, durante 7 días o hasta que tu webhook reciba el mensaje de forma correcta.

Verifica que el mensaje sea de Google

Debes verificar que Google haya enviado el mensaje antes de procesar su contenido.

Para verificar si Google envió un mensaje que recibiste,

1. Analiza el encabezado X-Goog-Signature del mensaje. Esta es una copia codificada en base64 de la carga útil del cuerpo del mensaje.

2. Con el token de cliente (que se presentó cuando configuraste el webhook) como clave, crea un HMAC SHA512 de los bytes de la carga útil del mensaje y codifica el resultado en base64.

   Nota: Si recibiste una clave de socio durante el registro con Business Messages, úsala como clave para SHA512 HMAC en lugar del token de cliente. Si actualizas tu webhook, usa el token de cliente para la validación de mensajes con la nueva configuración de webhook.

3. Compara el hash de X-Goog-Signature con el que creaste.

   • Si los hash coinciden, significa que confirmaste que Google envió el mensaje.
   • Si los hash no coinciden, verifica tu proceso de hash en un mensaje conocido. Si tu proceso de hash funciona correctamente y recibes un mensaje que indica que te enviaron de manera fraudulenta, comunícate con nosotros (debes acceder con una cuenta de Business Messages Google).

Consulta el ejemplo de verificación de mensajes en los repositorios de GitHub para los Echo Bots en Java, Node.js y Python.

Identifica la configuración regional

Los usuarios se comunican desde muchas ubicaciones y en muchos idiomas. Business Messages representa las preferencias de idioma de los usuarios con los campos resolvedLocale y userDeviceLocale, que se basan en la configuración regional de sus dispositivos. Consulta Localización y configuraciones regionales.

Siempre que sea posible, enruta los mensajes y redacta las respuestas según las preferencias de idioma de los usuarios.

Enrutar el mensaje según su contexto

El contexto del mensaje informa qué tipo de información podría buscar el usuario. Por ejemplo, si un usuario envía un mensaje con un valor placeId, envió un mensaje a una ubicación específica (identificada por placeId) y es probable que haga preguntas específicas sobre la ubicación. De manera similar, si un mensaje tiene un valor nearPlaceId, que identifica una ubicación cercana al usuario, es probable que este desee obtener información específica de la ubicación, pero el agente debe confirmar la ubicación con la que el usuario desea chatear antes de iniciar la conversación.

Con la información de contexto del mensaje, enruta el mensaje a la ubicación más adecuada para responder:

• Si el mensaje está en una conversación nueva y es una pregunta común, puedes responder con automatización.
• Si la automatización no puede responder la pregunta, diríjala a un agente humano.
• Si la configuración regional del mensaje no coincide con la predeterminada de tu agente, enruta el mensaje a un agente humano que pueda admitir esa configuración regional.
• Si la pregunta es sobre una ubicación específica, dirígela a alguien con información sobre esa ubicación.
• Si el mensaje está en una conversación en curso, enruta el mensaje al agente en vivo que participa en la conversación.

Identificar el tipo de mensaje que envió el usuario

Los usuarios pueden enviar tres tipos de mensajes:

• Los mensajes de texto son respuestas de formato libre.
• Los mensajes de imagen incluyen una URL firmada para una imagen que subió el usuario.
• Los mensajes de sugerencia incluyen los datos de notificación y el texto de la acción sugerida o la respuesta sugerida que el usuario presionó.

Cómo procesar el contenido del mensaje

Si tu agente usa la automatización, el contenido del mensaje del usuario debe guiar la lógica y la siguiente respuesta de tu agente en la conversación.

La forma más sencilla de identificar la intención del usuario es con datos de notificación de respuesta o acción sugerida. Sin importar el texto asociado con la sugerencia, los datos de notificación son legibles por máquina.

Si un usuario envía un mensaje de texto, tu agente puede analizar la respuesta en busca de palabras clave compatibles o usar la comprensión del lenguaje natural (como con la integración en Dialogflow) para procesar el mensaje del usuario e identificar una ruta.

Si tu agente no sabe cómo responder el mensaje del usuario, debe responder con un estado de error y tratar de continuar la conversación pidiéndole información adicional, pidiéndole información de otra manera o entregando la conversación a un agente humano.

Responde al usuario

Una vez que el agente identifica la respuesta correcta, ya sea mediante la automatización o un agente en vivo, envía un mensaje y continúa la conversación con el usuario.

Cuando redactes una respuesta, ten en cuenta la configuración regional del usuario. Además, puedes personalizar las respuestas si recuperas los valores del objeto userInfo en cada mensaje que recibas.

Nota: Si habilitas las respuestas automáticas en la integración de Dialogflow, Business Messages y Dialogflow responden a los usuarios en tu nombre con la mejor respuesta coincidente.

Tipos de mensajes

El siguiente código muestra cómo tu agente recibe mensajes.

Para obtener información sobre el formato y el valor, consulta UserMessage.

Texto

La forma más común para que los usuarios respondan es con texto sin formato. Los mensajes de texto tienen el siguiente formato.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "message": {
    "messageId": "MESSAGE_ID",
    "name": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "text": "MESSAGE_TEXT",
    "createTime": "MESSAGE_CREATE_TIME",
  },
  "dialogflowResponse": {
    "autoResponded": "BOOLEAN",
    "faqResponse": {
      "userQuestion": "USER_QUESTION",
      "answers": [{
        "faqQuestion": "FAQ_QUESTION",
        "faqAnswer": "FAQ_ANSWER",
        "matchConfidenceLevel": "CONFIDENCE_LEVEL",
        "matchConfidence": "CONFIDENCE_NUMERIC",
      }],
    },
  },
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

Para ver las opciones de formato y de valor, consulta Message.

De imagen

Además de enviar texto, los usuarios pueden enviar imágenes a tu agente como mensajes. Business Messages almacena imágenes compartidas durante 7 días en URL firmadas y, también, incluye esas URL en el campo text de la carga útil del mensaje.

Si tu agente incluye la automatización, asegúrate de que la automatización sepa cómo responder si un usuario comparte una imagen. Para los agentes humanos, asegúrate de que las imágenes se pasen o que se pueda hacer clic en las URL en los mensajes.

...
"message": {
    "text": "https://storage.googleapis.com/business-messages-us/936640919331/jzsu6cdguNGsBhmGJGuLs1DS?x-goog-algorithm\u003dGOOG4-RSA-SHA256\u0026x-goog-credential\u003duranium%40rcs-uranium.iam.gserviceaccount.com%2F20190826%2Fauto%2Fstorage%2Fgoog4_request\u0026x-goog-date\u003d20190826T201038Z\u0026x-goog-expires\u003d604800\u0026x-goog-signedheaders\u003dhost\u0026x-goog-signature\u003d89dbf7a74d21ab42ad25be071b37840a544a43d68e67270382054e1442d375b0b53d15496dbba12896b9d88a6501cac03b5cfca45d789da3e0cae75b050a89d8f54c1ffb27e467bd6ba1d146b7d42e30504c295c5c372a46e44728f554ba74b7b99bd9c6d3ed45f18588ed1b04522af1a47330cff73a711a6a8c65bb15e3289f480486f6695127e1014727cac949e284a7f74afd8220840159c589d48dddef1cc97b248dfc34802570448242eac4d7190b1b10a008404a330b4ff6f9656fa84e87f9a18ab59dc9b91e54ad11ffdc0ad1dc9d1ccc7855c0d263d93fce6f999971ec79879f922b582cf3bb196a1fedc3eefa226bb412e49af7dfd91cc072608e98"
  }
...

Para ver las opciones de formato y de valor, consulta Message.

Suggestion

Las respuestas sugeridas y las acciones sugeridas permiten a los usuarios responder o realizar acciones con solo presionar un botón. Cuando un usuario presiona una sugerencia, el agente recibe una carga útil con el texto de la sugerencia y los datos de notificación.

Los mensajes de sugerencias tienen el siguiente formato.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "suggestionResponse": {
    "message": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "postbackData": "POSTBACK_DATA",
    "createTime": "RESPONSE_CREATE_TIME",
    "text": "SUGGESTION_TEXT",
    "suggestionType": "SUGGESTION_TYPE",
  }
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

Para ver las opciones de formato y de valor, consulta SuggestionResponse.

Solicitud de autenticación

La sugerencia de solicitud de autenticación permite a los usuarios acceder con un proveedor de OAuth para proporcionar detalles de identidad con el agente o permitir que este realice acciones en nombre de los usuarios. Consulta Autentica con OAuth.

Si un usuario accede correctamente con el proveedor de OAuth especificado, el agente recibe una carga útil con el código de autorización. Si un usuario no puede acceder, el agente recibe una carga útil con detalles de errores.

Los mensajes de solicitud de autenticación tienen el siguiente formato.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "authenticationResponse": {
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "REDIRECT_URI",
    "errorDetails": {
      "error": "ERROR",
      "errorDescription": "ERROR_DESCRIPTION",
    },
  }
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

Para ver las opciones de formato y de valor, consulta AuthenticationResponse.

Contexto del mensaje

Cada mensaje contiene información contextual sobre el lugar donde se originó el mensaje.

...
  "context": {
    "customContext": "CUSTOM_CONTEXT",
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "nearPlaceId": "NEARBY_LOCATION_PLACE_ID",
    "deflectedPhoneNumber": "DEFLECTED_PHONE_NUMBER",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
    "widget": {
      "url": "WEBSITE_URL",
      "widgetContext": "WIDGET_CONTEXT",
    },
  },
...

Campo	Descripción
customContext	Datos de contexto especificados por el socio
entryPoint	La superficie de mensajería desde la que el usuario comenzó la conversación, según lo definido por EntryPoint.
placeId	Un identificador único de la base de datos de Google Places para la ubicación a la que el usuario envió el mensaje. Solo aparece en mensajes de puntos de entrada específicos de la ubicación.
nearPlaceId	Un identificador único de la base de datos de Google Places para la primera ubicación en un paquete local. Confirma las ubicaciones con las que los usuarios quieren chatear cuando recibas valores nearPlaceId.
deflectedPhoneNumber	Es el número de teléfono que Business Messages desvió al usuario de llamar cuando comenzó la conversación.
resolvedLocale	La mejor coincidencia calculada de la configuración regional del usuario (informada en userDeviceLocale) y las configuraciones regionales compatibles del agente (determinada por la configuración de conversación especificada) Consulta Localización y Cómo iniciar la conversación. El valor de configuración regional es una etiqueta de idioma IETF BCP 47 bien formada.
userInfo.displayName	El nombre del usuario que envió el mensaje. Si el usuario inhabilita el uso compartido de identidades, este campo estará vacío.
userInfo.userDeviceLocale	La configuración regional del usuario, informada por su dispositivo, como una etiqueta de idioma IETF BCP 47 bien formada.
widget.url	Es la URL del sitio web en el que se lanzó la plataforma de conversación.
widget.widgetContext	El valor del atributo data-bm-widget-context del widget que se usa para iniciar la conversación.

Historial de conversaciones

Google no proporciona historiales de conversaciones. Mantén tus propias conversaciones históricas, de una manera que cumpla con tu política de privacidad y prácticas recomendadas, para que puedas enviar respuestas fundamentadas a mensajes futuros de los usuarios.