> For the complete documentation index, see [llms.txt](https://docs.botbonnie.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.botbonnie.com/jiao-xue-fan-li/zhang-hao-bang-ding.md).

# 帳號綁定

## 1. 何謂綁定帳號？

綁定帳號可將 BotBonnie 中的用戶 ID 與企業用戶 ID 綁定，用戶綁定完成之後，企業可以藉由 JSON API 識別對話中的用戶是企業資料庫中的哪一名註冊用戶，進而提供個人化的服務。

BotBonnie 提供進階套件 **帳號綁定**，並在套件中預設之 **開始綁定** 模組設定有 **登入** 按鈕。藉由在對話視窗中登入企業會員帳號，即可將 BotBonnie 之 **userId** 與企業用戶 ID 綁定。

### 1.1 「登入」按鈕設定

請於 BotBonnie 後台設定綁定帳號的按鈕，並填入基本的設定。

| 設定名稱       | 類型  | 描述                                            |
| ---------- | --- | --------------------------------------------- |
| **登入轉址網址** | URL | 企業登入網頁網址，當用戶點擊 **登入** 時會以 webview 形式在對話介面中開啟。 |

### 1.2  網址參數

當用戶按下 **登入** 按鈕時，用戶會在訊息視窗內開啟您的登入網址，BotBonnie 會根據 LINE / Messenger 添加網址參數。

#### **LINE 網址參數(query string)**：

| Name          | Type   | Description                                                                          |
| ------------- | ------ | ------------------------------------------------------------------------------------ |
| **userId**    | String | 用戶 ID                                                                                |
| **pageId**    | String | LINE OA ID                                                                           |
| **carry**     | String | BotBonnie 用來判斷往後流程的參數(僅用於 **BotBonnie Redirect**)                                    |
| **linkToken** | String | LINE 產生之 **一次性** 驗證權杖，每個帳號綁定按鈕只可綁定(點擊)一次, 有效時間 **10** 分鐘(僅用於 **BotBonnie Redirect**) |

#### **Messenger 網址參數(query string)**：

| Name                        | Type   | Description                                                 |
| --------------------------- | ------ | ----------------------------------------------------------- |
| **userId**                  | String | 用戶 ID                                                       |
| **pageId**                  | String | FB 粉專 ID                                                    |
| **carry**                   | String | BotBonnie 用來判斷往後流程的參數(僅用於 **BotBonnie Redirect**)           |
| **redirect\_uri**           | String | Messenger 指定綁定完成後需重導向之網址(僅用於 **BotBonnie Redirect**)        |
| **account\_linking\_token** | String | Messenger 產生之短期權杖，有效時間 **5** 分鐘(僅用於 **BotBonnie Redirect**) |

記得將 **userId** 存入您的資料庫內，爾後的個人化服務可依此資料做用戶識別。

## 2. 處理「綁定帳號成功」

### 2.1. 網址重新導向

當用戶綁定（登入）成功時，建議您提供一個頁面告知用戶已登入成功，並重導向至 **BotBonnie Redirect**, 重導向時須根據 LINE / Messenger 平台帶入網址參數, BotBonnie 會依據平台幫用戶重新導向。

**BotBonnie Redirect**:

```
https://rd.botbonnie.com/account/link?{query}
```

#### **帶入 LINE 網址參數(query string)**：

| Name          | Type                            | Description                                                                                                                                                                     | Required |
| ------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| **carry**     | String                          | BotBonnie 用來判斷往後流程的參數                                                                                                                                                           | o        |
| **linkToken** | String                          | LINE 產生之 **一次性** 驗證權杖，每個帳號綁定按鈕只可綁定(點擊)一次, 有效期間 **10** 分鐘                                                                                                                        | o        |
| **nonce**     | String ( 10 \~ 255 characters ) | 使用用戶在企業內之相對應 ID 產生之[不重複字串](https://developers.line.biz/en/docs/messaging-api/linking-accounts/#verifying-user-id)，ex: 使用 secure random function 產生 128 bytes 之隨機碼並轉換成 base64 字串 | o        |

#### **帶入 Messenger 網址參數(query string)**：

| Name                        | Type   | Description                     | Required |
| --------------------------- | ------ | ------------------------------- | -------- |
| **carry**                   | String | BotBonnie 用來判斷往後流程的參數           | o        |
| **redirect\_uri**           | String | Messenger 指定綁定完成後需重導向之網址        | o        |
| **account\_linking\_token** | String | Messenger 產生之短期權杖，有效時間 **5** 分鐘 | o        |
| **authorization\_code**     | String | 企業用戶 ID                         | o        |

## 3. 處理「解除綁定帳號成功」

有兩種情況會使 BotBonnie 與用戶的帳號解除綁定，第一種是用戶主動在對話式介面中點擊解除綁定帳號按鈕，第二種是企業主動透過 API 方式通知 BotBonnie 解除與用戶的帳號綁定關係。

### 3.1 企業主動解除與用戶的帳號綁定

企業也可以主動解除與用戶的帳號綁定，請呼叫 BotBonnie API，通知我們進行以下動作：

1. 解除用戶帳號綁定狀態
2. 觸發動作

在您的伺服器呼叫 BotBonnie API ：

```
POST https://api.botbonnie.com/v1/api/accountLink/unlink
```

#### **Request headers**

| Name              | Description          |
| ----------------- | -------------------- |
| **Content-Type**  | application/json     |
| **Authorization** | Bearer `{API Token}` |

* [如何取得 `API Token`](/chang-jian-wen-ti/ru-he-qu-de-api-token.md) ？

#### **Request body**

| Name              | Type   | Description                     | Required |
| ----------------- | ------ | ------------------------------- | -------- |
| **bot\_id**       | String | 機器人的 ID                         | o        |
| **bot\_raw\_uid** | String | 用戶 ID (請帶入網址參數中相對應之 **userId**) | o        |
| **bot\_pid**      | String | 粉絲頁 ID                          | o        |
| **bot\_channel**  | Number | 渠道代號   `0`：Facebook `1`：LINE    | o        |
| **actions**       | Array  | 觸發動作                            | x        |

#### **actions：**

* 儲存用戶參數

  ```
  {
    "type": "saveParams",
    "name": "age",
    "value": "18"
  }
  ```
* 新增標籤

  ```
  {
    "type": "addTag",
    "value": "tag-4VW8DDgwu", // 請至 BotBonnie 後台設定標籤後，再帶入相對應之 tag ID
  }
  ```
* 移除標籤

  ```
  {
    "type": "removeTag",
    "value": "tag-4VW8DDgwu", // 請至 BotBonnie 後台設定標籤後，再帶入相對應之 tag ID
  }
  ```
* 通知專員

  ```
  {
    "type": "notifyAgent",
    "message": "用戶已解除綁定" // OPTIONAL
  }
  ```

## 4. 提供個人化服務

### 4.1. 準備個人化服務 API

BotBonnie 在呼叫您的個人化服務 API 時，會在 Request Body 內攜帶 **用戶識別資料**，並在 Request Header 攜帶 `X-Hub-Signature` 確保來源安全性，而您的個人化服務 API 需回傳 BotBonnie 特定訊息 JSON 格式。

詳細使用方法可參考[如何使用 JSON 訊息](/jiao-xue-fan-li/ru-he-shi-yong-json-xun-xi.md)。

### 4.2. 放置個人化服務按鈕

在對話腳本內，放置個人化服務按鈕，連結至含有「JSON 訊息（JSON API）」的模組，並將您的個人化服務 API 網址填上即可。