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.
14 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({
Looks like this may have fallen through the cracks -- the above query is close but the enumeration QUICK_REPLY_ACTION shouldn't be enclosed in quotes.
There's also a developer help community topic specific to Chat Conversations API here: Zendesk Chat Conversations API -- you'll probably get a wider range of community members looking at posts there.
Hi!
Great article!
While implementation I got 2 road-blockers, hoping you can help.
if I can display more than 3 buttons somehow, please suggest me how.
Moreover, the chat history is being displayed as unsupported content for the agent. How can I send the chat history properly in a readable format?
Thanks!
Hi Smriti,
Three buttons is the maximum for sendButtonTemplate documented here. There are no plans to extend this. Perhaps sendQuickReplies could offer a workaround.
For the chat history display question, can you please provide the context that you're getting and displaying chat history. It's not clear to me what you're looking for. Are you looking for a format that displays similar to what displays in the widget? Thanks for the additional info.
PS - For future posts, if you post to the Chat Conversations API developer forum instead of here, you may get a quicker response as this article is not monitored as closely.
Please sign in to leave a comment.