如何使用 JSON 訊息?

BotBonnie 提供特殊的JSON 訊息格式,可以利用此種訊息格式,串接您的服務,由您的伺服器動態提供不同的訊息內容。僅需提供您的 JSON API URL,在呼叫您的 API 時,BotBonnie 會自動帶入以下資料:

  • 在 Request Body 帶入用戶識別資料

  • 在 Request Header 帶入 X-Hub-Signature 做安全性驗證

而您的 API 需回傳 BotBonnie 特定訊息 JSON 格式。

1. JSON 訊息範例

2. 用戶識別資料

BotBonnie 會在 Request POST body 自動帶入用戶識別資料,可搭配帳號串接使用。

參數名稱

類型

描述

bot_id

String

機器人的 ID

bot_uid

(deprecated)

String

用戶 ID (加密)

bot_raw_uid

String

用戶 ID (未加密)

bot_pid

String

粉絲頁 ID

bot_channel

Number

渠道代號 (0:Facebook / 1:LINE)

bot_isLinked

(deprecated)

Boolean

用戶目前是否已經帳號連結 (true / false

3. 取得額外資料

當您的 JSON API 需要使用者的相關資料時,可以在 JSON API 網址中加上相關參數,BotBonnie 會在 Request POST body 中將相關的資訊一併傳送至您的伺服器。

https://yourdomian.com?fields=user,userParams

您可以在 JSON API URL 上攜帶額外網址參數來獲取 BotBonnie 提供的額外資訊。 目前支援的網址參數類型如下:

參數名稱

類型

支援的種類

fields

String

user: 提供當下的用戶資料 user_params: 提供儲存於 BotBonnie 端的自訂用戶參數

範例的 Body 如下:

{
"bot_id": "bot-xxxxx",
"bot_uid": "3xxxxxxxxxxxd",
"bot_raw_uid": "2xxxxxxxxxxxx0",
"bot_pid": "1234779123812",
"bot_channel": 0,
"bot_isLinked": true,
"user": {
"id": "3xxxxxxxxxxxd",
"rawId": "2xxxxxxxxxxxx0",
"created": 1505360797321,
"name": "陳邦妮",
"gender": "female",
"last_name": "陳",
"pic": "https://scontent.xx.fbcdn.net/v/t31.0-1/p960x960/1800025_10202073294786135_45024857_o.jpg?oh=85252db7049dbf99de251175d03a6d46&oe=5A604B50",
"locale": "zh_TW",
"first_name": "邦妮",
"timezone": 8
},
"userParams": {
"input": "你好",
...
}
...
}

user

所有與用戶相關的資訊

鍵值

數值

必定存在

id

BotBonnie 認定之用戶 ID (加密) ex: 3e69e881732e38b290e39a28b87403bd

o

rawId

BotBonnie 認定之用戶 ID (未加密) ex: 2452158751517100

o

created

BotBonnie 建立此用戶的時間,unixtime 以毫秒表示 ex: 1505360797321

o

name

用戶全名 ex: 陳邦妮

last_name

用戶姓氏 ex:

first_name

用戶名稱 ex: 邦妮

gender

用戶性別 male or female

pic

用戶大頭照網址

locale

用戶所在地區 ex: zh_TW

timezone

用戶時區 ex: 8

userParams

企業儲存於用戶身上額外的參數

鍵值

數值

必定存在

input

觸發此 JsonAPI 的用戶輸入

4. 來源安全性驗證

BotBonnie 會在 Request Header 帶入 X-Hub-Signature 確保來源安全性。

X-Hub-Signature 是為了驗證 POST 請求是來自 BotBonnie 伺服器,而不是來自惡意用戶。我們使用 SHA1 將 API Secret 與原始請求做雜湊,您可以在您的伺服器做來源驗證。

4.1 如何取得 API Secret

BotBonnie 提供每個 bot 專屬的 API Secert。可進入 bot 主控台,點選「設定 > 進階設定」,即可取得此 bot 的 API Secert

4.2 如何驗證 X-Hub-Signature

假設您有一個基本的伺服器監聽 webhooks 。

var express = require('express')
var bodyParser = require('body-parser')
var crypto = require('crypto')
// Express error-handling middleware function.
// Read more: http://expressjs.com/en/guide/error-handling.html
function abortOnError(err, req, res, next) {
if (err) {
console.log(err)
res.status(400).send({ error: "Invalid signature." })
} else {
next()
}
}
var app = express();
var listener = app.listen(process.env.PORT ? process.env.PORT : 3000)
// body-parser is the first Express middleware.
app.use(bodyParser.json({ verify: verifyRequest }))
// Add an error-handling Express middleware function
// to prevent returning sensitive information.
app.use(abortOnError)
app.post('/webhook/', function (req, res) {
res.status(200).send("done!")
})

使用 API Secret 與原始請求做驗證。

// Calculate the X-Hub-Signature header value.
function getSignature(buf) {
var hmac = crypto.createHmac("sha1", process.env.BOTBONNIE_API_SECRET)
hmac.update(buf, "utf-8")
return "sha1=" + hmac.digest("hex")
}
// Verify function compatible with body-parser to retrieve the request payload.
// Read more: https://github.com/expressjs/body-parser#verify
function verifyRequest(req, res, buf, encoding) {
var expected = req.headers['x-hub-signature']
var calculated = getSignature(buf)
console.log("X-Hub-Signature:", expected, "Content:", "-" + buf.toString('utf8') + "-")
if (expected !== calculated) {
throw new Error("Invalid signature.")
} else {
console.log("Valid signature!")
}
}