About Structured Messages
Engage Digital provides a REST API (using JSON bodies) to create structured messages from third party applications. This provides a richer messaging experience for customers.
Types of Structured Messages
Engage Digital supports the following types of structure messages:
| Type | Description |
|---|---|
select |
This structured message provides a list from which the customer can pick some elements. |
rich_link |
This structured message allows to decorate a link with an image, title and subtitle. |
template |
This structured message provides some buttons associated with a message. |
carousel |
This structured message allows to group multiple templates in the same message. |
time_select |
This structured message provides a list of dates from which the customer can choose an appointment. |
apple_pay |
This structured message provides a convenient way to ask for a payment from the customer. |
authenticate |
This structured message provides a way to send an OAuth2 authentication request to the customer. |
Channel Capabilities
Engage Digital provides an omnichannel API to create structured messages. Since not every channel supports every type of structured message, this comparison grid allows to have a general overview of the different features and limitations of each channel.
- Yes: Supported
- Not yet: Supported by channel but not by Engage Digital yet
- N/A: Not supported by channel
| select | rich_link | template | carousel | list | time_select | form | apple_pay | authenticate | |
|---|---|---|---|---|---|---|---|---|---|
| Apple Messages for Business | Yes | Yes | N/A | N/A | Yes | Yes | Yes | Yes | Yes |
| Facebook Messenger | Yes | Yes | Yes | Yes | N/A | N/A | N/A | N/A | N/A |
| Engage Web Messaging | Yes | Yes | Yes | Yes | N/A | N/A | N/A | N/A | N/A |
| Engage iOS Messaging | Yes | Yes | Yes | Yes | N/A | N/A | N/A | N/A | N/A |
| Engage Android Messaging | Yes | Yes | Yes | Yes | N/A | N/A | N/A | N/A | N/A |
| Google Business Messages | Yes | Yes | Yes | Yes | N/A | N/A | N/A | N/A | N/A |
| Channel SDK | Yes | Yes | Yes | Yes | N/A | N/A | N/A | N/A | N/A |
| Twitter Direct Messages | Not yet | Not yet | Not yet | N/A | N/A | N/A | N/A | N/A | N/A |
| Viber | Not yet | Not yet | Not yet | Not yet | N/A | N/A | N/A | N/A | N/A |
| N/A | N/A | Yes | N/A | Yes | N/A | N/A | N/A | N/A | |
| Instagram Messaging | Yes | Yes | Yes | Yes | N/A | N/A | N/A | N/A | N/A |
Channel Compatibilities
The Engage Digital omnichannel REST API strives to make a single payload compatible on every channel. However, each channel has their own features and limitations, this is why this omnichannel REST API will implicitly ignore or limit the different fields to adapt to the specified channel.
This section describes the generic compatibility logic of the API. Check the following section for the features and limitations specific to every channel.
| Limitation/Feature | Compatibility Description |
|---|---|
| Max number of items | Only processes the channel max number of items and ignores the other items. This applies for both the number of items in a template and the number of templates in a carousel. For example, if the channel supports a maximum of 4 items and the payload has 10 items, the API will only keep the first 4 items and discard the last 6 items. |
| Max number of characters of a String | Truncates the String to the channel max number of characters and adds an ellipsis. For example, if the channel supports a maximum of 80 characters and in the payload, the field is 100 characters, the API will truncate the field to 80 characters with an ellipsis. |
| Channel specific property | Ignores the property on channels not supporting it. Only the channel supporting the property processes it. For example, the Engage Messaging channel supports the “center_items” property on the select structured content. If this property is also used to create a FB Messenger quick reply structured content, it will be ignored. |
| Payload property presence | When the payload property (optional by default) is required by a channel, the API will generate a default value to be sent. For example, Google Business Messages requires the presence of the “payload” property. When blank, the API will generate a random value to be sent instead. |
| Deep links (url) | If the channel does not support deep links, we provide a url_fallback field to be used instead. The url_fallback is validated if the url is present. The validations are:
|
| Non-standard attachment type | If the channel does not support the attachment, we provide an attachment_fallback_id field to be used instead. The attachment_fallback_id is validated if the attachment_id is present. The validations are:
|
| Structured content type not existing in the channel | If a structured content type does not exist in a channel, the API will try to best represent it by converting it to another type the channel supports. See the channel specificities section for a more detailed behavior on this conversion. For example, the rich link type does not exist in Google Business Messages. So an Engage Digital Rich Link is converted to a Google Business Messages Rich Card with a single button representing the url. |
Channel Specificities
Apple Messages for Business
Facebook Messenger
Engage Messaging
Google Business Messages
Instagram Messaging
Channel SDK
Channel SDK supports only public attachments. Before sending a payload to third-party endpoint attachment_id is replaced by “attachment_url”. All other capabilities are inherited from the base validation described in this document.