メッセージを受信する

ビジネス メッセージに登録すると、テスト エージェントに代わってメッセージを受信できます。管理しているブランドの作成、確認、起動を行った後に、管理しているブランドのメッセージを受け取ることができます。

お客様が管理しているエージェントにユーザーがメッセージを送信すると、ビジネス メッセージは、さまざまな ID、メッセージの内容、位置情報を含む JSON ペイロードを Webhook に送信します。

メッセージ配信の問題をデバッグするには、Business Communications Developer Console のログページを使用します。

受信メールを処理する

エージェントがユーザーからのメッセージをどのように処理して応答するかは、ビジネス ロジックに大きく依存します。ただし、ユーザー メッセージに応答する手順は基本的に同じです。

メッセージの確認応答をする

Webhook が受信したメッセージを確認するには、Webhook に送信されたメッセージに対して有効な HTTP レスポンスを返します。

配信タイムアウト、Webhook のネットワーク到達性、リダイレクト、権限の問題が原因でメッセージが配信されなかった場合、Google はメッセージを 7 日間または Webhook が無事に受信するまで再試行し、格納して転送します。

メッセージが Google から送信されていることを確認する

メッセージの内容を処理する前に、Google がメッセージを送信したことを確認する必要があります。

Google が受信したメッセージを確認するには、次の操作を行います。

  1. メッセージの X-Goog-Signature ヘッダーを解析します。これは、メッセージ本文のペイロードの、ハッシュ化され、Base64 でエンコードされたコピーです。

  2. クライアント トークン（Webhook の構成時に表示）をキーとして使用して、メッセージ ペイロードのバイトの SHA512 HMAC を作成し、結果を base64 エンコードします。

  3. X-Goog-Signature ハッシュと作成したハッシュを比較します。

    • ハッシュが一致する場合、Google がメッセージを送信していることを確認しています。
    • ハッシュが一致しない場合は、既知の正常なメッセージでハッシュ化プロセスを確認してください。ハッシュ化プロセスが正しく機能していて、不正に送信されたと思われる場合は、 Google にお問い合わせください（ビジネス メッセージの Google アカウントでログインする必要があります）。

Java、Node.js、Python の Echo Bot については、GitHub リポジトリにあるメッセージ確認の例をご覧ください。

言語 / 地域を特定

ユーザーはさまざまな場所から、多くの言語でコミュニケーションをとっています。ビジネス メッセージは、デバイスの言語 / 地域設定に基づいて、resolvedLocale と userDeviceLocale のフィールドでユーザーの言語設定を表します。ローカライズとロケールをご覧ください。

可能な限り、ユーザーの言語設定に基づいてメッセージをルーティングし、レスポンスを作成します。

コンテキストに基づいてメールをルーティングする

メッセージ コンテキストは、ユーザーが求めている可能性のある情報を示します。 たとえば、ユーザーが placeId 値でメッセージを送信した場合、ユーザーは特定の場所（placeId で識別）にメッセージを送信します。これは、位置情報に固有の質問をする可能性が高くなります。同様に、メッセージに nearPlaceId 値があり、ユーザーの近くの場所を識別している場合、ユーザーは位置情報に固有の情報を知りたい可能性がありますが、エージェントは会話を開始する前に、チャットしたい場所を確認する必要があります。

メッセージのコンテキスト情報を使用して、応答に最適な場所にメッセージをルーティングします。

  • メッセージが新しい会話にあり、一般的な質問である場合は、自動化機能を使用します。
  • 自動化で質問に対応できない場合は、ライブ対応のエージェントにラウトします。
  • メッセージのロケールがエージェントのデフォルトのロケールと一致しない場合は、そのロケールをサポートできるライブ エージェントにメッセージをルーティングします。
  • 特定の場所に関する質問の場合は、その場所に関する情報を把握している者に案内してください。
  • 進行中の会話のメッセージの場合は、会話に参加しているライブ エージェントに転送します。

ユーザーが送信したメッセージの種類を特定する。

ユーザーは、次の 3 種類のメッセージを送信できます。

  • テキスト メッセージは、自由形式のレスポンスです。
  • Image メッセージには、ユーザーがアップロードした画像の署名付き URL が含まれています。
  • 返信文候補には、ポストバック データと、ユーザーがタップした提案されたアクションや返信の候補のテキストが含まれます。

メッセージ コンテンツを処理する

エージェントが自動化を使用する場合、ユーザー メッセージの内容によってエージェントのロジックと会話における次のレスポンスが指示されます。

ユーザーの意図を特定する最も簡単な方法は、返信の候補または操作の提案からポストバック データを使用することです。候補に関連付けられたテキストに関係なく、ポストバック データは機械で読み取り可能です。

ユーザーがテキスト メッセージを送信した場合、エージェントはレスポンスを解析してサポートされているキーワードを探したり、自然言語理解（Dialogflow 統合など）を使用してユーザーのメッセージを処理したり、今後のパスを特定したりすることができます。

エージェントがユーザーのメッセージへの応答方法を認識していない場合は、エラー状態を返して、ユーザーに追加情報を求めるか、別の方法で入力を求めるか、会話をライブ エージェントに引き継ぐことで会話を続行する必要があります。

ユーザーに返信する

エージェントは、自動化エージェントまたは人間のエージェントのいずれかによって正しいレスポンスを識別した後、メッセージを送信し、ユーザーとの会話を続行します。

レスポンスを作成するときは、ユーザーのロケールを考慮します。さらに、受信した各メッセージの userInfo オブジェクトから値を取得することで、レスポンスをカスタマイズできます。

メッセージのタイプ

次のコードは、エージェントがメッセージを受け取る方法を示しています。

フォーマットと値については、UserMessage をご覧ください。

Text

ユーザーが返信する最も一般的な方法は、書式なしテキストを使用することです。テキスト メッセージの形式は次のとおりです。

{
  "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 をご覧ください。

画像

ユーザーは、テキストを送信するだけでなく、画像をエージェントとしてエージェントに送信することもできます。ビジネス メッセージは、共有イメージを 署名付き URL に 7 日間保存し、それらの 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 プロバイダを使用してログインし、エージェントに ID の詳細を提供したり、エージェントがユーザーに代わってアクションを実行したりできるようになります。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",
    },
  },
...
Field 説明
customContext パートナーが指定したコンテキスト データ。
entryPoint EntryPoint の定義に従って、ユーザーが会話を開始したメッセージング サーフェス。
placeId ユーザーがメッセージを送信したビジネスの一意の識別子（Google プレイス データベースから取得したもの）。場所固有のエントリ ポイントからのメッセージにのみ表示されます。
nearPlaceId ローカルパック内の最初の場所の Google プレイス データベースから取得した一意の識別子です。nearPlaceId 値を受け取ったときに、ユーザーがチャットする場所を確認します。
deflectedPhoneNumber 会話の開始時にビジネス メッセージによってユーザーが通話できないようにした電話番号。
resolvedLocale

ユーザーの言語 / 地域（userDeviceLocale で報告）と、エージェントがサポートする言語 / 地域（指定された会話設定で指定）の、最適な計算方法。ローカライズと会話を始めるをご覧ください。

ロケール値は、正しい形式の IETF BCP 47 言語タグです。
userInfo.displayName メッセージを送信したユーザーの名前。ユーザーが ID の共有をオプトアウトした場合、このフィールドは空白になります。
userInfo.userDeviceLocale ユーザーのロケール。デバイスから報告されます。正しい形式の IETF BCP 47 言語タグでもあります。
widget.url 会話サーフェスが起動されたウェブサイトの URL。
widget.widgetContext 会話の開始に使用されたウィジェットの data-bm-widget-context 属性値。

会話の履歴

Google は会話の履歴を提供していません。プライバシーに関するベスト プラクティスやベスト プラクティスに準拠した方法で、独自の過去の会話を維持し、ユーザーから今後受け取るメッセージに対して十分な情報に基づいて返信できるようにします。