Receive messages

After you register with Business Messages, you can receive messages on behalf of your test agent. You can receive messages for brands you manage after you create, verify, and launch agents for those brands.

When a customer sends a message to an agent that you manage, Business Messages sends a JSON payload to your webhook that contains various IDs, message content, and location information.

Use the Business Communications Developer Console logs page to debug message delivery issues.

Handle incoming messages

How your agent handles and responds to messages from users is highly dependent on your business logic. Generally, however, the steps to respond to a user message are consistent.

Note: In the event that a field is missing from a message payload, your agent should still process the message to the best of its ability.

Acknowledge the message

To acknowledge a message received by your webhook, return a valid HTTP response to messages sent to your webhook.

If a message fails to deliver because of delivery timeout, webhook reachability, redirection, or permission issues, Google stores and forwards the message, with multiple retries, for 7 days or until your webhook successfully receives the message.

Verify that the message is from Google

You should verify that Google sent the message before processing the message contents.

To verify that Google sent a message you received,

1. Parse the message's X-Goog-Signature header. This is a hashed, base64-encoded copy of the message body payload.

2. Using your client token (which was presented when you configured your webhook) as a key, create a SHA512 HMAC of the bytes of the message payload and base64-encode the result.

   Note: If you received a Partner key during registration with Business Messages, use that as the key for the SHA512 HMAC instead of the client token. If you update your webhook, use the client token for message validation with the new webhook configuration.

3. Compare the X-Goog-Signature hash with the hash you created.

   • If the hashes match, you've confirmed that Google sent the message.
   • If the hashes don't match, check your hashing process on a known-good message. If your hashing process is working correctly and you receive a message that you believe was fraudulently sent to you, contact us (you must sign in with a Business Messages Google account).

See the message verification example in the GitHub repositories for the Echo Bots in Java, Node.js, and Python.

Identify the locale

Users communicate from many locations and in many languages. Business Messages represents users' language preferences with the resolvedLocale and userDeviceLocale fields, which are based on their devices' locale settings. See Localization and locales.

Whenever possible, route messages and compose responses based on users' language preferences.

Route the message based on its context

Message context informs what sort of information the user might be looking for. For example, if a user sends a message with a placeId value, they messaged a specific location (identified by placeId) and are likely to ask location-specific questions. Similarly, if a message has a nearPlaceId value, which identifies a location near the user, the user likely wants to know location-specific information, but the agent should confirm the location that the user wants to chat with before beginning the conversation.

With the message's context information, route the message to the location best suited to respond:

• If the message is in a new conversation and is a common question, you might answer with automation.
• If automation can't handle the question, route it to a live agent.
• If the message's locale doesn't match your agent's default locale, route the message to a live agent who can support that locale.
• If the question is about a specific location, route it to someone with information about that location.
• If the message is in an ongoing conversation, route it to the live agent participating in the conversation.

Identify the type of message the user sent

Users can send three types of messages:

• Text messages are freeform responses.
• Image messages include a signed URL for an image the user uploaded.
• Suggestion messages include the postback data and text of the suggested action or suggested reply that the user tapped.

Process the message content

If your agent uses automation, the user message's content should guide your agent's logic and next response in the conversation.

The easiest way to identify user intent is with postback data from a suggested reply or suggested action. Regardless of the text associated with the suggestion, the postback data is machine-readable.

If a user sends a text message, your agent might parse the response for supported keywords or use natural language understanding (such as with the Dialogflow integration to process the user's message and identify a path forward.

If your agent doesn't know how to respond to the user's message, it should respond with an error state and try to continue the conversation by prompting the user for additional information, by asking for input in a different way, or by handing off the conversation to a live agent.

Respond to the user

After the agent identifies the correct response—either through automation or a live agent—it sends a message and continues the conversation with the user.

When composing a response, consider the user's locale. You can additionally customize responses by retrieving values from the userInfo object in each message you receive.

Note: If you enable automatic responses in the Dialogflow integration, Business Messages and Dialogflow reply to users on your behalf with the best matched response.

Message types

The following code shows how your agent receives messages.

For formatting and value information, see UserMessage.

Text

The most common way for users to respond is with plain text. Text messages have the following 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",
}

For formatting and value options, see Message.

Image

In addition to sending text, users can send images to your agent as messages. Business Messages stores shared images, for 7 days, at signed URLs and includes those URLs in the text field of the message payload.

If your agent includes automation, make sure the automation knows how to respond if a user shares an image. For live agents, make sure that images are passed through or that URLs in messages are clickable.

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

For formatting and value options, see Message.

Suggestion

Suggested replies and suggested actions allow users to respond or perform actions with a tap. When a user taps a suggestion, the agent receives a payload with the suggestion text and postback data.

Suggestion messages have the following 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",
}

For formatting and value options, see SuggestionResponse.

Authentication request

The Authentication request suggestion allows users to sign in with an OAuth provider to provide identity details with the agent or allow the agent to perform actions on the users' behalf. See Authenticate with OAuth.

If a user successfully signs in with the specified OAuth provider, the agent receives a payload with the authorization code. If a user is unsuccessful in signing in, the agent receives a payload with error details.

Authentication request messages have the following 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",
}

For formatting and value options, see AuthenticationResponse.

Message context

Each message contains context information about where the message originated.

...
  "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	Description
customContext	Context data specified by the partner.
entryPoint	The messaging surface the user began the conversation from, as defined by EntryPoint.
placeId	A unique identifier from the Google Places database for the location that the user messaged. It only appears in messages from location-specific entry points.
nearPlaceId	A unique identifier from the Google Places database for the first location in a Local Pack. Confirm the locations that users want to chat with when you receive nearPlaceId values.
deflectedPhoneNumber	The phone number that Business Messages deflected the user from calling when the conversation started.
resolvedLocale	The best computed match of the user's locale (reported in userDeviceLocale) and the agent's supported locales (determined by specified conversational settings). See Localization and Begin the conversation. The locale value is a well-formed IETF BCP 47 language tag.
userInfo.displayName	The name of the user who sent the message. If the user opts out of identity sharing, this field is empty.
userInfo.userDeviceLocale	The user's locale, reported by their device, as a well-formed IETF BCP 47 language tag.
widget.url	The URL of the website where the conversational surface launched.
widget.widgetContext	The data-bm-widget-context attribute value of the widget used to start the conversation.

Conversation history

Google doesn't provide conversation histories. Maintain your own historical conversations, in a way compliant with your privacy policy and best practices, so you can send informed responses to future messages from users.