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.
Agent default locale
# 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__"
}
}'
For formatting and value options, see BusinessMessagesAgent.
Location default locale
# 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"
}'
For formatting and value options, see brands.locations.