Получать сообщения

После регистрации в Business Messages вы сможете получать сообщения от имени вашего тестового агента. Вы можете получать сообщения для брендов, которыми вы управляете, после создания , проверки и запуска агентов для этих брендов.

Когда клиент отправляет сообщение агенту, которым вы управляете, Business Messages отправляет полезные данные JSON на ваш веб-перехватчик, который содержит различные идентификаторы, содержимое сообщения и информацию о местоположении.

Используйте страницу журналов консоли разработчика Business Communications для устранения проблем с доставкой сообщений.

Обрабатывать входящие сообщения

То, как ваш агент обрабатывает сообщения от пользователей и отвечает на них, сильно зависит от вашей бизнес-логики. Однако, как правило, шаги по ответу на сообщение пользователя согласуются.

Примечание. Если в полезной нагрузке сообщения отсутствует какое-либо поле, ваш агент все равно должен обработать сообщение в меру своих возможностей.

Подтвердите сообщение

Чтобы подтвердить сообщение, полученное вашим веб-перехватчиком, верните действительный ответ HTTP на сообщения, отправленные на ваш веб-перехватчик.

Если сообщение не может быть доставлено из-за тайм-аута доставки, доступности веб-перехватчика, перенаправления или проблем с разрешениями, Google сохраняет и пересылает сообщение с несколькими попытками в течение 7 дней или до тех пор, пока ваш веб-перехватчик не получит сообщение.

Убедитесь, что сообщение от Google

Вы должны убедиться, что Google отправил сообщение, прежде чем обрабатывать его содержимое.

Чтобы убедиться, что Google отправил полученное вами сообщение,

1. Разберите заголовок X-Goog-Signature сообщения. Это хешированная копия полезной нагрузки тела сообщения в кодировке base64.

2. Используя свой клиентский токен (который был представлен при настройке веб-перехватчика ) в качестве ключа, создайте SHA512 HMAC байтов полезной нагрузки сообщения и закодируйте результат в base64.

   Примечание. Если вы получили партнерский ключ во время регистрации в Business Messages, используйте его в качестве ключа для SHA512 HMAC вместо токена клиента. Если вы обновляете свой веб-перехватчик, используйте токен клиента для проверки сообщения с новой конфигурацией веб-перехватчика.

3. Сравните хэш X-Goog-Signature с созданным вами хэшем.

   • Если хэши совпадают, вы подтверждаете, что Google отправил сообщение.
   • Если хэши не совпадают, проверьте процесс хеширования заведомо исправного сообщения. Если ваш процесс хеширования работает правильно, и вы получаете сообщение, которое, по вашему мнению, было отправлено вам мошенническим путем,свяжитесь с нами (вы должны войти в систему с помощью учетной записи Google Business Messages).

См. пример проверки сообщения в репозиториях GitHub для ботов Echo на Java , Node.js и Python .

Определите регион

Пользователи общаются из многих мест и на многих языках. Business Messages представляет языковые предпочтения пользователей с помощью полей resolvedLocale и userDeviceLocale , которые основаны на региональных настройках их устройств. См. Локализация и локали .

По возможности маршрутизируйте сообщения и составляйте ответы на основе языковых предпочтений пользователей.

Маршрутизация сообщения на основе его контекста

Контекст сообщения сообщает, какую информацию может искать пользователь. Например, если пользователь отправляет сообщение со значением placeId , он отправил сообщение в определенное место (определяемое placeId ) и, скорее всего, задаст вопросы, связанные с местоположением. Точно так же, если сообщение имеет значение nearPlaceId , которое идентифицирует местоположение рядом с пользователем, пользователь, вероятно, захочет узнать информацию о конкретном местоположении, но агент должен подтвердить местоположение, с которым пользователь хочет пообщаться, прежде чем начать разговор.

С информацией о контексте сообщения направьте сообщение в место, наиболее подходящее для ответа:

• Если сообщение находится в новой беседе и является распространенным вопросом, вы можете ответить с помощью автоматизации.
• Если автоматизация не может ответить на вопрос, направьте его живому агенту.
• Если языковой стандарт сообщения не соответствует языковому стандарту вашего агента по умолчанию, направьте сообщение активному агенту, который может поддерживать этот языковой стандарт.
• Если вопрос касается определенного места, перенаправьте его тому, у кого есть информация об этом месте.
• Если сообщение находится в текущем разговоре, направьте его агенту, участвующему в разговоре.

Определите тип сообщения, отправленного пользователем

Пользователи могут отправлять три типа сообщений:

• Текстовые сообщения являются ответами произвольной формы.
• Сообщения с изображениями включают подписанный URL-адрес изображения, загруженного пользователем.
• Сообщения с предложениями включают данные обратной передачи и текст предлагаемого действия или предлагаемого ответа, который нажал пользователь.

Обработать содержимое сообщения

Если ваш агент использует автоматизацию, содержание пользовательского сообщения должно определять логику вашего агента и следующий ответ в разговоре.

Самый простой способ определить намерение пользователя — использовать данные обратной передачи из предлагаемого ответа или предлагаемого действия. Независимо от текста, связанного с предложением, данные обратной передачи являются машиночитаемыми.

Если пользователь отправляет текстовое сообщение, ваш агент может проанализировать ответ на наличие поддерживаемых ключевых слов или использовать понимание естественного языка (например, с интеграцией Dialogflow для обработки сообщения пользователя и определения пути вперед.

Если ваш агент не знает, как ответить на сообщение пользователя, он должен ответить состоянием ошибки и попытаться продолжить разговор, запросив у пользователя дополнительную информацию, запросив ввод другим способом или передав разговор с живым агентом.

Ответ пользователю

После того, как агент определяет правильный ответ — либо с помощью автоматизации, либо с помощью живого агента — он отправляет сообщение и продолжает разговор с пользователем.

При составлении ответа учитывайте языковой стандарт пользователя. Вы можете дополнительно настроить ответы, извлекая значения из объекта userInfo в каждом полученном сообщении.

Примечание. Если вы включите автоматические ответы в интеграции Dialogflow , Business Messages и Dialogflow будут отвечать пользователям от вашего имени наиболее подходящим ответом.

Типы сообщений

Следующий код показывает, как ваш агент получает сообщения.

Сведения о форматировании и значениях см. в разделе UserMessage .

Текст

Самый распространенный способ ответа пользователей — это обычный текст. Текстовые сообщения имеют следующий формат.

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

Параметры форматирования и значений см. в разделе Message .

Изображение

Помимо отправки текста, пользователи могут отправлять вашему агенту изображения в виде сообщений. Деловые сообщения хранят общие изображения в течение 7 дней по подписанным URL -адресам и включают эти URL-адреса в text поле полезной нагрузки сообщения.

Если ваш агент включает в себя автоматизацию, убедитесь, что автоматизация знает, как реагировать, если пользователь делится изображением. Для активных агентов убедитесь, что изображения передаются или что URL-адреса в сообщениях кликабельны.

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

Параметры форматирования и значений см. в разделе Message .

Предложение

Предлагаемые ответы и предлагаемые действия позволяют пользователям отвечать или выполнять действия одним касанием. Когда пользователь нажимает на предложение, агент получает полезную нагрузку с текстом предложения и данными обратной передачи.

Сообщения с предложениями имеют следующий формат.

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

Параметры форматирования и значений см. в разделе SuggestionResponse .

Запрос аутентификации

Предложение запроса аутентификации позволяет пользователям войти в систему с помощью поставщика OAuth, чтобы предоставить агенту идентификационные данные или разрешить агенту выполнять действия от имени пользователей. См. Аутентификация с помощью OAuth .

Если пользователь успешно входит в систему с помощью указанного поставщика OAuth, агент получает полезную нагрузку с кодом авторизации. Если пользователю не удается войти в систему, агент получает полезные данные со сведениями об ошибке.

Сообщения запроса аутентификации имеют следующий формат.

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

Параметры форматирования и значений см. в разделе AuthenticationResponse .

Контекст сообщения

Каждое сообщение содержит контекстную информацию о том, откуда оно было отправлено.

...
  "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",
    },
  },
...

Поле	Описание
customContext	Контекстные данные, указанные партнером.
entryPoint	Поверхность обмена сообщениями, с которой пользователь начал беседу, как определено EntryPoint .
placeId	Уникальный идентификатор из базы данных Google Places местоположения, о котором сообщил пользователь. Он появляется только в сообщениях из точек входа, зависящих от местоположения.
nearPlaceId	Уникальный идентификатор из базы данных Google Places для первого местоположения в локальном пакете. Подтвердите местоположения, с которыми пользователи хотят общаться, когда вы получите значения nearPlaceId .
deflectedPhoneNumber	Номер телефона, на который Business Messages отклонил звонок пользователя при начале разговора.
resolvedLocale	Наилучшее вычисленное совпадение языкового стандарта пользователя (сообщается в userDeviceLocale ) и языковых стандартов, поддерживаемых агентом (определяемых указанными диалоговыми настройками). См. раздел Локализация и начните разговор . Значение локали — это правильно сформированный языковой тег IETF BCP 47 .
userInfo.displayName	Имя пользователя, отправившего сообщение. Если пользователь отказывается от обмена идентификационными данными, это поле остается пустым.
userInfo.userDeviceLocale	Языковой стандарт пользователя, сообщаемый его устройством, в виде правильно сформированного языкового тега IETF BCP 47 .
widget.url	URL-адрес веб-сайта, на котором запущена диалоговая поверхность.
widget.widgetContext	Значение атрибута data-bm-widget-context виджета, используемого для начала диалога.

История разговоров

Google не предоставляет истории разговоров. Сохраняйте свои собственные исторические разговоры в соответствии с вашей политикой конфиденциальности и рекомендациями, чтобы вы могли отправлять информированные ответы на будущие сообщения от пользователей.