Updates: Check the release notes for new features and product updates.

Send messages

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 returns a 400 error. If the message uses invalid credentials, the API returns a 401 error.

Fallback strategy

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 400 (FAILED PRECONDITION) error. However, you can work around unsupported message types by specifying fallback text for each message you send. If you specify fallback 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 400 (FAILED PRECONDITION) error and identifying an alternate message.

fallback text for any given message should mirror the function of the message. For example,

  • For messages with suggested replies or actions, include the message text in the fallback text, and include guidance on what options users have to continue the conversation.
  • For rich cards or carousels, include the title and description in the fallback text, and include links to images or websites.

To insert line breaks in fallback text, use \n or \r\n.

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.

cURL

Node.js

Java

Python

For details, see Message.

Representatives

When your agent sends a message, you specify a representative: the individual or automation that composed the message. Business Messages supports BOT and HUMAN representatives.

Specify a 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 engage in.

Specify a HUMAN representative only when a live agent composes a message. Before you send any messages from a HUMAN representative, you send a REPRESENTATIVE_JOINED 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 REPRESENTATIVE_LEFT event 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 the conversation.

See Handoff from bot to live agent for sample conversation and code involved in transitioning between BOT and HUMAN representatives.

Whether a representative is BOT or 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.

Text

The simplest messages are made of text. Text messages are best suited to communicate information without the need for visuals, complex interaction, or response.

Example

The following code sends a simple text message. For reference information, see conversations.messages.create.

cURL

Node.js

Java

Python

Rich text

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
Bold ** **Some text** Some text
Italics * *Some text* Some text
Hyperlink []() [Click here](https://www.example.com) Click here
Line break \n Line one\nLine two Line one
Line two

The formatting must follow some additional rules:

  • All links must begin with https:// or http://
  • Different types of formatting may be nested but may not otherwise overlap.
  • Line breaks with \n are 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 (*, \, [, or ]), 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
[Click here](www.example.com) Invalid. The link doesn't begin with http:// or https:// Does not render.
[**Click here**](https://www.example.com) Valid. Nesting is allowed. Click here
**This is [not** valid](https://www.example.com) Invalid. Overlapping formatting is not allowed. Does not render.
** Some bold text ** Invalid. No trailing whitespace allowed inside the **. Does not render.
Citation below\* Valid. The * character is escaped. Citation below*

Example

The following code sends a rich text message. For reference information, see conversations.messages.create.

cURL

Node.js

Java

Python

Images

Send an image to a user in a message.

You can send an image message with URLs to the image and the image thumbnail.

Example

The following code sends an image. For formatting and value options, see conversations.messages.create and Image.

cURL

Node.js

Java

Python

Suggested replies

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.

Example

The following code sends text with two suggested replies. For formatting and value options, see conversations.messages.create and SuggestedReply.

cURL

Node.js

Java

Python

Suggested actions

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.

For formatting and value options, see conversations.messages.create and SuggestedAction.

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 options, see OpenUrlAction.

cURL

Node.js

Java

Python

Dial action

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 options, see DialAction.

cURL

Node.js

Java

Python

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.

Example

The following code sends text with an Authentication request suggestion. For formatting and value options, see conversations.messages.create and Suggestion.

cURL

Node.js

Java

Python

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.

Example

The following code sends text with a Live agent request suggestion. For formatting and value options, see conversations.messages.create and Suggestion.

cURL

Node.js

Java

Python

Rich cards

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.

Card height

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.

Example

The following code sends a rich card with an image and suggested replies. For formatting and value options, see conversations.messages.create and RichCard.

cURL

Node.js

Java

Python

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.

Example

The following code sends a rich card carousel. For formatting and value options, see conversations.messages.create and RichCard.

cURL

Node.js

Java

Python