> 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-message-history.md).

# 用戶訊息

## Get Message history

<mark style="color:blue;">`GET`</mark> `https://api.botbonnie.com/v1/api/message/history`

#### Query Parameters

| Name     | Type    | Description                          |
| -------- | ------- | ------------------------------------ |
| botId    | string  | 機器人 ID                               |
| pageId   | string  | 粉專 ID                                |
| platform | integer | 粉專平台 facebook 填 0, line 填 1          |
| userId   | string  | 欲查詢的使用者ID                            |
| from     | integer | 13 碼 timestamp 預設為 0                 |
| to       | integer | 13 碼 timestamp 預設為 current timestamp |
| limit    | integer | 回傳的訊息筆數，最大 100，預設 100                |
| desc     | boolean | true 為以時間做降冪排序，預設為 true              |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer `{API Token}` |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{
    "res": {
        "messages": [
            {
                "category": "conversation",
                "type": "reply",
                "data": {
                    "quickReplies": [],
                    "text": "文字內容",
                    "type": "text"
                },
                "timestamp": 1623918332624,
                "mid": "0_29612160-1bd1-4358-aee7-9a0ff605cae6"
            },
            {
                "category": "conversation",
                "type": "click",
                "timestamp": 1623918331847,
                "senderId": "xxxxxx",
                "data": {
                    "type": "click",
                    "title": "快速回覆"
                }
            }
        ],
        "desc": true
    },
    "status": 200
}
```

{% endtab %}
{% endtabs %}

{% content-ref url="/pages/-LB5E-0YYIeQoHCeUJy4" %}
[如何取得 API Token？](/chang-jian-wen-ti/ru-he-qu-de-api-token.md)
{% endcontent-ref %}

### **Response body**

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

#### Res 物件

| Name         | Type            | Description                                                                         |
| ------------ | --------------- | ----------------------------------------------------------------------------------- |
| **messages** | Array\[Message] | 用戶訊息資料，見[ Message **物件**](/jiao-xue-fan-li/user-message-history.md#message-wu-jian) |
| **desc**     | Boolean         | 是否為降冪排序                                                                             |

#### Message 物件

| Name           | Type    | Description                                                            |
| -------------- | ------- | ---------------------------------------------------------------------- |
| **category**   | String  | 紀錄分類                                                                   |
| **type**       | String  | 紀錄類型                                                                   |
| **data**       | Object  | 訊息內容， [Data 物件](/jiao-xue-fan-li/user-message-history.md#data-wu-jian) |
| **timestamp**  | Integer | 紀錄發生時間，13 碼 timestamp                                                  |
| **operatorId** | Number  | 回覆的操作者  ID，只有在後台即時訊息單獨回覆使用者時才會存在                                       |
| **senderId**   | Number  | 使用者 ID                                                                 |

#### Data 物件

| Name             | Type               | Description                                                                          |
| ---------------- | ------------------ | ------------------------------------------------------------------------------------ |
| **type**         | String             | 訊息類型                                                                                 |
| **text**         | String             | 訊息文字                                                                                 |
| **payload**      | String             | 訊息內容                                                                                 |
| **quickReplies** | Array\[quickReply] | 快速回復按鈕， [QuickReply 物件](/jiao-xue-fan-li/user-message-history.md#quickreply-wu-jian) |
| **buttons**      | Array\[button]     | 按鈕列表，[Button 物件](/jiao-xue-fan-li/user-message-history.md#button-wu-jian)            |
| **link**         | String             | url                                                                                  |
| **cards**        | Array\[card]       | 輪播卡片，[ Card 物件](/jiao-xue-fan-li/user-message-history.md#card-wu-jian)               |

#### QuickReply 物件

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| **title** | String | 按鈕文字        |
| **type**  | String | 按鈕類型        |

#### Button 物件

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| **title** | String | 按鈕文字        |
| **type**  | String | 按鈕類型        |

#### Card 物件

| Name                   | Type           | Description                                                                |
| ---------------------- | -------------- | -------------------------------------------------------------------------- |
| **title**              | String         | 標題                                                                         |
| **subtitle**           | String         | 描述文字                                                                       |
| **imageUrl**           | String         | 圖片網址                                                                       |
| **imageClickShortUrl** | String         | 圖片點擊的縮址 url                                                                |
| **imageClickOrignUrl** | String         | 圖片點擊設定的 url                                                                |
| **buttons**            | Array\[button] | 按鈕列表，[ Button 物件](/jiao-xue-fan-li/user-message-history.md#button-wu-jian) |

### 範例 Message object 訊息

使用者行為的紀錄類別包含 click, text, image, video, audio, file, sticker, follow, unfollow, open\_url&#x20;

reply 則為機器人回覆紀錄，push 為推播紀錄

reply/push 會包含的訊息種類有 text, image, video, audio, gallery (輪播訊息), imagemap (圖文訊息)

#### click Type

為使用者點擊按鈕時產生的事件紀錄

```
{
    "category": "conversation",
    "type": "click",
    "timestamp": 1623046482461,
    "senderId": "xxxxxxx",
    "data": {
        "type": "click",
        "title": "被點擊的按鈕文字"
    }
}
```

#### text Type

使用者發送文字訊息時的事件紀錄

```
{
    "category": "conversation",
    "type": "text",
    "timestamp": 1623907684961,
    "senderId": "xxxxxxx",
    "data": {
        "type": "text",
        "payload": "使用者輸入的文字"
    }
}
```

#### image/video/audio/file Type

使用者傳送圖片影片音訊檔案的類型的訊息時的事件紀錄

```
{
    "category": "conversation",
    "type": "audio/video/image/file",
    "timestamp": 1623907089811,
    "senderId": "xxxxxx",
    "data": {
        "type": "audio/video/image/file",
        "payload": "xxxxxx" // content message id
    },
    "mid": "14239393100682"
}
```

#### sticker Type

使用者傳送貼圖訊息時的事件紀錄

```
{
    "category": "conversation",
    "type": "sticker",
    "timestamp": 1615965080838,
    "senderId": "xxxxxx",
    "data": {
        "type": "sticker",
        "payload": {
            "packageId": "xxxx",
            "stickerId": "xxxxxx"
        }
    }
}
```

#### follow/unfollow Type

使用者追蹤官方帳號或封鎖時的事件紀錄

```
{
    "category": "system",
    "type": "follow/unfollow",
    "timestamp": 1622626402433
}
```

#### open\_url Type

使用者開啟 url 時的事件紀錄&#x20;

```
{
    "category": "system",
    "type": "open_url",
    "timestamp": 1620206520431,
    "data": {
        "type": "open_url",
        "link": "https://www.botbonnie.com"
    }
}
```

#### Reply/Push Type with data of text type

回覆文字訊息的紀錄

```
{
    "category": "conversation",
    "type": "reply/push",
    "data": {
        "quickReplies": [
            {
                "title": "快速回覆",
                "type": "text",
                "payload": "{\"fm\":\"module-xxxxxx\",\"to\":\"module-xxxxx\",\"id\":\"qr_0\",\"bid\":\"bot-xxxxxxx\",\"bv\":\"PROD\",\"ti\":\"快速回覆\"}"
            }
        ],
        "type": "text",
        "text": "文字訊息內容"
    },
    "timestamp": 1622198735278,
    "mid": "0_0_92d674b9-cdd0-4357-a8de-dd6b58d9b021",
    "operatorId": "xxxxxxx"
}
```

#### Reply/Push Type with data of  image/video/audio type

回覆影像/影片/音訊的訊息紀錄

```
{
    "category": "conversation",
    "type": "reply",
    "data": {
        "type": "video",
        "videoUrl": "https://xxxxxxx", // exist in video
        "imageUrl": "https://xxxxxxx", // exist in image
        "audioUrl": "https://xxxxxxx"  // exist in audio
    },
    "timestamp": 1623907690653,
    "mid": "3_3_857803a6-de80-4def-a2e3-56134db79b1f"
}
```

#### Reply/Push Type with data of imagemap type

回覆圖文訊息的紀錄

```
{
    "category": "conversation",
    "type": "reply",
    "data": {
        "baseUrl": "https://xxxxx", //image
        "quickReplies": [],
        "buttons": [
            {
                "area": {
                    "x": 0,
                    "width": 1040,
                    "y": 0,
                    "height": 1040
                },
                "type": "web_url",
                "value": "https://xxxxxx",
                "shortUrl": "https://xxxxxxxxxxx",
                "originUrl": "https://xxxxxxxx"
            }
        ],
        "size": {
            "width": 1040,
            "height": 1040
        },
        "text": "圖文訊息",
        "type": "imagemap"
    },
    "timestamp": 1623915747419,
    "mid": "4_4_00a3323f-4a1e-4d3a-a8ec-593969091c4a"
}
```

#### Reply/Push Type with data of gallery type

回覆輪播訊息的紀錄

```
{
    "category": "conversation",
    "type": "reply",
    "data": {
        "cards": [
            {
                "imageClickShortUrl": "https://xxxxxx",
                "buttons": [],
                "imageClickUrl": "https://xxxxxx",
                "subtitle": "描述",
                "imageUrl": "https://xxxxx",
                "title": "卡片 1 標題",
                "imageClickOriginUrl": "https://xxxxxx"
            },
            {
                "imageClickShortUrl": "https://xxxxxx",
                "buttons": [],
                "imageClickUrl": "https://xxxxxx",
                "subtitle": "描述",
                "imageUrl": "https://xxxxx",
                "title": "卡片 2 標題",
                "imageClickOriginUrl": "https://xxxxxx"
            }
        ],
        "type": "gallery",
        "imageStyle": "horizontal"
    },
    "timestamp": 1623907690652,
    "mid": "2_2_857803a6-de80-4def-a2e3-56134db79b1f"
}
```