# 用戶資料

## 取得用戶資料

在您的伺服器呼叫 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
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.botbonnie.com/jiao-xue-fan-li/user-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.