Google Business Messages API

🚧

API Endpoint and Authentication

  • Your API endpoint varies based on where your Webex Connect account is hosted. Visit Know Your API Endpoint section to know more.

  • You can use either Service Key or JSON Web Tokens (JWT) for authentication. If you use both JWT authentication and Service Key in an API request, JWT authentication takes priority, and the Service Key is ignored.

Google Business Messages - Samples

{
    "callbackUrl": "https://requestinspector.com/inspect/01gp31z8derrbjs22qxby9kxzr",
    "callbackData": "customerID123|1234|new_sale",
    "correlationId": "de36bb32-3f5d-46c9-b132-15e010a80ccc",
    "from": "a_167344112755437860",
    "to": "66d8a4d2-8fc7-4447-8bd1-b1874d0db18b",
    "representative": {
        "avatarImage": "https://developers.google.com/identity/images/g-logo.png",
        "displayName": "Chatbot",
        "representativeType": "BOT"
    },
    "suggestions": [
        {
            "reply": {
                "text": "Flowtrigger",
                "postbackData": "Flow GBM executed"
            }
        },
        {
            "action": {
                "text": "Open URL",
                "postbackData": "Url Opened",
                "openUrlAction": {
                    "url": "https://www.google.com"
                }
            }
        },
        {
            "action": {
                "text": "Call support",
                "postbackData": "call-support",
                "dialAction": {
                    "phoneNumber": "+919876543210"
                }
            }
        },
        {
            "liveAgentRequest": {}
        }
    ],
    "fallback": "fallback text",
    "containsRichText": true,
    "text": "Text with BOT as representative"
}
{
    "callbackUrl": "https://requestinspector.com/inspect/01gp31z8derrbjs22qxby9kxzr",
    "callbackData": "customerID123|1234|new_sale",
    "correlationId": "de36bb32-3f5d-46c9-b132-15e010a80ccc",
    "from": "a_167344112755437860",
    "to": "66d8a4d2-8fc7-4447-8bd1-b1874d0db18b",
    "representative": {
        "avatarImage": "https://developers.google.com/identity/images/g-logo.png",
        "displayName": "Chat Bot",
        "representativeType": "BOT"
            
        },
         "suggestions": [
             {
                 "reply": {
                     "text": "Flowtrigger",
                     "postbackData": "Flow GBM executed"
                    
                }
                
            },
             {
                 "action": {
                     "text": "Open URL",
                     "postbackData": "Url Opened",
                     "openUrlAction": {
                         "url": "https://www.google.com"
                        
                    }
                    
                }
                
            },
             {
                 "action": {
                     "text": "Call support",
                     "postbackData": "call-support",
                     "dialAction": {
                         "phoneNumber": "+919876543210"
                        
                    }
                    
                }
                
            },
             {
                 "liveAgentRequest": {}
                
            }
            
        ],
         "fallback": "Image sending",
         "containsRichText": true,
         "image": {
             "contentInfo": {
                 "fileUrl": "https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg",
                 "thumbnailUrl": "https://developers.google.com/identity/images/g-logo.png",
                 "forceRefresh": true,
                 "altText": "Sending Images with suggesstion"
                
            }
            
        }
    
}
{
     "callbackUrl": "https://requestinspector.com/inspect/01gp31z8derrbjs22qxby9kxzr",
     "callbackData": "customerID123|1234|new_sale",
     "correlationId": "de36bb32-3f5d-46c9-b132-15e010a80ccc",
     "from": "a_167344112755437860",
     "to": "66d8a4d2-8fc7-4447-8bd1-b1874d0db18b",
     "representative": {
             "avatarImage": "https://developers.google.com/identity/images/g-logo.png",
             "displayName": "Chatbot",
             "representativeType": "BOT"
            
        },
         "suggestions": [
             {
                 "action": {
                     "text": "Call support",
                     "postbackData": "call-support",
                     "dialAction": {
                         "phoneNumber": "+919876543210"
                        
                    }
                    
                }
                
            },
             {
                 "liveAgentRequest": {}
                
            }
            
        ],
         "fallback": "string",
         "containsRichText": true,
         "richCard": {
             "standaloneCard": {
                 "cardContent": {
                     "title": "GBM",
                     "description": "desc",
                     "media": {
                         "height": "SHORT",
                         "contentInfo": {
                             "fileUrl": "https://developers.google.com/identity/images/g-logo.png",
                             "thumbnailUrl": "https://developers.google.com/identity/images/g-logo.png",
                             "forceRefresh": true,
                             "altText": "string"
                            
                        }
                        
                    },
                     "suggestions": [
                         {
                             "reply": {
                                 "text": "reply",
                                 "postbackData": "Replied"
                                
                            }
                            
                        },
                         {
                             "action": {
                                 "text": "Open URL FB",
                                 "postbackData": "Url Opened",
                                 "openUrlAction": {
                                     "url": "https://www.facebook.com"
                                    
                                }
                                
                            }
                            
                        }
                        
                    ]
                    
                }
                
            }
            
        }
    
}
{
    "callbackUrl": "https://requestinspector.com/inspect/01gp31z8derrbjs22qxby9kxzr",
    "callbackData": "customerID123|1234|new_sale",
    "correlationId": "de36bb32-3f5d-46c9-b132-15e010a80ccc",
    "from": "a_167344112755437860",
    "to": "66d8a4d2-8fc7-4447-8bd1-b1874d0db18b",
    "representative": {
        "avatarImage": "https://developers.google.com/identity/images/g-logo.png",
        "displayName": "Human",
        "representativeType": "HUMAN"
    },
    "fallback": "string",
    "containsRichText": true,
    "richCard": {
        "carouselCard": {
            "cardWidth": "MEDIUM",
            "cardContents": [
                {
                    "title": "Carousel 1",
                    "description": "This carousel 1 description",
                    "media": {
                        "height": "MEDIUM",
                        "contentInfo": {
                            "fileUrl": "https://developers.google.com/identity/images/g-logo.png",
                            "thumbnailUrl": "https://developers.google.com/identity/images/g-logo.png",
                            "forceRefresh": true,
                            "altText": "string"
                        }
                    },
                    "suggestions": [
                        {
                            "reply": {
                                "text": "Need help reply",
                                "postbackData": "Welcome, to connect QA, How may help you?"
                            }
                        },
                        {
                            "action": {
                                "text": "Open FB Url",
                                "postbackData": "Successfully, Opened URL",
                                "openUrlAction": {
                                    "url": "http://www.facebook.com"
                                }
                            }
                        }
                    ]
                },
                {
                    "title": "Carousel 2",
                    "description": "This is carousel 2 description",
                    "media": {
                        "height": "MEDIUM",
                        "contentInfo": {
                            "fileUrl": "https://developers.google.com/identity/images/g-logo.png",
                            "thumbnailUrl": "https://developers.google.com/identity/images/g-logo.png",
                            "forceRefresh": true,
                            "altText": "string"
                        }
                    },
                    "suggestions": [
                        {
                            "reply": {
                                "text": "Send reply message",
                                "postbackData": "how may help you?"
                            }
                        }
                    ]
                },
                {
                    "title": "Carousel 3",
                    "description": "This is carousel 3 description",
                    "media": {
                        "height": "MEDIUM",
                        "contentInfo": {
                            "fileUrl": "https://developers.google.com/identity/images/g-logo.png",
                            "thumbnailUrl": "https://developers.google.com/identity/images/g-logo.png",
                            "forceRefresh": true,
                            "altText": "string"
                        }
                    },
                    "suggestions": [
                        {
                            "reply": {
                                "text": "reply carousel 3",
                                "postbackData": "Need more help?"
                            }
                        }
                    ]
                }
            ]
        }
    }
}

Common Parameters

ParameterTypeMandatoryDescription
callbackUrlstringNoThe Webex Connect platform will send notifications to the URL specified in the callbackurl parameter. The URL is used to retrieve the status of the message sent. The callbackUrl/notifyurl can also be configured while creating a service. If the URL is specified in both the service and the messaging API, preference will be given to the messaging API request.
callbackDatastringNoData that you have configured to receive on the callbackUrl. This is configured as a part of the request.
correlationIdStringNoThe correlationid is a unique identifier that you can attach to every request as a reference to a particular transaction or event. This is configured as a part of the request.
fromstringYesRepresents the App ID. The ID of the app asset that you can obtain from the Connect platform.
tostringYesThe destination ID represents google business message conversation id which uniquely identifies conversation between business and customer.
representativeJSONObjectYesJSON object for representative/agent configuration.
avatarImageURLNoText that Business wants to send to the end user.It can also contain rich text such as text for Bold, text for Italics, text for Hyperlink, and \n for Line break in the message text.
displayNameStringNoDisplay name of the agent/message sender.
representativeTypeStringYesrepresentativeType allows to choose the agent type, between Bot and Human.

Message Type - Text

ParameterTypeMandatoryDescription
textStringYesText that Business wants to send to the end user.It can also contain rich text such as text for Bold, text for Italics, text for Hyperlink, and \n for Line break in the message text.
containsRichTextBooleanNoBoolean value to check for rich text elements
fallbackStringNoPlain text that gets delivered when the user’s device doesn’t support the actual message sent

Message Type - Image

ParameterTypeMandatoryDescription
fallbackStringNoPlain text that gets delivered when the user’s device doesn’t support the actual message sent
imageJSONObjectJSON object for configuration of image.
contentInfoJSONObjectYesJSON object for configuration of image content.
containsRichTextBooleanNoBoolean value to check for rich text elements.
fileUrlURLYesContains the URL of the file.
thumbnailUrlURLNoContains the URL of the thumbnail.
forceRefreshBooleanNoBoolean to indicate whether the image needs to be refreshed on the user’s device.
altTextStringYesAlternate text appears as a placeholder when the image is not available.

Message Type - RichCard - Standalone

ParameterTypeMandatoryDescription
fallbackStringNoAlternate Text when the user’s device doesn’t support the message sent
containsRichTextBooleanNoBoolean value to check for rich text elements
richCardJSONObjectYesJSON object for configuring rich card. It can either be a standalone card or carousel card.
standaloneCardJSONArrayYesJSON object for configuring standalone rich card.
cardContentJSONArrayYesJSON object for configuring standalone rich card content.
titleStringNoSpecifies the message title for the card.
descriptionStringNoSpecifies the message description for the card.
mediaJSONArrayNoDirect URL pointing to the media file.
heightSpecifies the image’s height, values can be SHORT,MEDIUM and TALL.
contentInfoJSONArrayYesJSON object for configuration of image content.
fileUrlURLYesContains the URL of the file
thumbnailUrlURLNoContains the URL of the thumbnail
forceRefreshBooleanNoBoolean to indicate whether the image needs to be refreshed on the user’s device
altTextStringYesAlternate text appears as a placeholder when the image is not available.

Message Type - RichCard - Carousel

ParameterTypeMandatoryDescription
fallbackStringNoAlternate Text when the user’s device doesn’t support the message sent
containsRichTextBooleanNoBoolean value to check for rich text elements
richCardJSONObjectYesSpecifies 2 or more rich cards
carouselCardJSONObjectYesJSON object for configuring carousel card.
cardWidthStringNoSpecifies the card’s width including values as SMALL and MEDIUM
cardContentsJSONArrayYesJSON object for configuring carousel card content.
titleStringNoSpecifies the message title.
descriptionStringNoSpecifies the message description for the card.
mediaJSONArrayNoDirect URL pointing to the media file.
heightSpecifies the card’s height, including values such as SHORT,MEDIUM and TALL.
contentInfoJSONObjectYesJSON object for configuration of image content.
fileUrlURLYesContains the URL of the file
thumbnailUrlURLNoContains the URL of the thumbnail
forceRefreshBooleanNoBoolean to indicate whether the image needs to be refreshed on the user’s device
altTextStringYesAlternate text appears as a placeholder when the image is not available.

Suggestion Types

They include REPLY and ACTION

ParameterTypeMandatoryDescription
suggestionsJSONArrayNoContains one or more suggestions, with each suggestion containing fields as mentioned in the Suggestion Table
replyJSONObjectNoSpecifies the message type.
textStringYesContains the text for the header. Maximum of 60 characters is supported for text.
postbackDataStringYesPostback data to be sent back as part of response. Applicable only for the suggestion types Reply and Action
actionJSONObjectNoJSON object for which can be either dial action or URL action.
openUrlActionJSONObjectYesThe URL to which the consumer would be taken.
dialActionJSONObjectYesThe phone number to which the consumer is dialed.
liveAgentRequestJSONArrayNoJSON object to provide a live agent request suggestion.

Google Business Message Event API Sample

{
    "callbackUrl": "https://01hj8c2x2e3chpx0hvr6cjpw0j00-990f5b52a7e1c00b0f77.requestinspector.com",
    "callbackData": "customerID123|1234|new_sale",
    "correlationId": "deXXXX32-3XXd-46c9-b132-15e010a80ccc",
    "from": "a_167344112755437860",
    "to": "dec11241-76ae-493d-8a3a-06bd7a1c8f77",
    "representative": {
        "representativeType": "HUMAN",
        "displayName": "AGENT",
        "avatarImage": "https://developers.google.com/identity/images/g-logo.png"
    },
    "event": "REPRESENTATIVE_JOINED"
}
{
    "callbackUrl": "https://01hj8c2x2e3chpx0hvr6cjpw0j00-990f5b52a7e1c00b0f77.requestinspector.com",
    "callbackData": "customerID123|1234|new_sale",
    "correlationId": "de36bb32-3f5d-46c9-b132-15e010a80ccc",
    "from": "a_167344112755437860",
    "to": "dec11241-76ae-493d-8a3a-06bd7a1c8f77",
    "representative": {
        "representativeType": "HUMAN",
        "displayName": "AGENT",
        "avatarImage": "https://developers.google.com/identity/images/g-logo.png"
    },
    "event": "REPRESENTATIVE_LEFT"
}'

{
    "callbackUrl": "https://01hj8c2x2e3chpx0hvr6cjpw0j00-990f5b52a7e1c00b0f77.requestinspector.com",
    "callbackData": "customerID123|1234|new_sale",
    "correlationId": "de36bb32-3f5d-46c9-b132-15e010a80ccc",
    "from": "a_167344112755437860",
    "to": "dec11241-76ae-493d-8a3a-06bd7a1c8f77",
    "representative": {
        "representativeType": "BOT",
        "displayName": "BOT",
        "avatarImage": "https://developers.google.com/identity/images/g-logo.png"
    },
    "event": "TYPING_STARTED"
}'

{
    "callbackUrl": "https://01hj8c2x2e3chpx0hvr6cjpw0j00-990f5b52a7e1c00b0f77.requestinspector.com",
    "callbackData": "customerID123|1234|new_sale",
    "correlationId": "de36bb32-3f5d-46c9-b132-15e010a80ccc",
    "from": "a_167344112755437860",
    "to": "dec11241-76ae-493d-8a3a-06bd7a1c8f77",
    "representative": {
        "representativeType": "BOT",
        "displayName": "BOT",
        "avatarImage": "https://developers.google.com/identity/images/g-logo.png"
    },
    "event": "TYPING_STOPPED"
}'

You can refer to common body parameters from the common parameters table above. Channel-specific parameters are available in the table below:

ParameterTypeMandatoryDescription
eventJSON ArrayNoExplains the state of the representative. The following states of "event" can be viewed as a result of the representative action:

Representative Joined- value "REPRESENTATIVE_JOINED"

Representative Left- value "REPRESENTATIVE_LEFT"

Typing Indicator Started- value "TYPING_STARTED"

Typing Indicator Stopped-value "TYPING_STOPPED"
Language
Authorization
Query
Click Try It! to start a request and see the response here!