Administrator
Administrator
1 0 876
‎04-09-2020 12:12 AM

Summary

A technical guide to creating Zinc Message Cards via the messaging API

Overview

Zinc Message Cards is a way to share interactive snippets of content directly within Zinc conversations.  They can contain formatted text, labelled fields, photos, and call-to-action buttons. Message cards can only be created through the Zinc message API.


Step-by-Step

Message Cards can be composed using several different components. Each is optional.

The paragraph component, and the values in the “key-value” component support a subset of the Markdown formatting language, including bulleted lists, italics, bolded text, and embedded URL links.

 

Message Card User Interface

There are two user interfaces for message card content – one is the preview card that appears in the conversation timeline, and the other is an optional full-screen “details” view that users can access by clicking or tapping on the card in the timeline.

Conversation Timeline Preview

The timeline preview card is designed to show a small amount of content directly in the conversation timeline. It can contain any or all of the message card components but they will be truncated so the card doesn’t take up too much room in the conversation. Keep the conversation timeline content short &ndash to present more content, use the details view.

Details View

The details view shows all of the message card content. You can send multiple paragraphs of text, or long lists of labeled fields (key-value data pairs).

 

 

External Links

Message cards can also be made to link to an external URL. If a card with an external link does not have a details view then when users click or tap on the card it will open the link. If, on the other hand, a card with an external link does have a details view, then an external link icon will appear in the details view, which users can click or tap on to open the link.

 

Action Buttons

In addition to holding content, message cards can also contain call-to-action buttons. These can be made to either open a URL with an HTTP GET request, or a send a pre-configured data payload to an API endpoint with an HTTP POST request. (HTTP methods other than GET and POST are not supported currently.) You can add action buttons to either the conversation timeline preview, or the details view, or both.

 

Markdown Support

The paragraph and key-value components of message cards support a subset of the Markdown text formatting language.  This lets you embed links and also create more visually effective content.

 

API Documentation

Message card content must be specified under the "template" field in the JSON payload sent to the Zinc message API endpoint when creating a message card.

Here is an example of a message card payload:

{
  "template": {
    "link": "https://www.example.com/external/record/page",
    "preview": {
      "header": {
        "title": "Message Card Title",
        "subtitle": "Text that supports the title",
        "image_url": "https://api.example.com/photo.jpeg"
      },
      "sections": [
        {
          "type": "paragraph",
          "text": "A few sentences of text that will appear on the card in the timeline. You can add anything you like."
        }
      ],
      "actions": [
        {
          "url": "https://api.example.com/some/action",
          "type": "postback",
          "text": "Click Here",
          "payload": "random=information"
        }
      ]
    },
    "details": {
      "header": {
        "title": "Message Card Title",
        "subtitle": "Supporting text, which can be different from preview header",
        "image_url": "https://api.example.com/photo.jpeg"
      },
      "sections": [
        {
          "type": "paragraph",
          "text": "A few sentences of text that will appear on the card in the timeline. You can add anything you like."
        },
        {
          "type": "key_value",
          "values": [
            {
              "label": "Name",
              "value": "Foobert Bar"
            },
            {
              "label": "Occupation",
              "value": "Example Message Card"
            },
            {
              "label": "Date of Birth",
              "value": "December 10th 2019"
            }
          ]
        }
      ],
      "actions": [
        {
          "url": "https://api.example.com/some/action",
          "type": "postback",
          "text": "Click Here",
          "payload": "random=information"
        },
        {
          "url": "https://www.example.com",
          "type": "web_url",
          "text": "Go to Example"
        }
      ]
    }
  }
}

Top-Level Message Card Attributes

[Optional] Object describing the contents of the "drill-in" details view.
Attribute NameDescription
preview[Required] object describing the contents of the timeline preview card view
details[Optional] Object describing the contents of the "drill-in" details view.
link[Optional] URL for resource to be opened when the card is clicked, or if the card has a "details" view, then the resource opened when the user clicks on the external link icon.


Preview and Details Attributes

Both the "preview" and "details" objects have the same attributes available.  The preview and details can be different from each other.  They do not need to have the same exact data.

Attribute NameDescription
headerThe header object, which contains fields that appear at the top of the message card.
sectionsAn array of section objects.


Header Attributes

The header object in either the preview or details can have the following attributes:

Attribute NameDescription
titleTitle content to appear in timeline preview card
subtitleSub-title content to appear in timeline preview card
image_urlURL of image to appear in timeline preview card


Section Object Attributes

The section objects appear in the "sections" array in either the preview or details.

Attribute NameDescription
typeThe section type. Allow values are "paragraph" or "key_value"
textOnly valid for "paragraph" type sections. This is the text of the paragraph. (A subset of Markdown syntax is supported in this field.)
valuesOnly valid for "key_value" type sections. An array of key-value objects.


Key-Value Object Attributes

Attribute NameDescription
labelThe field label (i.e. the "key" in the key-value pair)
valueThe field data (i.e. the "value" in the key-value pair)


Action Object Attributes

Action objects can appear in either the preview or details. Different actions can be put in each.

Attribute NameDescription
typeThe type of action. The allowed types are:
- "postback" - performs an HTTP POST request, optionally with a specified data payload
- "web_url" - opens the specified URL via an HTTP GET in a web browser
urlThe URL associated with the action
textThe text to appear on the button
payloadOnly valid for "postback" actions. These are form keys and values to send along with the POST request.

Terms of Use

ServiceMax terms of use are as follows: Images and content used on this site are owned or licensed by ServiceMax Inc. or its affiliates for use on this site only. Unauthorized use is prohibited.

©2015 ServiceMax. All Rights Reserved.

Note: ServiceMax makes every effort to ensure the accuracy of the information contained within this article, but assumes no responsibility or liability for any errors or inaccuracies that may appear. All references to versions, system requirements or supported features should be referenced within online help documentation for most up to date information. If you do find any errors or inaccuracies, please send your feedback to knowledge@servicemax.com.