Localization and locales

Users communicate from many locations and in many languages. Agents that are responsive to users' communication preferences and localize their experiences reach more users, create more fulfilling user experiences, and drive more repeat interactions than agents that aren't responsive. Business Messages enables agents and locations to be responsive to users' preferences by passing user locale settings to agents, enabling agents to specify a default locale and unique conversational settings per locale, and resolving matches between users' locales and an agent or location's supported locales.

By detecting locale, Business Messages agents can localize their experiences by making automated and live agent interactions aware of users' region and language preferences.

User locale

When a user begins a conversation with an agent, and each time a user sends a message, Business Messages detects the user device's locale settings. Each message agents receive includes the user's locale in the context.userInfo.userDeviceLocale field.

Business Messages uses the user device's locale to change the language in the user interface and change the language of strings generated by the platform.

userDeviceLocale can change within a conversation if the user changes the device's language or switches between devices that have different locale settings. If agents read userDeviceLocale, they should check if the value has changed with each new message and adapt accordingly if it has. For example, an agent might detect a locale change and ask the user if they would prefer to continue communicating in the current language or switch to one that matches the new locale.

userDeviceLocale is specified by the user's device and can be any IETF BCP 47 language tag.

Agent and location locale

Agents and locations can specify conversational settings for whichever locales they support. For example, an agent might specify a welcome message in English for the "en" locale and have the same message in Spanish for the "es" locale, or one location may specify settings for the "fr" locale while another location doesn't.

If an agent or location has any conversational settings set for a locale, Business Messages assumes that the agent or location supports that locale. Agents and locations can set a default locale (defaultLocale) that they usually communicate in.

To update an agent or location's default locale, see Update the default locale. To set conversational settings for a locale, see Begin the conversation.

Resolved locale

By identifying the user device's locale and comparing that locale to the locales specified for the agent or the location that the user messages, Business Messages can resolve a match between the user and agent locales. An agent or location's defaultLocale takes precedence over other supported locales when Business Messages resolves a match. Each message agents receive includes this match in the context.resolvedLocale field.

Business Messages uses the resolved locale to select which conversational settings (such as welcome messages and offline messages) and strings (such as the Live agent request suggestion string) to display. It's best practice for agents to communicate in the resolved locale to maintain a consistent user experience.

The resolved locale can change within a conversation if the user changes the device's language or switches between devices that have different locale settings. Agents should check if the value has changed with each new message and adapt accordingly if it has. For example, an agent might detect a locale change and ask the user if they would prefer to continue communicating in the current language or switch to one that matches the new locale.

Update the default locale

To specify a default locale, you make a PATCH request with the Business Communications API to update an agent or location's defaultLocale field.

To update an agent or location's conversation settings for a locale—such as welcome message and conversation starters—see Begin the conversation.

Prerequisites

Before you update the default locale, you need the following items:

• Path to your GCP project's service account key on your development machine

• For agent's default locale, agent name (for example, "brands/12345/agents/67890")

  If you don't know the agent's name, see List all agents for a brand.

• For location's default locale, location name (for example, "brands/12345/locations/67890")

  If you don't know the location's name, see List all locations for a brand.

• The locale to set as default, as a two-character ISO 639-1 language code

• Locale-specific conversational settings set for the agent or location. See Begin the conversation

Send the update request

To update the agent or location, run the following command. Replace variables with values you identified in Prerequisites.

# This code sets the default locale of a Business Messages agent.
# Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.agents/patch

# Replace the __BRAND_ID__, __AGENT_ID__ and __DEFAULT_LOCALE__
# Make sure a service account key file exists at ./service_account_key.json

curl -X PATCH \
"https://businesscommunications.googleapis.com/v1/brands/__BRAND_ID__/agents/__AGENT_ID__?updateMask=businessMessagesAgent.defaultLocale" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json ./service_account_key.json businesscommunications)" \
-d '{
  "businessMessagesAgent": {
    "defaultLocale": "__DEFAULT_LOCALE__"
  }
}'
update-agent-bm-defaultLocale.sh

# This code updates the default locale of an agent.
# Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.locations/patch

# Replace the __BRAND_ID__ and __LOCATION_ID__
# Make sure a service account key file exists at ./service_account_key.json

curl -X PATCH \
"https://businesscommunications.googleapis.com/v1/brands/__BRAND_ID__/locations/__LOCATION_ID__?updateMask=defaultLocale" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json ./service_account_key.json businesscommunications)" \
-d '{
  "defaultLocale": "en"
}'
update-location-bm-defaultLocale.sh