# 用戶訊息

## 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"
}
```


---

# 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-message-history.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.