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

FeatureSupportRemarks
delivery notificationyesOccurs when your message is delivered to the Google Business Messages platform. Delivery notifications are sent to the status report webhooks.
text messagesyesThe maximum length of a Google Business Messages message is 1.500 characters. Rich text is for messages only, it isn't supported in welcome messages, suggested replies, suggested actions, or rich cards.
mediayesMedia 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: imagesyesMaximum file size for an uploaded image is 5 MB. Supported MIME types are image/jpeg, image/png.
media: gifsno
media: videono
media: audiono
media: documentno
reply suggestionsyesMaximum label length: 25 characters.
rich cardyesSupport for text, media or suggestions.
rich card carouselyesMinimum of 2 and maximum of 10 rich cards.
message tagsyesAllows messaging from a specific source
live agent requestyesAllows a BOT to send a Live Agent Request suggestion to the end-user.

Onboarding

Onboarding is done via our Channels portal. On our portal, you will be presented with an onboarding page in which you have to provide CM.com information about your agent. With this information CM.com will create, verify, and launch the agent itself and the agent’s locations for you.

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.

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.

See the Google Business Messages message with text and image example.

Quick reply suggestions

Quick Replies allows you to suggest quick answers for the recipient beneath your message.

The following restrictions apply for a quick reply:

FieldRequiredRemarks
labelYesMaximum length is 25 characters.
postbackdataYes
mediaNo

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.

Message Tags

By default, all messages send towards an enduser 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:

TagDescription
HUMAN_AGENTMessage will be considered to be send by a human agent

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:

FeatureRemarks
MediaJpg, jpeg or png, maximum 5 MB
Media thumbnailMaximum 25 KB
TitleMaximum 200 characters
DescriptionMaximum 2000 characters
A list of suggested replies and suggested actionsMaximum 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.

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.

Examples

Direct message with plain text contents

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."
                }
            }
        ]
    }
}

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-tablet.jpg",
                                "mediaUri": "https://www.cm.com/cdn/web/blog/featured/cm-tablet.jpg",
                                "mimeType": "image/jpeg"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

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"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

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 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"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

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": "cm-tablet.jpg",
                                "mediaUri": "https://www.cm.com/cdn/web/blog/featured/cm-tablet.jpg",
                                "mimeType": "image/jpeg"
                            },
                            "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-tablet.jpg",
                                            "mediaUri": "https://www.cm.com/cdn/web/blog/featured/cm-tablet.jpg",
                                            "mimeType": "image/jpeg"
                                        },
                                        "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"
                                            }
                                        ]
                                    }
                                ]
                            }
                            
                        }
                    ]
                }
            }
        ]
    }
}

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"
                        }
                    ]
                }
            }
        ]
    }
}

Did this page help you?