Line Messaging API 的各種訊息格式

作了這麼多卡米狗的功能，只用到了少數幾個 Line Messaging API 訊息格式，還有很多都沒提到，就在這裡一次說明吧。

之前我們回應訊息的程式是這樣寫的：

  # 傳送訊息到 line
  def reply_to_line(reply_text)
    # 取得 reply token
    reply_token = params['events'][0]['replyToken']
    
    # 設定回覆訊息
    message = {
      type: 'text',
      text: reply_text
    } 

    # 傳送訊息
    line.reply_message(reply_token, message)
  end

在設定回覆訊息的部分，如果是文字訊息的話，是這樣寫：

message = {
  "type": "text",
  "text": "這裡是要回應的文字"
}

那麼傳送其他訊息的寫法呢？

傳送貼圖

message = {
  "type": "sticker",
  "packageId": "1",
  "stickerId": "1"
}

改成這樣就能傳送貼圖，只是 Line 有限制只能使用前4套，也就是說 packageId 的值必須在 1 到 4 之間。

傳送圖片

message = {
  "type": "image",
  "originalContentUrl": "圖片網址",
  "previewImageUrl": "縮圖網址"
}

接受 1MB 以下的 JPG 圖檔，網址必須是 https 開頭。

傳送影片

message = {
  "type": "video",
  "originalContentUrl": "影片網址",
  "previewImageUrl": "縮圖網址"
}

接受 1 分鐘以下 10MB 以下的 MP4 影片檔，網址必須是 https 開頭。

傳送聲音

message = {
  "type": "audio",
  "originalContentUrl": "聲音檔網址",
  "duration": 60000
}

接受 1 分鐘以下 10MB 以下的 M4A 聲音檔，網址必須是 https 開頭。duration 的值要填入聲音檔的長度，單位是毫秒(milliseconds)。

傳送地標

message = {
  "type": "location",
  "title": "第一行文字",
  "address": "第二行文字",
  "latitude": 35.65910807942215,
  "longitude": 139.70372892916203
}

顯示一個地標按鈕，title 是按鈕上的第一行文字，address 是第二行文字，address 可以是隨便打的字，不一定要是真的地址，只要經緯度值正確，按下按鈕後就能開啟對應經緯度的地圖。

傳送影像地圖(Imagemap)

message = {
  "type": "imagemap",
  "baseUrl": "圖片網址的一部分",
  "altText": "在不支援顯示影像地圖的地方顯示的文字",
  "baseSize": {
    "height": 1040,
    "width": 1040
  },
  "actions": [
    {
      "type": "uri",
      "linkUri": "https://www.kamigo.tw/",
      "label": "https://www.kamigo.tw/",
      "area": {
        "x": 0,
        "y": 0,
        "width": 520,
        "height": 1040
      }
    },
    {
      "type": "message",
      "text": "傳送文字",
      "area": {
        "x": 520,
        "y": 0,
        "width": 520,
        "height": 1040
      }
    }
  ]
}

baseUrl

baseUrl 的值要填入圖片網址，但 Line 會在取圖片時在網址後面加上 /240、/300、/460、/700、/1040，這是為了各種裝置需要的圖片尺寸不同所作的設計，圖片越小，讀取速度就可以越快。不過我們這邊也要製作各種大小的圖片，而且要配合他的網址，讓這些網址都能正確讀取到圖。如果要作到最完美的話，當然就是符合 Line 的規範來作，但是為了求方便，還是有取巧的方法可以用。

舉例來說，如果我們 baseUrl 填入的是 https://www.kamigo.tw/assets/kamigo-c3b10dff4cdb60fa447496b22edad6c32fffde96de20262efba690892e4461e8.png，當他在網址後面加上 /1040，變成 https://www.kamigo.tw/assets/kamigo-c3b10dff4cdb60fa447496b22edad6c32fffde96de20262efba690892e4461e8.png/1040 時，這個網址就打不開圖片了。為了避免這種情形，我們可以在網址的尾端加入 # 或 ?，變成這樣：https://www.kamigo.tw/assets/kamigo-c3b10dff4cdb60fa447496b22edad6c32fffde96de20262efba690892e4461e8.png#，因為網址上的 # 和 ? 是有特殊意義的，所以圖片就打得開了，所以我們可以拿任意的圖片網址後面加上 # 或 ? 來製作影像地圖。

接受 1MB 以下的圖片檔，可以是 JPG 或者 PNG，如果是 PNG 的話會有背景透明的效果，一樣要求 https 開頭的網址。

altText

altText 的文字會顯示在 Line 的聊天選單上，或推播訊息上。

baseSize

baseSize 是控制圖片顯示出來的大小。

actions

actions 用來控制圖片中各個區域被按下後要發生什麼事，這裡有兩種事情可以做，一種是點了之後開網頁，另一種是點了之後替用戶發訊息。

使用 "type": "uri" 來製作超連結：

{
  "type": "uri",
  "linkUri": "https://www.kamigo.tw/",
  "area": {
    "x": 0,
    "y": 0,
    "width": 520,
    "height": 1040
  }
}

linkUri 填入網址，area 指定點擊區域，以目前的設定的話是點擊圖片的左半邊。

使用 "type": "message" 來製作文字指令：

{
  "type": "message",
  "text": "傳送文字",
  "area": {
    "x": 520,
    "y": 0,
    "width": 520,
    "height": 1040
  }
}

當用戶點擊圖片的右半邊時，用戶會自動發出文字訊息，訊息內容為傳送文字。我們可以利用這個功能讓用戶說一句話，然後再根據這句話的內容，作我們想要作的事情。

目前在電腦版 Line 點擊 message 區塊會顯示「請至智慧手機上確認訊息內容。」字樣。

傳送樣板(Template)

樣板有四種，分別是 Confirm、Buttons、Carousel、Image carousel。

Confirm樣板

message = {
  "type": "template",
  "altText": "在不支援顯示樣板的地方顯示的文字",
  "template": {
    "type": "confirm",
    "text": "標題文字",
    "actions": [
      {
        "type": "message",
        "label": "第一個按鈕",
        "text": "1"
      },
      {
        "type": "message",
        "label": "第二個按鈕",
        "text": "2"
      }
    ]
  }
}

altText

目前在電腦版 Line 是完全沒辦法顯示樣板訊息的。

template-type

template type 目前有四種值可以填：confirm、buttons、carousel、image_carousel，不同的值代表使用不同的樣板。

actions

在 Confirm 樣板中，只能使用 2 個 action。

actions-type

action 目前也有四種，分別是 message、uri、postback、datetimepicker，我會先介紹四種樣板，然後再介紹這四種 action。

Buttons樣板

message = {
  "type": "template",
  "altText": "在不支援顯示樣板的地方顯示的文字",
  "template": {
    "type": "buttons",
    "text": "標題文字",
    "actions": [
      {
        "type": "message",
        "label": "第一個按鈕",
        "text": "1"
      }
    ]
  }
}

跟 Confirm 不同的地方在於，Buttons 可以做到只放一個按鈕。

message = {
  "type": "template",
  "altText": "在不支援顯示樣板的地方顯示的文字",
  "template": {
    "type": "buttons",
    "text": "標題文字",
    "actions": [
      {
        "type": "message",
        "label": "第一個按鈕",
        "text": "1"
      },
      {
        "type": "message",
        "label": "第二個按鈕",
        "text": "2"
      },
      {
        "type": "message",
        "label": "第三個按鈕",
        "text": "3"
      },
      {
        "type": "message",
        "label": "第四個按鈕",
        "text": "4"
      }
    ]
  }
}

Buttons 還可以做到放四個按鈕，不過 Buttons 的按鈕是直式的。

Buttons 不只是按鈕更加彈性，還可以放粗體標題和圖片。

長方形的圖片：

正方形的圖片：

message = {
  "type": "template",
  "altText": "在不支援顯示樣板的地方顯示的文字",
  "template": {
    "type": "buttons",
    "imageAspectRatio": "rectangle",
    "imageSize": "contain",
    "thumbnailImageUrl": "圖片網址",
    "imageBackgroundColor": "#a8e8fb",
    "title": "更粗的標題",
    "text": "標題文字",
    "defaultAction": {
      "type": "message",
      "label": "點到圖片或標題",
      "text": "0"
    },
    "actions": [
      {
        "type": "message",
        "label": "第一個按鈕",
        "text": "1"
      },
      {
        "type": "message",
        "label": "第二個按鈕",
        "text": "2"
      },
      {
        "type": "message",
        "label": "第三個按鈕",
        "text": "3"
      },
      {
        "type": "message",
        "label": "第四個按鈕",
        "text": "4"
      }
    ]
  }
}

thumbnailImageUrl

接受 1MB 以下的圖片檔，可以是 JPG 或者 PNG，如果是 PNG 的話會有背景透明的效果，一樣要求 https 開頭的網址。

imageAspectRatio

控制圖片顯示為長方形或正方形，有兩種值，分別為 rectangle 代表長方形，square 代表正方形。長方形的圖片長寬比為 1.51:1。

imageSize

控制圖片長寬比與顯示比例不合時應該填滿顯示範圍還是完整顯示圖片，有兩種值，分別為 cover 代表填滿顯示範圍，contain 代表完整顯示圖片，如果是完整顯示圖片的話，周圍就有可能產生留白。

imageBackgroundColor

背景色，當圖片留白或者圖片本身有透明部分，就會看見背景色，預設為白色。

title

粗體的標題文字

defaultAction

當點擊到圖片或文字時就會觸發的 action。

Carousel樣板

message = {
  "type": "template",
  "altText": "在不支援顯示樣板的地方顯示的文字",
  "template": {
    "type": "carousel",
    "columns": [
      {
        "text": "第一組標題",
        "actions": [
          {
            "type": "message",
            "label": "第一個按鈕",
            "text": "1"
          }
        ]
      },
      {
        "text": "第二組標題",
        "actions": [
          {
            "type": "message",
            "label": "第一個按鈕",
            "text": "1"
          }
        ]
      }
    ]
  }
}

columns

其實跟 Buttons 差不多，把部分內容搬移到 columns 然後多放幾個，就可以作出 Carousel 了。
最多可以放 10 個 column，也可以只放一個 column，只放一個就跟 Buttons 幾乎一樣了，唯一不同的地方是 Carousel 的按鈕最多只能放 3 個。

這邊要注意每個 column 的 actions 的數量必須相同。

message = {
  "type": "template",
  "altText": "在不支援顯示樣板的地方顯示的文字",
  "template": {
    "type": "carousel",
    "imageAspectRatio": "rectangle",
    "imageSize": "contain",
    "columns": [
      {
        "thumbnailImageUrl": "圖片網址",
        "imageBackgroundColor": "#a8e8fb",
        "title": "更粗的標題",
        "text": "第一組標題",
        "defaultAction": {
          "type": "message",
          "label": "點到圖片或標題",
          "text": "0"
        },
        "actions": [
          {
            "type": "message",
            "label": "第一個按鈕",
            "text": "1"
          },
          {
            "type": "message",
            "label": "第二個按鈕",
            "text": "2"
          },
          {
            "type": "message",
            "label": "第三個按鈕",
            "text": "3"
          }
        ]
      },
      {
        "thumbnailImageUrl": "圖片網址",
        "imageBackgroundColor": "#a8e8fb",
        "title": "更粗的標題",
        "text": "第二組標題",
        "defaultAction": {
          "type": "message",
          "label": "點到圖片或標題",
          "text": "0"
        },
        "actions": [
          {
            "type": "message",
            "label": "第一個按鈕",
            "text": "1"
          },
          {
            "type": "message",
            "label": "第二個按鈕",
            "text": "2"
          },
          {
            "type": "message",
            "label": "第三個按鈕",
            "text": "3"
          }
        ]
      }
    ]
  }
}

跟 Buttons 一樣可以放圖片，這邊要注意的是，如果要放圖片，那麼所有的 column 都要放圖片才行。

Image Carousel樣板

message = {
  "type": "template",
  "altText": "在不支援顯示樣板的地方顯示的文字",
  "template": {
    "type": "image_carousel",
    "columns": [
      {
        "imageUrl": "圖片網址",
        "action": {
          "type": "message",
          "label": "第一張圖",
          "text": "1"
        }
      },
      {
        "imageUrl": "圖片網址",
        "action": {
          "type": "message",
          "label": "第二張圖",
          "text": "2"
        }
      }
    ]
  }
}

跟 Carousel 比起來，這個其實還蠻單純的，他的圖片只能是正方形。不過他的 action label 是選填的，不填就不會顯示文字在圖片上。

樣板行為(Template Action)

action 目前有四種，分別是 message、uri、postback、datetimepicker，以下一個個介紹。

message

讓用戶點擊按鈕後傳送訊息。

{  
  "type":"message",
  "label":"按鈕顯示的文字",
  "text":"讓用戶傳送的文字"
}

uri

讓用戶點擊按鈕後開啟網頁。

{  
  "type":"uri",
  "label":"按鈕顯示的文字",
  "uri":"網址"
}

postback

讓用戶點擊按鈕後偷偷傳回訊息，不讓其他人發現。

{  
  "type":"postback",
  "label":"按鈕顯示的文字",
  "data":"偷偷傳回的訊息"
}

基於某種原因，你不想讓用戶看見訊息，所以不使用 message action，改用 postback，一個可能的原因是你想傳遞 json 之類的結構化資訊，或者是你想要作匿名投票。

datetimepicker

{  
  "type":"datetimepicker",
  "label":"按鈕顯示的文字",
  "data":"偷偷傳回的訊息",
  "mode":"datetime",
  "initial":"2017-12-25t00:00",
  "max":"2018-01-24t23:59",
  "min":"2017-12-25t00:00"
}

跟 postback 差不多，不過在點擊按鈕後會跳出一個日期時間選擇畫面。

在用戶點擊傳送之後，我們會收到一個 postback 事件，data 一個長這樣的 json：

{
  "data": "偷偷傳回的訊息",
  "params": {
    "datetime":"2018-03-22T05:28"
  }
}

mode

有三種值，date 選擇日期，time 選擇時間，datetime 選擇日期加時間。

initial

選填，可以控制一開始顯示時的預設日期時間。

max、min

選填，用來限制日期時間能選擇的範圍。