> 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/user-data.md).

# 用戶資料

## 取得用戶資料

在您的伺服器呼叫 BotBonnie 用戶資料 API：

```
GET https://api.botbonnie.com/v1/api/bot/customers
```

### **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) ？

### **Query parameters**

| Name      | Description                                                                               | Required |
| --------- | ----------------------------------------------------------------------------------------- | -------- |
| **botId** | 機器人 ID                                                                                    | o        |
| **limit** | 單次呼叫欲截取的筆數 \[1-3086]                                                                      | o        |
| **from**  | 13 碼的 timestamp，抓取「最後互動時間」在這個 timestamp 之後的用戶（如果沒有帶則沒有限制）                                 | x        |
| **next**  | 截取下一頁用的 key，從前一頁的 [Res 物件](/jiao-xue-fan-li/user-data.md#res-wu-jian) 中取得（如果沒有帶則會回第一頁的資料） | x        |

### **Response body**

| Name       | Type   | Description                                                     |
| ---------- | ------ | --------------------------------------------------------------- |
| **res**    | Object | 用戶 ID，見 [**Res 物件**](/jiao-xue-fan-li/user-data.md#res-wu-jian) |
| **status** | Number | HTTP Status                                                     |

#### Res 物件

| Name        | Type           | Description                                                             |
| ----------- | -------------- | ----------------------------------------------------------------------- |
| **records** | Array\[Record] | 所有用戶的資料，見 [**Record 物件**](/jiao-xue-fan-li/user-data.md#record-wu-jian) |
| **next**    | String         | 截取下一頁所需的 key                                                            |

#### Record 物件

| Name           | Type          | Description                                                             |
| -------------- | ------------- | ----------------------------------------------------------------------- |
| **id**         | String        | 用戶的 LINE / FB Messenger ID                                              |
| **name**       | String        | 用戶的姓名                                                                   |
| **platform**   | String        | 值為 FB / LINE                                                            |
| **pageId**     | String        | FB 粉專或 LINE 官方帳號 ID                                                     |
| **status**     | Number        | 用戶的狀態，值的定義分別為  1: 運行中  2: 暫停中  3: 已停止  4: 被封鎖  5:主動封鎖                   |
| **created**    | Number        | 初次互動時間，為 13 碼的 timestamp                                                |
| **lastActive** | Number        | 上次互動時間，為 13 碼的 timestamp                                                |
| **pic**        | String        | 大頭照的連結                                                                  |
| **tags**       | Array\[Tag]   | 用戶身上的標籤列表，見 [**Tag 物件**](/jiao-xue-fan-li/user-data.md#tag-wu-jian)     |
| **params**     | Array\[Param] | 用戶身上的參數列表，見 [**Param 物件**](/jiao-xue-fan-li/user-data.md#param-wu-jian) |
| **email**      | String        | 用戶的個人信箱                                                                 |
| **gender**     | String        | 用戶的性別，男 / 女                                                             |
| **birthday**   | String        | 用戶的生日，YYYY-MM-DD 的格式                                                   |
| **phone**      | String        | 用戶的電話                                                                   |
| **extId**      | String        | 帳號綁定完取得的 ID                                                             |

#### Tag 物件

| Name          | Type   | Description                    |
| ------------- | ------ | ------------------------------ |
| **id**        | String | 標籤 ID                          |
| **name**      | String | 標籤名稱                           |
| **timestamp** | Number | 最後一次被貼上此標籤的時間，為 13 碼 timestamp |
| **count**     | Number | 被貼上此標籤的次數                      |

#### Param 物件

| Name          | Type   | Description                |
| ------------- | ------ | -------------------------- |
| **name**      | String | 參數名稱                       |
| **value**     | String | 參數值                        |
| **timestamp** | Number | 此參數被設定的時間，為 13 碼 timestamp |

### 範例

#### 取得第一頁

**Request**

```
GET https://api.botbonnie.com/v1/api/bot/customers?botId=bot-n3WIChboi&limit=1
```

**Response body**

```javascript
{
    "res": {
        "records": [
            {
                "id": "",
                "name": "陳邦尼",
                "platform": "FB",
                "pageId": "",
                "status": 1,
                "created": 1576728847151,
                "lastActive": 1598512257867,
                "params": [
                    {
                        "name": "birthday",
                        "value": "2020-06-02",
                        "timestamp": 1594897339883
                    },
                    {
                        "name": "location",
                        "value": "???",
                        "timestamp": 1594897345660
                    },
                    {
                        "name": "phone",
                        "value": "0999999999",
                        "timestamp": 1594897335025
                    }
                ],
                "birthday": "1999-09-09",
                "email": "",
                "phone": "0900123456",
                "tags": [],
                "pic": ""
            }
        ],
        "next": "895c79bac725e96ab2dc3ed8a7162909b7dc974323125e32fbfb1bd7b8711ea84ebf41e152ddd3fae7b34161fde046ea47382164336abb151369071ba926729d2a6d6927e18182dff7da0513bb81506b0c641fc8c175f224896664de912b1ac9cc0e7bfa3a6f30"
        // 用來取得第二頁的 key
    },
    "status": 200
}
```

#### 取得第二頁

**Request**

```
GET https://api.botbonnie.com/v1/api/bot/customers?botId=bot-n3WIChboi&limit=1&next=895c79bac725e96ab2dc3ed8a7162909b7dc974323125e32fbfb1bd7b8711ea84ebf41e152ddd3fae7b34161fde046ea47382164336abb151369071ba926729d2a6d6927e18182dff7da0513bb81506b0c641fc8c175f224896664de912b1ac9cc0e7bfa3a6f30
```

**Response body**

```javascript
{
    "res": {
        "records": [
            {
                "id": "",
                "name": "孫邦尼",
                "platform": "FB",
                "pageId": "",
                "status": 1,
                "created": 1579664574373,
                "lastActive": 1596705419231,
                "params": [],
                "tags": [
                    {
                        "id": "",
                        "name": "推播",
                        "timestamp": 1584502439638,
                        "count": 2
                    }
                ],
                "pic": ""
            }
        ],
        "next": "895c79bac725e96ab2dc3ed8a7162909b7d2954224145a3cf1fe1dd7b8711ea84ebf41ed50dad3fbefba4460f5e640ef4d3a2164336abb151369071ba926729d2a6d6927e18182dff7da0513bb81506b0c641fc8c175f224896664de912b1ac9cc0e7bfa3a6f30"
    },
    "status": 200
}
```