Otrzymywanie wiadomości

Po zarejestrowaniu się w usłudze Business Messages możesz odbierać wiadomości w imieniu swojego agenta testowego. Możesz otrzymywać wiadomości dotyczące marek, którymi zarządzasz po utworzeniu, zweryfikowaniu i uruchomieniu agentów dla tych marek.

Gdy klient wysyła wiadomość do agenta, którym zarządzasz, Business Messages wysyła ładunek JSON do webhooka zawierającego różne identyfikatory, treść wiadomości i informacje o lokalizacji.

Aby debugować problemy z dostarczaniem wiadomości, użyj strony logów konsoli dla firm Business Communications.

Obsługa wiadomości przychodzących

Sposób, w jaki agent obsługuje wiadomości od użytkowników i odpowiada na nie, zależy w dużym stopniu od logiki Twojej firmy. Ogólnie jednak czynności wymagane w odpowiedzi na wiadomość użytkownika są spójne.

Potwierdzanie odebrania wiadomości

Aby potwierdzić wiadomość otrzymaną przez webhooka, ustaw prawidłową odpowiedź HTTP na wiadomości wysyłane do webhooka.

Jeśli wiadomość nie zostanie dostarczona z powodu przekroczenia limitu czasu, problemu z osiąganiem, przekierowaniem lub uprawnieniami webhooka, Google przechowuje i przekazuje wiadomość z wieloma kolejnymi próbami przez 7 dni lub do momentu, aż webhook ją otrzyma.

Sprawdzanie, czy wiadomość pochodzi od Google

Przed przetworzeniem treści sprawdź, czy firma Google wysłała wiadomość.

Aby sprawdzić, czy wysłaliśmy do Ciebie wiadomość,

  1. Przeanalizuj nagłówek X-Goog-Signature wiadomości. To zaszyfrowana kopia ładunku treści wiadomości zakodowana w formacie base64.

  2. Użyj tokena klienta (który został podany podczas konfigurowania webhooka) jako klucza, utwórz SHA512 MAC-a MAC-a ładunku wiadomości i zakoduj wynik.

  3. Porównaj skrót X-Goog-Signature z utworzonym skrótem.

    • Jeśli hasze są zgodne, oznacza to, że wiadomość została wysłana przez Google.
    • Jeśli hasze nie pasują, sprawdź proces szyfrowania w dobrze znanej wiadomości. Jeśli proces haszowania działa prawidłowo i widzisz wiadomość, która Twoim zdaniem została wysłana w wyniku oszustwa, skontaktuj się z nami (musisz zalogować się za pomocą konta Google Business Messages).

Zobacz przykład weryfikacji wiadomości w repozytoriach GitHuba dla botów Echo w językach Java, Node.js i Python.

Identyfikuj język

Użytkownicy komunikują się z wielu lokalizacji i w wielu językach. Business Messages przedstawia ustawienia językowe użytkowników w polach resolvedLocale i userDeviceLocale, które zależą od ustawień regionalnych urządzenia. Zobacz Lokalizacja i ustawienia regionalne.

Tam, gdzie to możliwe, przekazuj wiadomości i twórz odpowiedzi na podstawie preferencji językowych użytkowników.

Kierowanie wiadomości na podstawie jej kontekstu

Kontekst wiadomości informuje, jakich informacji może szukać użytkownik. Jeśli na przykład użytkownik wyśle wiadomość z wartością placeId, to mógł odpowiedzieć na konkretną lokalizację (określoną przez placeId) i prawdopodobnie odpowie na pytania dotyczące lokalizacji. I podobnie, jeśli wiadomość ma wartość nearPlaceId, która identyfikuje lokalizację w pobliżu użytkownika, prawdopodobnie chce poznać informacje dotyczące konkretnej lokalizacji, ale agent powinien potwierdzić lokalizację, z którą chce porozmawiać na czacie przed rozpoczęciem rozmowy.

Korzystając z informacji kontekstowych, przekaż wiadomość do lokalizacji, w której najlepiej na nią odpowiedzieć:

  • Jeśli wiadomość jest w nowej rozmowie i jest to najczęstsze pytanie, możesz odpowiedzieć przy użyciu automatyzacji.
  • Jeśli automatyzacja nie może odpowiedzieć na to pytanie, przekieruj go do pracownika obsługi klienta.
  • Jeśli język wiadomości nie pasuje do języka domyślnego agenta, przekaż wiadomość do pracownika obsługi klienta, który obsługuje dany język.
  • Jeśli pytanie dotyczy konkretnej lokalizacji, przekieruj tę osobę do osób, które mają dane o tej lokalizacji.
  • Jeśli wiadomość jest w trakcie trwającej rozmowy, przekieruj ją do pracownika obsługi klienta, który bierze udział w rozmowie.

Określanie typu wiadomości wysłanej przez użytkownika

Użytkownicy mogą wysyłać 3 rodzaje wiadomości:

  • SMS-y są swobodnymi odpowiedziami,
  • Wiadomości zawierające obraz zawierają podpisany adres URL obrazu przesłanego przez użytkownika.
  • Wiadomości sugestii zawierają dane zwrotne i tekst sugerowanej czynności lub sugerowanej odpowiedzi klikniętej przez użytkownika.

Przetwarzanie treści wiadomości

Jeśli Twój agent korzysta z automatyzacji, treść wiadomości użytkownika powinna być zgodna z logiką agenta i następną odpowiedzią w wątku.

Najłatwiejszym sposobem rozpoznania zamiaru użytkownika jest użycie danych zwrotnych z sugerowanej odpowiedzi lub sugerowanego działania. Niezależnie od tekstu powiązanego z sugestią dane wywołania zwrotnego są czytelne dla komputerów.

Jeśli użytkownik wyśle SMS-a, agent może przeanalizować odpowiedź pod kątem obsługiwanych słów kluczowych lub użyć rozumienia języka naturalnego (np. za pomocą integracji Dataflow, aby przetworzyć wiadomość użytkownika i zidentyfikować ścieżkę.

Jeśli agent nie wie, jak odpowiedzieć na wiadomość użytkownika, powinien wyświetlić się komunikat o błędzie i kontynuować rozmowę, podając użytkownikowi dodatkowe informacje, prosząc o podanie innego sposobu lub przekazując rozmowę do pracownika obsługi klienta.

Odpowiedz użytkownikowi

Gdy agent zidentyfikuje właściwą odpowiedź – za pomocą automatyzacji lub trwającego agenta – wysyła wiadomość i kontynuuje rozmowę z użytkownikiem.

Podczas tworzenia odpowiedzi weź pod uwagę język użytkownika. Możesz też dostosować odpowiedzi, pobierając wartości z obiektu userInfo w każdej odebranej wiadomości.

Rodzaje wiadomości

Ten kod pokazuje, jak agent otrzymuje wiadomości.

Formatowanie i wartości znajdziesz na stronie UserMessage.

Tekst

Najczęstszym sposobem, w jaki użytkownicy mogą odpowiadać, jest zwykły tekst. SMS-y mają następujący format.

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

Opcje formatowania i opcji wartości znajdziesz na stronie Message.

Obraz

Oprócz wysyłania wiadomości użytkownicy mogą też wysyłać obrazy do agenta jako wiadomości. Business Messages przechowuje udostępnione obrazy przez 7 dni pod podpisanymi adresami URL i uwzględnia te adresy URL w polu text ładunku wiadomości.

Jeśli agent obejmuje automatyzację, upewnij się, że wie, jak odpowiedzieć, jeśli użytkownik udostępni obraz. W przypadku agentów na żywo upewnij się, że obrazy są przekazywane lub że adresy URL w wiadomościach można kliknąć.

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

Opcje formatowania i opcji wartości znajdziesz na stronie Message.

Sugestia

Sugerowane odpowiedzi i sugerowane czynności umożliwiają użytkownikom odpowiadanie jednym kliknięciem lub wykonywanie czynności. Gdy użytkownik kliknie sugestię, agent otrzyma ładunek z tekstem sugestii i danymi wywołania zwrotnego.

Wiadomości z sugestią mają następujący format.

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

Opcje formatowania i opcji wartości znajdziesz na stronie SuggestionResponse.

Prośba o uwierzytelnienie

Sugestia żądania uwierzytelniania pozwala użytkownikom logować się przy użyciu dostawcy OAuth, aby podawać im szczegółowe informacje o tożsamości lub umożliwiać agentowi wykonywanie działań w imieniu użytkowników. Zobacz Uwierzytelnianie za pomocą protokołu OAuth.

Jeśli użytkownik zaloguje się przy użyciu określonego dostawcy OAuth, agent otrzyma ładunek z kodem autoryzacji. Jeśli nie uda się zalogować użytkownika, agent otrzyma ładunek ze szczegółami błędów.

Wiadomości z prośbą o uwierzytelnienie mają następujący format.

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

Opcje formatowania i opcji wartości znajdziesz na stronie AuthenticationResponse.

Kontekst wiadomości

Każda wiadomość zawiera informacje kontekstowe dotyczące pochodzenia wiadomości.

...
  "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",
    },
  },
...
Pole Opis
customContext Dane kontekstowe określone przez partnera.
entryPoint Komunikat, w którym użytkownik rozpoczął rozmowę, zgodnie z definicją w EntryPoint.
placeId Unikalny identyfikator bazy danych Miejsc Google przypisany do lokalizacji, do której użytkownik wysłał wiadomość. Pojawia się tylko w wiadomościach z punktów wejścia właściwych dla lokalizacji.
nearPlaceId Unikalny identyfikator pierwszej bazy danych miejsca w lokalnym pakiecie danych Miejsc Google. Potwierdź lokalizacje, z którymi użytkownicy mają czatować, gdy otrzymasz wartości nearPlaceId.
deflectedPhoneNumber Numer telefonu, z którego Wiadomości biznesowe przestały dzwonić po rozpoczęciu rozmowy.
resolvedLocale

Największe obliczone dopasowanie do języka użytkownika (zgodnie z raportem w userDeviceLocale) i regionów obsługiwanych przez agenta (określone przez określone ustawienia konwersacji). Zobacz Lokalizacja i rozpoczęcie rozmowy.

Wartością regionu jest dobrze sformatowany tag języka IETF BCP 47.

userInfo.displayName Nazwa użytkownika, który wysłał wiadomość. Jeśli użytkownik zrezygnuje z udostępniania tożsamości, to pole pozostanie puste.
userInfo.userDeviceLocale Lokalizacja regionalna użytkownika zgłoszona przez urządzenie jako prawidłowy tag języka IETF BCP 47.
widget.url Adres URL witryny, w której uruchomiono platformę konwersacyjną.
widget.widgetContext Wartość atrybutu data-bm-widget-context widżetu użytego do rozpoczęcia rozmowy.

Historia rozmowy

Google nie udostępnia historii rozmów. Prowadź własne rozmowy historyczne w sposób zgodny ze swoją polityką prywatności i sprawdzonymi metodami, aby móc wysyłać spersonalizowane odpowiedzi na przyszłe wiadomości użytkowników.