Google's Business Messages
Our business messaging API supports sending and receiving Google Business Messages.
Being able to send Google Business Messages requires requesting access via the Channels portal. Without onboarding with Google Business Messages via the portal, you can not make use of this part of the API.
Fact sheet
| Feature | Support | Remarks |
|---|---|---|
| delivery notification | yes | Occurs when your message is delivered to the Google Business Messages platform. Delivery notifications are sent to the status report webhooks. |
| text messages | yes | The maximum length of a Google's Business Messages message is 3.072 characters |
| media | yes | Media name attribute should end in the proper file extension. Only one media file is allowed per message; when sending multiple files, each file will be sent in its own Google Business Messages message. When the linked media doesn't exist/can't be found, the message will not be sent at all. The provided text message is sent in a separate Google Business Messages message. |
| media: images | yes | Maximum file size for an uploaded image is 5 MB. Supported MIME types are image/jpeg, image/png. |
| media: GIFs | no | |
| media: video | no | |
| media: audio | no | |
| media: document | no | |
| reply suggestions | yes | Maximum label length: 25 characters. Maximum of 13 suggestions. |
| rich card | yes | Support for text, media, or suggestions. |
| rich card carousel | yes | Minimum of 2 and maximum of 10 rich cards. |
| message tags | yes | Allows messaging from a specific source |
| live agent request | yes | Allows a BOT to send a Live Agent Request suggestion to the end-user. |
Prerequisites
Your business needs to be registered at Google Business Profile.
Your business is verified in Google's business locations.
*The name of your agent should match the business profile name. (So you cannot have the Building Blocks agent set up for the CM.com HQ business profile in Google)
Onboarding
Onboarding is done via our Channels portal. On our portal, you can onboard your brand and agent yourself by following the steps:
Step 1. Onboarding on CM.com platform - Request channel, and sign order after validation by CM.com.
Step 2. Create brand
Step 3. Create agent
Step 4. Onboarding agent in Google Search (manual process)
Step 5. Onboarding agent in Google Maps
Step 6. Launching agent
Please note
To assess agent performance, Google Business Messages tracks multiple metrics to ensure that agents provide a good user experience. If an agent falls below a metrics threshold, CM.com will be notified about this by Google Business Messages. If an agent remains below a threshold for 28 days, Google Business Messages may suspend the agent. See the following link for more information: Performance thresholds
Business rules
Sending Google Business Messages using the CM Business Messaging API also requires you to adhere to the Google Business Messages Terms of Service, Acceptable Use Policy and Guidelines for sending messages.
To be able to send Google Business Messages, the creation of an agent is required. An agent is a conversational entity that users interact with. You create one agent for each brand you manage.
An agent encompasses a brand's business functions, such as online support, and physical locations (if any). Each message contains the context from which the user initiated the conversation.
It is allowed to have multiple agent accounts under one CM.com account.
Considerations
The only way to have a Google Business Messages conversation with end-users is when the end-user starts the conversation by sending you an initial message.
Sending messages
Unlike other channels, Google Business Messages does not use telephone numbers as identifiers for sender (from) and recipient (to.number), instead it uses a so-called "Conversation ID" for the recipient and an "Agent ID" for the sender. A person is assigned a unique Conversation ID for each agent they start a conversation with.
These IDs are visible in the CM.com platform as the userid under channels...Google Business Messages.
Text
Direct message with plain text content
The example below will send a simple text-only Google Business Messages message.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Agent ID",
"to": [
{
"number": "Conversation ID"
}
],
"allowedChannels": ["Google Business Messages"],
"body": {
"type": "auto",
"content": "CM.com - Be part of it."
}
}
]
}
}
Media
Display order
If you send a message including both an image and some text, Google Business Messages will display these as separate messages; typically the text will be the first message.
Direct message with text and image
In the example below, we send a simple rich content message that contains both text and an image that Google Business Messages will display as two separate messages. An explanation on how to send rich content messages in general can be found in the rich content description.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Agent ID",
"to": [
{
"number": "Conversation ID"
}
],
"body": {
"type": "auto",
"content": "Fallback Text"
},
"allowedChannels": ["Google Business Messages"],
"richContent": {
"conversation": [
{
"text": "CM.com - Be part of it.",
"media": {
"mediaName": "cm.png",
"mediaUri": "https://www.cm.com/cdn/cm/cm.png",
"mimeType": "image/png"
}
}
]
}
}
]
}
}
Quick reply suggestions
Quick Replies allows you to suggest quick answers for the recipient beneath your message. A message has a maximum of 13 suggestions.
The following restrictions apply for a quick reply:
| Field | Required | Remarks |
|---|---|---|
| label | Yes | Maximum length is 25 characters. |
| postbackdata | Yes | |
| media | No |
The following actions are supported by Google Business Messages as rich card buttons.
| Action | Remarks |
|---|---|
| Reply | Maximum length of label is 25 characters. |
| OpenURL | Maximum length of label is 25 characters, url required. |
| Dial action | Maximum length of label is 25 characters, phone number required. |
| Live agent request | Reply action without label, which must have postbackdata HUMAN_AGENTThis must/can only be send as BOT to the user (without HUMAN_AGENTtag) |
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.
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.
Live agent request
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.
When users tap a Live agent request suggestion, it triggers a Live agent requested event.
When a BOT is unable to process a user message correctly it can also suggest a Live Agent Request to the user as an option.
More info can be found under Suggestions/Features.
Direct message with reply suggestion
In the example below, we send a rich content message that contains a text and some reply suggestions. An explanation on reply suggestions can be found under Suggestions/Features under Rich Content
NOTE: Google Business Messages only supports suggestions with
"action": "Reply"
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Agent ID",
"to": [
{
"number": "Conversation ID"
}
],
"body": {
"content": ""
},
"allowedChannels": ["Google Business Messages"],
"richContent": {
"conversation": [
{
"text": "Hi, what can I do for you?",
"suggestions": [
{
"action": "Reply",
"label": "Call me",
"postbackdata": "call-me"
},
{
"action": "Reply",
"label": "Email me",
"postbackdata": "email-me"
},
{
"action": "Reply",
"label": "Send me an sms",
"postbackdata": "send-me-sms"
}
]
}
]
}
}
]
}
}
Send a Live Agent Request suggestion to the user
Note
In the example below we send a Live Agent Request suggestion to the user. This must/can only be send as BOT to the user.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Agent ID",
"to": [
{
"number": "Conversation ID"
}
],
"body": {
"type": "auto",
"content": "Fallback text"
},
"allowedChannels": ["Google Business Messages"],
"richContent": {
"conversation": [
{
"text": "Do you want to speak with a live agent?",
"suggestions": [
{
"action": "Reply",
"postbackdata": "HUMAN_AGENT"
}
]
}
]
}
}
]
}
}
Direct message with open url action
In the example below, we send a simple rich content message that contains elements that Google Business Messages will display as an open URL action. An explanation on how to send rich content messages in general can be found in the rich content description.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Agent ID",
"to": [
{
"number": "Conversation ID"
}
],
"body": {
"type": "auto",
"content": "Fallback Text"
},
"allowedChannels": ["Google Business Messages"],
"richContent": {
"conversation": [
{
"text": "CM.com - Be part of it.",
"suggestions": [
{
"action": "OPENURL",
"label": "Visit CM.com",
"url": "https://www.cm.com/",
"postbackdata": "visit-cm"
}
]
}
]
}
}
]
}
}
Rich card
Rich cards offer a way for you to offer a richer in-conversation experience than standard text messages by integrating buttons, images and more alongside text in a single message. Rich cards can be used for many purposes, such as displaying product information or asking the message recipient to choose from a pre-determined set of options.
Rich cards can contain the following items:
| Feature | Remarks |
|---|---|
| Media | JPG, JPEG or PNG, maximum 5 MB |
| Media thumbnail | 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.
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.
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.
Direct message rich card content with reply suggestion
In the example below, we send a rich content message that contains elements that Google Business Messages will display as a rich card.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Agent ID",
"to": [
{
"number": "Conversation ID"
}
],
"body": {
"content": ""
},
"allowedChannels": ["Google Business Messages"],
"richContent": {
"conversation": [
{
"header": "Contact options",
"text": "Hi, what can I do for you?",
"media": {
"mediaName": "connect.png",
"mediaUri": "https://www.cm.com/cdn/web/en/small/connect-test.png",
"mimeType": "image/png"
},
"suggestions": [
{
"action": "Reply",
"label": "Call me",
"postbackdata": "call-me"
},
{
"action": "Reply",
"label": "Email me",
"postbackdata": "email-me"
},
{
"action": "Reply",
"label": "Send me an sms",
"postbackdata": "send-me-sms"
}
]
}
]
}
}
]
}
}
Direct message with rich card carousel content with button suggestions
In the example below, we send a rich content message that contains elements that Google Business Messages will display as a rich card carousel.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Agent ID",
"to": [
{
"number": "Conversation ID"
}
],
"body": {
"type": "auto",
"content": "Fallback Text"
},
"allowedChannels": ["Google Business Messages"],
"richContent": {
"conversation": [
{
"carousel": {
"cards": [
{
"header": "CM.com - Be part of it.",
"text": "Want to know more about CM.com?",
"media": {
"mediaName": "cm.png",
"mediaUri": "https://www.cm.com/cdn/cm/cm.png",
"mimeType": "image/png"
},
"suggestions": [
{
"action": "REPLY",
"label": "Give me more info",
"postbackdata": "INFO"
},
{
"action": "OPENURL",
"label": "Visit CM.com",
"url": "https://www.cm.com/",
"postbackdata": "visit-cm"
}
]
},
{
"header": "CM.com - Customer Satisfaction",
"text": "17 Ways To Enhance Your Customer Satisfaction",
"media": {
"mediaName": "customer-contact-channels.png",
"mediaUri": "https://www.cm.com/cdn/web/blog/content/customer-contact-channels.png",
"mimeType": "image/png"
},
"suggestions": [
{
"action": "REPLY",
"label": "Give me more info",
"postbackdata": "INFO CCC"
},
{
"action": "OPENURL",
"label": "Visit CM.com - CCC",
"url": "https://www.cm.com/blog/17-ways-business-messaging-enhances-your-customer-satisfaction/",
"postbackdata": "visit-cm"
}
]
}
]
}
}
]
}
}
]
}
}
Message Tags
By default, all messages send towards an end user are considered to be coming from a bot.
By including a tag, you can specify the message comes from a different source, like a human agent.
The end user will receive a notification when a human agent joins the conversation.
The following message tags are supported:
| Tag | Description |
|---|---|
| HUMAN_AGENT | Message will be considered to be sent by a human agent |
Direct message with message tag
In the example below, we send a simple text message with a message tag "HUMAN_AGENT" applied. This tag is used to indicate this messages comes from a human agent.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Agent ID",
"to": [
{
"number": "Conversation ID"
}
],
"body": {
"type": "auto",
"content": "Fallback Text"
},
"allowedChannels": ["Google Business Messages"],
"richContent": {
"conversation": [
{
"text": "Hi, how can I help you?",
"tag": "HUMAN_AGENT"
}
]
}
}
]
}
}
Receiving messages / Inbound flow
Since Google Business Messages is used for 2-way communication (chat) it is important to also implement an Inbound flow. You can find more information about how to do this using our API documentation of the Inbound webhook. Note that for Google Business Messages, you need to set up your webhook API in the Channels app, not in the Gateway app.
Updated 10 days ago