跳至主要内容

介紹 Message Templates

Overview​

在 Asgard 的 message object 中，有一個 template 欄位用來提供前端公版的渲染資料物件。範例如下：

Common Features​

text 欄位​

Template Type 如 TEXT BUTTON 的屬性當中都有 text 欄位，如果在設定 Template 時刻意省略，則 Asgard 將會以 Push Message Processor 的 message 設定直接作為 Template 的 text 值。這個特殊規則可以避免在一些情境下，需要不斷重複設定兩次訊息內容的問題。

quickReplies 欄位​

quickReplies 為所有 Template Type 皆有的欄位，表示一串讓使用者快速回覆的選項

template object 內含 quickReplies 範例:

{
  "type": "TEXT",
  "text": "聽起來你今天很需要找一間餐廳，有沒有什麼特別喜歡的菜系呢?",
  "quickReplies": [
    {
      "text": "📍我要找川菜"
    },
    {
      "text": "📍我要找粵菜"
    },
    {
      "text": "📍我要找台菜"
    }
  ]
}

Template Object 定義​

Template Object 有分為以下幾種 type ，分別代表常見的幾種訊息UI渲染方式：

  • TEXT : 純文字訊息。如果設計人員在 Asgard Push Message Processor 中沒有指定任何的 template type, 則預設template就會是 text type。
  • IMAGE : 帶圖的訊息
  • BUTTON : 帶一些可點擊的按鈕
  • CAROUSEL : 帶多個『圖＋文＋按鈕組』的橫向滾軸互動訊息
  • HINT : 一段置中的提示訊息
  • CHART : 產生一張圖表
備註

Quick Reply 為以上這幾種 type 的共有欄位，詳見 quickReplies 欄位

TEXT​

template object:

{
  "type": "TEXT",
  "text": "你好你好你好你好你好你好",
  "quickReplies": []
}
  • text : 純文字訊息內容

IMAGE​

template object:

{
  "type": "IMAGE",
  "originalContentUrl": "https://example.com/original.jpg",
  "previewImageUrl": "https://example.com/preview.jpg",
  "quickReplies": []
}
  • originalContentUrl : required
  • previewImageUrl : required

BUTTON​

template object

{
  "type": "BUTTON",
  "thumbnailImageUrl": "https://example.com/bot/images/image.jpg",
  "imageAspectRatio": "rectangle",
  "imageSize": "cover",
  "imageBackgroundColor": "#FFFFFF",
  "title": "Brown Cafe",
  "text": "Enjoy delicious food with a great atmosphere at our place.",
  "buttons": [
      {
        "label": "Reserve",
        "action": {
          "type": "message",
          "text": "Please reserve for me"
        }  
      },
      {
        "label": "Call",
        "action": {
          "type": "uri",
          "uri": "tel://+88623456789"
        }
      }
  ],
  "defaultAction": {
      "type": "uri",
      "uri": "https://store.com/"
  },
  "quickReplies": []
  
}
  • thumbnailImageUrl : optional
  • imageAspectRatio : (enum: rectangle , square )
    • rectangle: 1.51:1
    • square: 1:1
  • imageSize : (enum: cover , contain )
  • title : required
  • text : required
  • buttons : 選項按鈕的選項呈現與按下之後的動作
  • defaultAction : optional, 當 title or text or image 被按下後的動作，詳見 Action Object 定義。

template object:

{
  "type": "CAROUSEL",
  "columns": [
    {
      "thumbnailImageUrl": "https://example.com/bot/images/image.jpg",
      "imageAspectRatio": "rectangle",
      "imageSize": "cover",
      "imageBackgroundColor": "#FFFFFF",
      "title": "Brown Cafe",
      "text": "Enjoy delicious food with a great atmosphere at our place.",
      "buttons": [
        {
          "label": "Reserve",
          "action": {
            "type": "message",
            "text": "Please reserve for me"
          }
        },
        {
          "label": "Call",
          "action": {
            "type": "uri",
            "uri": "tel://+88623456789"
          }
        }
      ],
      "defaultAction": {
        "type": "uri",
        "uri": "https://store.com/"
      }
    }
  ],
  "quickReplies": []
}
  • columns : 旋轉項目清單。每個項目的內容如下 (其實同 BUTTON type):
    • thumbnailImageUrl : optional
    • imageAspectRatio : (enum: rectangle , square )
      • rectangle: 1.51:1
      • square: 1:1
    • imageSize : (enum: cover , contain )
    • title : required
    • text : required
    • buttons : 選項按鈕的選項呈現與按下之後的動作
    • defaultAction : optional, 當 title or text or image 被按下後的動作，詳見 Action Object 定義。

HINT​

template object

{
  "type": "HINT",
  "text": "已切換至台北欣欣秀泰",
  "quickReplies": []
}

CHART​

template object

{
  "type": "CHART",
  "title": "每月銷售額統計",
  "description": "以下是過去三個月的總銷售數據分析。",
  "chartOptions": [
    {
      "type": "bar",
      "title": "長條圖",
      "spec": {
        "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
        "data": {
          "values": [
            {"month": "Jan", "sales": 28},
            {"month": "Feb", "sales": 55},
            {"month": "Mar", "sales": 43}
          ]
        },
        "mark": "bar",
        "encoding": {
          "x": { "field": "month", "type": "ordinal" },
          "y": { "field": "sales", "type": "quantitative" }
        }
      }
    },
    {
      "type": "line",
      "title": "折線圖",
      "spec": {
        "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
        "data": {
          "values": [
            {"month": "Jan", "sales": 28},
            {"month": "Feb", "sales": 55},
            {"month": "Mar", "sales": 43}
          ]
        },
        "mark": "line",
        "encoding": {
          "x": { "field": "month", "type": "ordinal" },
          "y": { "field": "sales", "type": "quantitative" }
        }
      }
    },
    {
      "type": "pie",
      "title": "圓餅圖",
      "spec": {
        "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
        "data": {
          "values": [
            {"month": "Jan", "sales": 28},
            {"month": "Feb", "sales": 55},
            {"month": "Mar", "sales": 43}
          ]
        },
        "mark": { "type": "arc", "tooltip": true },
        "encoding": {
          "theta": { "field": "sales", "type": "quantitative" },
          "color": { "field": "month", "type": "nominal" }
        }
      }
    }
  ],
  "defaultChart": "bar",
  "quickReplies": [
  ]
}

Action Object 定義​

Action Object 表示使用者對互動元素(如按鈕)呈現以及進行互動時(如 Click) 的程式反應動作。Action Object有分為以下幾種 type :

  • MESSAGE : 相當於替使用者發出一句文字訊息來回應Bot。(與 quickReplies 欄位功能一樣)
  • URI : 相當於按下一個 uri 超連結

MESSAGE​

action object:

{
  "type": "MESSAGE",
  "text": "Please reserve Brown Cafe for me"
}
  • text : Required, 按下互動元素後，要替使用者發給 Bot 的文字。

URI​

action object:

{
  "type": "URI",
  "uri": "https://shop.com/sku/12345"
}
  • uri : Required, 按下互動元素後，要導向的URI位址。