The structured messaging feature in Zendesk Chat allows you to provide elements that enhance and simplify a customer's chat experience. These elements include quick reply buttons, GIFs (as image in a template), and persistent panel templates, among others.
Currently, accounts use the Chat Conversations API to add structured messages to their chats.
You do not need to manually enable the structured messaging feature. If your account meets the requirements described in this article, you can begin using structured messages in chats. This article includes the following topics:
Requirements and restrictions
To use structured messaging, you must meet the following requirements:
- Your Zendesk Chat account is Enterprise or Premium (Legacy)
- You are using the Web Widget integrated Chat experience.
OR
You are using the Chat Web SDK version 1.6.0 or above. See Structured Message Payload for details.
- You have access to the Zendesk Chat Conversations API.
Additionally, each message type has certain restrictions, regarding the number and type of included items. See the descriptions below for specifics.
Structured message types
The available structured message types are:
Quick replies
Quick replies allow an agent to send a message with a number of option buttons for an end user to choose from. When the end user clicks a button, it sends a pre-defined reply to the agent.
You can include up to 11 buttons in a quick reply.
Button templates
A button template allows an agent to send a message along with a list of buttons. When clicked by the end user, these buttons can:
- Launch a quick reply, as described above, or
- Open a URL in a new tab
A button template must include at least one button, and can include a maximum of three buttons.
Panel templates
A panel template allows an agent to send a message with a panel and a list of buttons.
The panel can include an image, title, and subtitle. When clicked by the end user, the panel can:
- Open a URL in a new tab
When clicked by the end user, the buttons can:
- Launch a quick reply, as described above, or
- Open a URL in a new tab
Panel template carousel
A panel template carousel allows an agent to send an array of panel templates as a carousel.
A carousel must include at least two items, and can include a maximum of 10 items.
List template
A list template allows an agent to send an array of items with an optional button.
A list template should include at least two items, and can inlcude a maximum of four items. The template should include no more than one button.
The item(s) can include an title, subtitle, and an optional image. When clicked by the end user, the item can:
-
Open a URL in a new tab
When clicked by the end user, the button can:
- Launch a quick reply, as described above, or
- Open a URL in a new tab
Using structured messages in chats
To use structured messages in chats, you must use the Chat Conversations API. To familiarize yourself with this, see Getting Started with the Chat Conversations API.
We recommend you write an application that can act as an agent using the Conversations API. For a step-by-step walkthrough on writing this application, see the section Getting Started. Once this is completed, instead of using the sendMessage mutation to deliver a text message to the end user, the application can use the following mutations to send a structured message:
| Structured message type | Conversations API mutation name |
|---|---|
| Quick replies | sendQuickReplies |
| Button templates | sendButtonTemplate |
| Panel templates | sendPanelTemplate |
| Panel template carousel | sendPanelTemplateCarousel |
| List template | sendListTemplate |
Refer to the Conversations API schema documentation for the full API details.
11 Comments
So to use structured messages we would need to write our own Chat application? As in totally discard the current Chat web widget. Are there no software hooks in the Chat web widget for us to inject this new functionality?
Hi Van,
You can use either Web Widget with integrated Chat experience or your custom-build widget with Chat SDK. If you use Web Widget, you can turn on the integrated Chat experience in Widget settings page.
Hi Sutrisno,
I have "Integrated Chat" enabled. Now what?
- Where do I hook into the current javascript of the Web Widget?
- What events should I listen for?
- Any documentation on how to get structured with the existing Web Widget?
- Difference between chat shortcuts and structured messages?
- Where do I hook into the current javascript of the Web Widget? What events should I listen for?
You don't need to do anything with the Web Widget. If an agent sent a structured message to a visitor that uses Web Widget, the visitor should be able to see it as per the screenshot above.
- Any documentation on how to get structured with the existing Web Widget?
For an agent to send structured messages, you need to initialize an agent session with Chat Conversations API and use the API to send the structured messages to the visitors. As of now, this is the only way to send structured messages.
- Difference between chat shortcuts and structured messages?
Hi Sutrisno,
Could you please suggest a way to send structured message as a first message to a customer after he just opens web chat.
Thanks!
Hi Sergey,
Can I clarify whether you are referring to sending a structured message before the customer start a chat? If that's the case, I'm afraid that it is not possible at the moment. To better understand the use case, could you elaborate on the flow that you have in your mind?
Hi, it is possible to send structured messages from human agent?
Hi Antonino Tocco
Can you kindly expand on what you mean please?
Hi, Heather thanks for your help.
I have seen that with Chat Conversational API it is possible to send structured messages.
But Chat Conversational API seems to be designed for bot interaction, not human.
How I can send structured messages with human agent interaction?
Hi Antonino Tocco,
I also responded likewise over here https://support.zendesk.com/hc/en-us/articles/360022184574?page=1#comment_360003483434
It does look like others are having difficulty using the Conversational Chat API to send structured messages. (ref: https://develop.zendesk.com/hc/en-us/articles/360001331787/comments/360001751547 )
My experience doesn't include this API. We have our Agents use shortcuts and they work quite well.
I'm sorry I can't be of more help. Hopefully someone else will jump in here to assist.
As per the documentation https://zendesk.github.io/conversations-api/mutation.doc.html I have used the same payload for button templates. But button templates doesn't work where as quick replies, simple messages works.
Button template Payload:
JSON.stringify({
Please sign in to leave a comment.