English (US)
  1. Zendesk help
  2. Chat
  3. Using Chat
  4. Agent guide

Using structured messages in Zendesk Chat

Sutrisno Suryajaya
  • Edited

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:

Additionally, each message type has certain restrictions, regarding the number and type of included items. See the descriptions below for specifics.

Note: Structured messages are not currently supported on the Chat Android SDK and Chat iOS SDK.

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:

Note: These mutations support a fallback parameter, which is used in situations where structured messaging is not supported (see Requirements and restrictions, above).
Table 1.
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.

Return to top
Have more questions? Submit a request

15 Comments

  • Van Nguyen
    • Edited

    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?

    1
  • Sutrisno Suryajaya

    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.

    0
  • Van Nguyen

    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?

    0
  • Sutrisno Suryajaya

    - 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?

    • How agent sent them? Shortcuts are sent through the Chat dashboard. Structured messages are sent through Chat Conversations API
    • What is the content? Shortcuts can only contain text and options. Structured messages provide you various templates that include more elements such as interactive buttons and images.
    1
  • Sergey

    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!

    0
  • Sutrisno Suryajaya

    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?

    0
  • Antonino Tocco

    Hi, it is possible to send structured messages from human agent?

     

    0
  • Heather Rommel
    Community Moderator

    Hi Antonino Tocco

    Can you kindly expand on what you mean please?

    0
  • Antonino Tocco

    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?

    0
  • Heather Rommel
    • Edited
    Community Moderator

     

    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.

    0
  • Bhargav Guduri

    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({

                payload: {
                    query: `mutation { 
                        sendButtonTemplate(
                                          channel_id: "${channelId}", 
                                          msg: "You are going to be transferred to  department shortly",
                                          buttons:[{action:{type:"QUICK_REPLY_ACTION", value:"hi"},text:"hi"}]
                                      ) {
                                          success
                                      }
                                  }`
                  },
                  type: "request",
                  id: REQUEST_ID.SEND_BUTTON_TEMPLATE
            });


    Is there something I am missing?
    0
  • Bryan - Community Manager
    • Edited
    Zendesk Developer Support

    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.

    0
  • Smriti

    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!

    0
  • Bryan - Community Manager
    Zendesk Developer Support

    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.

    0
  • Unto
    • Edited

    Will structured messages work in mobile apps using the zendesk chat mobile SDK ? its a bit unclear. in the article you say these messages are not supported by zendesk mobile "app".

     

    0

Please sign in to leave a comment.

Related articles

Powered by Zendesk