After you receive a message from a user, you can send a response to continue the conversation.
Agents communicate with users by sending and receiving messages. To send messages to users, your agent sends message requests to Business Messages.
To send a message, you send an HTTP POST request to the Business Messages API that includes
- a unique message ID
- the conversation ID
- the message content
When the Business Messages API sends your message to the user, it returns a
200 OK. If there are required values missing from your message, the API
400 error. If the message uses invalid credentials, the API returns
If a user's device doesn't support a message you attempt to send, such as if a
user doesn't support suggested replies, the API returns a
PRECONDITION) error. However, you can work around unsupported message types by
fallback text for each message you send. If you specify
text, the API returns a
200 OK response, even if the user's device doesn't
support the message type.
If a user receives a message that their device doesn't support but includes
fallback text, their device displays the
fallback text instead. This
behavior allows you to continue the conversation in a proactive way without
interrupting the conversation's flow or taking extra time to process a
(FAILED PRECONDITION) error and identifying an alternate message.
fallback text for any given message should mirror the function of the message.
- For messages with suggested replies or actions, include the message text in
fallbacktext, and include guidance on what options users have to continue the conversation.
- For rich cards or carousels, include the title and description in the
fallbacktext, and include links to images or websites.
To insert line breaks in
fallback text, use
Test fallback text
Before you launch an agent, you can test how fallback text appears in a
conversation by sending a message with the URL parameter
forceFallback set to
true. When you force fallback text, the conversation disregards the main
message content, text and an Open URL suggestion in the following example, and
displays the fallback text instead.
For details, see
When your agent sends a message, you specify a representative: the individual or
automation that composed the message. Business Messages supports
BOT representative when any sort of automation composes a message,
whether the automation is an auto-responder telling users their place in a
queue, a complex natural language understanding agent that has dynamic access to
user details, or anything in between. Messages with
BOT representatives appear
with a small icon
that helps set users' expectations for the types of interactions they might
HUMAN representative only when a live agent composes a message.
Before you send any messages from a
HUMAN representative, you send a
event to let
users know they can send more freeform or complex messages. After you send your
last message from a
HUMAN representative, send a
to once again set user expectations.
For example, if a user starts a conversation with your agent and you
send an automated message that they should expect a live agent within two
minutes, that message should be sent with a
BOT representative. Before the
live agent joins, send a
REPRESENTATIVE_JOINED event. All messages from the
live agent should be labeled as from a
HUMAN representative. When the live
agent exits the conversation, send a
REPRESENTATIVE_LEFT event. All subsequent
messages should have from a
BOT representative unless another live agent joins
See Handoff from bot to live
for sample conversation and code involved in transitioning between
Whether a representative is
HUMAN, you can specify a representative
display name and avatar. Both display names and avatars are visible to users.
Avatar images must be 1024x1024 px and a maximum of 50 KB and must be specified
as publicly available URLs. If you do not supply an avatar image, the agent's
logo is displayed as the representative's avatar.
The simplest messages are made of text. Text messages are best suited to communicate information without the need for visuals, complex interaction, or response.
The following code sends a simple text message. For reference information, see
Text messages with
containsRichText set to
true may include
basic Markdown formatting. You can include hyperlinks or make text bold or
italics. The table shows some valid examples:
|Formatting||Characters||Plain text||Rendered text|
The formatting must follow some additional rules:
- All links must begin with
- Different types of formatting may be nested but may not otherwise overlap.
- Line breaks with
\nare allowed anywhere in your message, but line breaks at the end of your message don't display.
- To normally display any of the reserved characters (
]), you must prefix them with a backslash character (
Messages with invalid formatting fail to send with an error message about invalid Markdown. The table shows some more valid and invalid examples based on the above rules:
|Plain text||Validity||Rendered text|
||Invalid. The link doesn't begin with
||Does not render.|
||Valid. Nesting is allowed.||Click here|
||Invalid. Overlapping formatting is not allowed.||Does not render.|
||Invalid. No trailing whitespace allowed inside the
||Does not render.|
The following code sends a rich text message. For reference information, see
Send an image to a user in a message.
You can send an image message with URLs to the image and the image thumbnail.
Suggested replies guide users through conversations by providing responses that your agent knows how to react to.
When a user taps a suggested reply, your agent receives a message that contains the reply's text and postback data.
Suggested replies have a maximum of 25 characters.
Suggested actions guide users through conversations by leveraging the native functionality of the their devices. When a user taps a suggested reply, your agent receives a message that contains the actions's text and postback data.
Suggested replies have a maximum of 25 characters.
Open URL action
With the Open URL action, your agent suggests a URL for a user to open. If an app is registered as a default handler for the URL, the app opens instead, and the icon for the action is the app's icon.
The following code sends text with an Open URL action. For formatting and value
The Dial action suggests a phone number for the user to dial. When a user taps a Dial action suggestion chip, the user's default dialer app opens with the specified phone number pre-populated.
The following code sends text with a Dial action. For formatting and value
Authentication request suggestion
The Authentication request suggestion prompts users to sign in to an OAuth 2.0-compliant application, passing authentication codes to confirm account data and enabling customized user experiences and detailed conversation flows. See Authenticate with OAuth.
Live agent request suggestion
The Live agent request suggestion allows you to guide users to interact with human representatives during complex interactions or when your automation can't handle a user request.
Users can request a live agent at any point in a conversation from the overflow menu. This suggestion gives agents a way to programmatically suggest interactions with human representatives based on the context of the conversation. Your agent should always be ready to respond to a Live agent requested event, even if it didn't send a Live agent request suggestion.
When users tap a Live agent request suggestion, it triggers a Live agent requested event.
When you need to send a chunk of related information, media, or suggestions, you should send a rich card. Rich cards allow your agent to send multiple units of information in a single message.
Rich cards can contain the following items:
- Media (JPG, JPEG, or PNG, maximum 5 MB)
- Media thumbnail (JPG, JPEG or PNG, maximum 25 KB)
- Title (maximum 200 characters)
- Description (maximum 2000 characters)
- A list of suggested replies and suggested actions (maximum 4)
A rich card can contain any or all of the listed items, but a card must contain at least media or a title to be valid. A rich card can contain a maximum of four suggested actions and suggested replies.
Your agent can send multiple rich cards together in a rich card carousel.
Cards expand vertically to fit their contents. Rich cards have a minimum height of 112 DP and a maximum height of 344 DP. If the contents of a card are not large enough to fill the minimum card height, the card expands and fills the extra height with white space.
Media in rich cards must fit one of three heights:
- Short: 112 DP
- Medium: 168 DP
- Tall: 264 DP
If the media doesn't fit the dimensions within the card given the selected height, the media preview is chosen by zooming and cropping the media.
Rich card carousels
When you need to present a user with multiple options to choose between, use a rich card carousel. Carousels string together multiple rich cards, allowing users to compare items and react to each individually.
Carousels may contain a minimum of two and a maximum of ten rich cards. Rich cards within carousels must conform to general rich card requirements for content and height.