Structured messages

In sending messages we explain how to send a basic text message in a conversation. But there is a lot more to messaging than just exchanging text. This guide explains how to use the API to send structured messages to your users. You can use this wide variety of message types to create rich conversational experiences with your customers that combine a variety of media and interactive elements.

For the full reference of supported types and parameters, consult the Post Message API documentation.

Images, stickers and GIFs

In order to send an image using the API, we follow the recipe for sending text messages, but set the type parameter to image and set the mediaUrl field to a URL for the image to be sent to the user:

const apiInstance = new SunshineConversationsClient.MessagesApi()
const data = new SunshineConversationsClient.MessagePost()
data.author = {
  type: "business"
}
data.content = {
  type: "image",
  mediaUrl: "https://example.org/image.jpg"
}

await apiInstance.postMessage("{appId}", "{conversationId}", data)

To send a sticker, simply have the mediaUrl point to a transparent-background PNG and most messaging clients will format the message accordingly. Animated GIFs work in a similar manner, however, some platforms don't have full support for GIFs and might only display them as still images.

Files

Similar to images, you can also supply a mediaUrl for the user to download a file. See supported file types for messaging attachments in Zendesk help. Use the file type for your message instead of image:

const apiInstance = new SunshineConversationsClient.MessagesApi()
const data = new SunshineConversationsClient.MessagePost()
data.author = {
  type: "business"
}
data.content = {
  type: "file",
  mediaUrl: "https://example.org/document.pdf"
}

await apiInstance.postMessage("{appId}", "{conversationId}", data)

Action buttons

You can use buttons to guide the user to act on the information in your conversation. Buttons can trigger replies, web links, and more. For messaging channels where buttons are not natively supported, Zendesk has built in fallback behaviours that attempt to communicate the intent of the action in the best way possible. For example, a link button might fallback to a simple hyperlink on channels such as SMS.

Buttons can be sent by including an actions array in your message. Mixing different action types is allowed, however reply actions cannot be mixed with other action types in the same message.

The number of actions allowed in a given message may be limited by third party channels. If the actions array of a message exceeds the number of actions that the channel allows, the list will be truncated to fit the limit, and actions beyond the allowed size will be ignored.

Link buttons

Link buttons allow you to send a call to action that opens a URL when tapped or clicked. You can configure the buttons with any valid URL - use it to send links to web pages or deep-link into apps:

const apiInstance = new SunshineConversationsClient.MessagesApi()
const data = new SunshineConversationsClient.MessagePost()
data.author = {
  type: "business"
}
data.content = {
  type: "text",
  text: "Please click on this button",
  actions: [
    {
      type: "link",
      text: "Button Label",
      uri: "https://url.button.com"
    }
  ]
}

await apiInstance.postMessage("{appId}", "{conversationId}", data)

Webview buttons

Webview buttons allow you to send Conversations Extensions to render custom experiences on top of the conversation when the button is tapped, while keeping the user in the same seamless flow. Webview actions use the type webview:

const apiInstance = new SunshineConversationsClient.MessagesApi()
const data = new SunshineConversationsClient.MessagePost()
data.author = {
  type: "business"
}
data.content = {
  type: "text",
  text: "Pick a date for your delivery.",
  actions: [
    {
      type: "webview",
      text: "Pick Date",
      uri: "https://pick-a-date.com",
      fallback: "https://pick-a-date-fallback.com"
    }
  ]
}

await apiInstance.postMessage("{appId}", "{conversationId}", data)

Note: If a user is messaging via the Web Widget in an https page, the webview URI must also be https or it will fail to load.

For more information, see Using conversation extensions.

Reply buttons

Reply buttons (or quick replies) are a great way to walk the user through a specific flow, by suggesting various courses of action. A reply button, once tapped, will insert a reply on behalf of the user. Suggested replies are invaluable when building a bot or automated conversation flow, because they keep your user focused and provide clear instructions on how to proceed.

Each reply button has an associated payload, which should uniquely identify the intent of the action. When the user answers with one of the suggested replies, this payload will be included as part of the resulting message object. To send quick replies, use the reply action type:

const apiInstance = new SunshineConversationsClient.MessagesApi()
const data = new SunshineConversationsClient.MessagePost()
data.author = {
  type: "business"
}
data.content = {
  type: "text",
  text: "Which do you prefer?",
  actions: [
    {
      type: "reply",
      text: "Tacos",
      iconUrl: "https://example.org/taco.png",
      payload: "TACOS"
    },
    {
      type: "reply",
      text: "Burritos",
      iconUrl: "https://example.org/burrito.png",
      payload: "BURRITOS"
    }
  ]
}

await apiInstance.postMessage("{appId}", "{conversationId}", data)

Postback buttons

Postback buttons are a great way to enhance your conversations by triggering server-side logic when a user clicks on them. When you send the postback button, you can attach a payload which is communicated to your server via the conversation:postback trigger once the button is tapped. This allows you to respond to the press of a button from your backend. The server-side logic can use the payload to run different code based on the context of the conversation.

Postback buttons are similar in function to reply buttons, but with a few key differences:

• Postbacks are multi-use. The button does not disappear after the user taps on it, and therefore it can be clicked many times.
• By default, postbacks do not echo the user’s selection in the conversation history. This can be customized with the echoPostback app setting.
• Postbacks use the conversation:postback webhook event to communicate the payload, rather than the conversation:message event.

You can use postbacks in combination with other button types using the API:

const apiInstance = new SunshineConversationsClient.MessagesApi()
const data = new SunshineConversationsClient.MessagePost()
data.author = {
  type: "business"
}
data.content = {
  type: "text",
  text: "Please click one of these buttons",
  actions: [
    {
      type: "postback",
      text: "Postback Button Label",
      payload: "PAYLOAD_HERE"
    },
    {
      type: "link",
      text: "Link Button Label",
      uri: "https://url.button.com"
    }
  ]
}

await apiInstance.postMessage("{appId}", "{conversationId}", data)

Compound messages

A compound message is a message which can include text, action buttons and an image. This does not have a dedicated message type, but can crafted by supplying any combination of these three elements.

An image message with text and action buttons:

const apiInstance = new SunshineConversationsClient.MessagesApi()
const data = new SunshineConversationsClient.MessagePost()
data.author = {
  type: "business"
}
data.content = {
  type: "image",
  text: "I strongly recommend our Family Basket, it's perfect for your needs!",
  actions: [
    {
      type: "postback",
      text: "Subscribe",
      payload: "SUBSCRIBE"
    },
    {
      type: "postback",
      text: "Learn more",
      payload: "LEARN_MORE"
    }
  ],
  mediaUrl: "https://media.smooch.io/templates/template-family-basket.jpg"
}

await apiInstance.postMessage("{appId}", "{conversationId}", data)

A text message with action buttons:

const apiInstance = new SunshineConversationsClient.MessagesApi()
const data = new SunshineConversationsClient.MessagePost()
data.author = {
  type: "business"
}
data.content = {
  type: "text",
  text: "I strongly recommend our Family Basket, it's perfect for your needs!",
  actions: [
    {
      type: "postback",
      text: "Subscribe",
      payload: "SUBSCRIBE"
    },
    {
      type: "postback",
      text: "Learn more",
      payload: "LEARN_MORE"
    }
  ]
}

await apiInstance.postMessage("{appId}", "{conversationId}", data)

Carousels

Carousel messages are a horizontally scrollable set of items that may each contain text, an image, and up to 3 message actions. Not all messaging channels fully support carousel messages; to check the level of support across messaging channels see channel capabilities. Send a carousel message using the carousel type and an array of items:

const apiInstance = new SunshineConversationsClient.MessagesApi()
const data = new SunshineConversationsClient.MessagePost()
data.author = {
  type: "business"
}
data.content = {
  type: "carousel",
  items: [
    {
      title: "Tacos",
      description: "Description",
      mediaUrl: "https://example.org/image.jpg",
      actions: [
        {
          text: "Select",
          type: "postback",
          payload: "TACOS"
        },
        {
          text: "More info",
          type: "link",
          uri: "https://example.org"
        }
      ]
    },
    {
      title: "Ramen",
      description: "Description",
      mediaUrl: "https://example.org/image.jpg",
      actions: [
        {
          text: "Select",
          type: "postback",
          payload: "RAMEN"
        },
        {
          text: "More info",
          type: "link",
          uri: "https://example.org"
        }
      ]
    }
  ]
}

await apiInstance.postMessage("{appId}", "{conversationId}", data)

Forms

Form messages allow you to capture user data in an ongoing conversation by displaying a form that can contain text and email inputs as well as select dropdowns. Use the form message type and specify an array of fields:

const apiInstance = new SunshineConversationsClient.MessagesApi()
const data = new SunshineConversationsClient.MessagePost()
data.author = {
  type: "business"
}
data.content = {
  type: "form",
  fields: [
    {
      type: "text",
      name: "name",
      label: "Name",
      placeholder: "Enter your name..."
    },
    {
      type: "email",
      name: "email",
      label: "Email",
      placeholder: "Enter your email..."
    },
    {
      type: "select",
      name: "meal",
      label: "Meal",
      placeholder: "Choose your meal...",
      options: [
        {
          name: "taco",
          label: "Taco"
        },
        {
          name: "burrito",
          label: "Burrito"
        },
        {
          name: "enchiladas",
          label: "Enchiladas"
        }
      ]
    }
  ]
}

await apiInstance.postMessage("{appId}", "{conversationId}", data)

Form messages are only supported on our native messaging SDKs. Attempting to send a form to a user on a social channel will result in a delivery error.

When the user completes the form, a message will be generated with the type formResponse containing the user's answers for each field. For form and form response schema details, see Post Message.

Rich text

Rich text messages allow you to send messages with text formatting such as bold, italic, underline, strikethrough, and code. You can also include links in your messages, or even format them using a subset of HTML.

To send a message with rich text using Post Message, set the property type to one of the following: text, image or file. You must specify either htmlText or markdownText but not both. If both htmlText and markdownText are provided, the message will be rejected.

When markdownText is specified, the provided markdown will be automatically converted to HTML and stored in the htmlText field. In other words, markdownText can be sent to the platform in order to generate HTML, but it cannot be read back in its original form afterwards.

The htmlText field is subject to a 4096-character limit. If htmlText exceeds this limit, or if the markdownText is converted to an htmlText that exceeds this limit, the message will be rejected.

const apiInstance = new SunshineConversationsClient.MessagesApi()
const data = new SunshineConversationsClient.MessagePost()
data.author = {
  type: "business"
}
data.content = {
  type: "text",
  htmlText:
    '<b>This is bold</b> <i>This is italic</i> <u>This is underline</u> <s>This is strikethrough</s> <code>This is code</code> <a href="https://example.com">This is a link</a>'
}

await apiInstance.postMessage("{appId}", "{conversationId}", data)

Supported tags / attributes

When sending rich text, only a subset of markdown / HTML tags and attributes are supported. Unsupported tags will be stripped from the message content. The following table lists the supported tags and attributes:

Tag	Attributes
<b>
<br>
<p>
<span>
<strong>
<b>
<em>
<i>
<u>
<ins>
<s>
<del>
<a>	href, target
<ol>
<ul>
<li>
<h1>
<h2>
<h3>
<h4>
<h5>
<h6>
<code>
<q>

Next steps

• Check the channel capabilities grid to understand how structured messages are supported across different platforms.
• Learn how to quickly craft structured messages using our messaging shorthand syntax.
• Template messages can be used to store reusable structured message payloads which can be sent to multiple users.