# การส่งออกสถิติข้อความแบบอะซิงโครนัส

`exportMessagesStatistics` จะส่งออกประวัติและสถิติข้อความไปยังไฟล์ CSV บนเซิร์ฟเวอร์ ใช้สำหรับดึงข้อมูลขนาดใหญ่หรือข้อมูลทั้งบัญชีซึ่ง [`messages:list`](/th/developer/api-reference/statistics-api/message-statistics-api/#messageslist) ไม่สามารถจัดการได้

## ควรใช้ export แทน messages:list เมื่อใด

ใช้ `messages:list` สำหรับการค้นหาแบบสดและแบ่งหน้าในช่วงเวลาที่จำกัด ใช้ `exportMessagesStatistics` เมื่อผลลัพธ์มีขนาดเกินขีดจำกัดการแบ่งหน้าของ `messages:list` (`page × per_page > 100000`) หรือเมื่อเป้าหมายคือไฟล์เดียวที่สามารถดาวน์โหลดได้แทนที่จะเป็น JSON แบบแบ่งหน้า การส่งออกไม่มีข้อจำกัดเกี่ยวกับ `date_range` หรือจำนวนแถว เนื่องจากจะสตรีมผลลัพธ์ไปยังไฟล์บนดิสก์แทนที่จะเก็บไว้ในการตอบกลับครั้งเดียว

## ขั้นตอนการส่งออกทำงานอย่างไร

1. เรียกใช้ [`export`](#export) ด้วยตัวกรองเดียวกับ `messages:list` การตอบกลับจะส่งคืนตัวระบุงาน `uid` ทันที ก่อนที่ไฟล์จะถูกสร้างขึ้น
2. ตรวจสอบ [`status`](#status) ด้วย `uid` นั้นจนกว่าจะรายงาน `STATUS_SUCCESS` (หรือ `STATUS_FAILED`)
3. เรียกใช้ [`result`](#result) ด้วย `uid` เดียวกันเพื่อรับชื่อไฟล์ที่สร้างขึ้น
4. [ดาวน์โหลด](#download) ไฟล์ตามชื่อ

ใช้ [`lastTasks`](#lasttasks) เพื่อค้นหางานส่งออกล่าสุดสำหรับแอปพลิเคชัน และใช้ [`delete`](#delete) เพื่อยกเลิกงานหรือลบไฟล์ก่อนเวลา

## เมธอด

วงจรการส่งออกมีห้าเมธอด บวกกับ endpoint สำหรับดาวน์โหลดโดยตรง:

| เมธอด | คำอธิบาย |
|--------|--------------|
| [`exportMessagesStatistics/export`](#export) | จัดคิวการส่งออกและส่งคืน `uid` ของงาน |
| [`exportMessagesStatistics/status`](#status) | ตรวจสอบความคืบหน้าของงาน |
| [`exportMessagesStatistics/result`](#result) | ส่งคืนชื่อไฟล์ที่สร้างขึ้นเมื่องานเสร็จสิ้น |
| [`exportMessagesStatistics/lastTasks`](#lasttasks) | แสดงรายการงานส่งออกล่าสุดสำหรับแอปพลิเคชัน |
| [`exportMessagesStatistics/delete`](#delete) | ยกเลิกงานหรือลบไฟล์ก่อนที่ระยะเวลาการเก็บรักษาจะหมดอายุ |
| [ดาวน์โหลด](#download) | ดาวน์โหลดไฟล์ CSV ที่สร้างขึ้นตามชื่อ |

### export

จัดคิวการส่งออกประวัติข้อความและส่งคืนตัวระบุงานทันที

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/export`

##### ส่วนหัว (Headers)

คำขอต้องการ Server API token:

| ชื่อ | จำเป็น | คำอธิบาย |
|------------------|----------|---------------------------------------------------------------------------------------------------------|
| `Authorization` | ใช่ | [Server API token](/th/developer/api-reference/api-access-token/#server-api-token) ต้องระบุในรูปแบบต่อไปนี้: `Authorization: Api <Server Key>` |

##### พารามิเตอร์ในส่วนเนื้อหาของคำขอ (Request body)

ส่วนเนื้อหาของคำขอยอมรับฟิลด์ต่อไปนี้:

| ชื่อ | จำเป็น | ประเภท | คำอธิบาย |
|----------------------------------------|----------|---------|--------------------------------------------------------------------------------------------------------------------------------|
| `type` | ใช่ | String | ต้องเป็น <code>"TASK_TYPE_EXPORT<wbr/>_MESSAGES_V2"</code> |
| <code>export_messages<wbr/>_v2</code> | ใช่ | Object | พารามิเตอร์การส่งออก อธิบายไว้ด้านล่าง |
| <code>export_messages<wbr/>_v2.application<wbr/>_code</code> | ดูหมายเหตุ | String | [รหัสแอปพลิเคชัน Pushwoosh](/th/developer/api-reference/api-identifiers/#application-code) จำเป็นหากไม่ได้ตั้งค่า `app_group_code` |
| <code>export_messages<wbr/>_v2.app<wbr/>_group_code</code> | ดูหมายเหตุ | String | รหัสกลุ่มแอปพลิเคชัน ส่งออกข้อมูลของทุกแอปในกลุ่ม จำเป็นหากไม่ได้ตั้งค่า `application_code` |
| <code>export_messages<wbr/>_v2.search</code> | ไม่ | String | ค้นหาข้อความอิสระในชื่อและเนื้อหาของข้อความ |
| <code>export_messages<wbr/>_v2.filters</code> | ไม่ | Object | ตัวกรองข้อความ อธิบายไว้ด้านล่าง หากไม่ระบุจะส่งออกประวัติทั้งหมดของบัญชี |
| <code>export_messages<wbr/>_v2.properties</code> | ไม่ | Array | คอลัมน์ที่จะรวมใน CSV อธิบายไว้ด้านล่าง |

`export_messages_v2.filters` ยอมรับ:

| ชื่อ <div style="width:150px"></div> | ประเภท | คำอธิบาย |
|---------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `statuses` | Array | สถานะข้อความที่จะรวม <details><summary>ค่าที่เป็นไปได้</summary><ul><li><code>"MESSAGE_STATUS_CANCELED"</code></li><li><code>"MESSAGE_STATUS_CREATING"</code></li><li><code>"MESSAGE_STATUS_DONE"</code></li><li><code>"MESSAGE_STATUS_FAIL"</code></li><li><code>"MESSAGE_STATUS_PENDING"</code></li><li><code>"MESSAGE_STATUS_PROCESSING"</code></li><li><code>"MESSAGE_STATUS_WAITING"</code></li></ul></details> |
| `platforms` | Array | [รหัสแพลตฟอร์ม](/th/developer/api-reference/messages-api/api-prerequisites/#platforms) (ตัวเลข เช่น `1` สำหรับ iOS) ไม่ใช่สตริงชื่อแพลตฟอร์มที่ใช้โดย `messages:list` |
| `sent_date` | Object | ช่วงเวลารายงานที่กรองตามวันที่ส่ง: `{"date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD"}` |
| `created_date` | Object | ช่วงเวลารายงานที่กรองตามวันที่สร้างข้อความ รูปแบบเดียวกับ `sent_date` |
| `created_via` | Array | แหล่งที่มาของข้อความ <details><summary>ค่าที่เป็นไปได้</summary><ul><li><code>"AB_TEST"</code></li><li><code>"API"</code></li><li><code>"AUTO_PUSH"</code></li><li><code>"CP"</code></li><li><code>"CSV"</code></li><li><code>"CUSTOMER_JOURNEY"</code></li><li><code>"EMAIL_API"</code></li><li><code>"EMAIL_CP"</code></li><li><code>"GEO_ZONE"</code></li><li><code>"PUSH_ON_EVENT"</code></li><li><code>"RSS"</code></li><li><code>"SYSTEM"</code></li></ul></details> |
| `segments` | Array | [รหัสตัวกรอง](/th/developer/api-reference/api-identifiers/#segment--filter-code) ที่ข้อความถูกส่งไป |
| `campaigns` | Array | [รหัสแคมเปญ](/th/developer/api-reference/api-identifiers/#campaign-code) ซึ่งแตกต่างจาก `messages:list` ที่นี่จะรับเป็นรายการ ไม่ใช่รหัสเดียว |
| `message_id` | String (uint64) | ID ข้อความตัวเลขเดียว อยู่ในเครื่องหมายคำพูด ซึ่งแตกต่างจาก `messages:list` ที่การส่งออกจะรับ ID เดียว ไม่ใช่ array |
| `message_code` | String | [รหัสข้อความ](/th/developer/api-reference/api-identifiers/#message-code) เดียว |

`export_messages_v2.properties` จะเลือกว่า CSV จะมีคอลัมน์ใดบ้าง

<details>
<summary>ค่าที่เป็นไปได้</summary>

- `"EXPORT_MESSAGE_PROPERTY_ID"`
- `"EXPORT_MESSAGE_PROPERTY_TIMESTAMP"`
- `"EXPORT_MESSAGE_PROPERTY_CONTENT"`
- `"EXPORT_MESSAGE_PROPERTY_TITLE"`
- `"EXPORT_MESSAGE_PROPERTY_APPLICATIONS"`
- `"EXPORT_MESSAGE_PROPERTY_STATUS"`
- `"EXPORT_MESSAGE_PROPERTY_PLATFORMS"`
- `"EXPORT_MESSAGE_PROPERTY_SOURCE"`
- `"EXPORT_MESSAGE_PROPERTY_FILTER"`
- `"EXPORT_MESSAGE_PROPERTY_SUBSCRIPTION_SEGMENTS"`
- `"EXPORT_MESSAGE_PROPERTY_SENT"`
- `"EXPORT_MESSAGE_PROPERTY_OPENED"`
- `"EXPORT_MESSAGE_PROPERTY_ERRORS"`
- `"EXPORT_MESSAGE_PROPERTY_RECIPIENTS"`
- `"EXPORT_MESSAGE_PROPERTY_DELIVERED"`
- `"EXPORT_MESSAGE_PROPERTY_TOTAL_DELIVERED"`
- `"EXPORT_MESSAGE_PROPERTY_TOTAL_OPENED"`
- `"EXPORT_MESSAGE_PROPERTY_TOTAL_CLICKS"`
- `"EXPORT_MESSAGE_PROPERTY_CLICKS"`
- `"EXPORT_MESSAGE_PROPERTY_UNSUBSCRIBED"`

</details>

<Aside type="caution" title="properties ไม่ใช่แค่ตัวกรอง">
คุณสมบัติที่ไม่ได้ระบุใน `properties` จะไม่ปรากฏในไฟล์เลย รวมถึงคอลัมน์พื้นฐาน (ID, วันที่ส่ง, เนื้อหา, สถานะ) การปล่อยให้ `properties` ว่างจะสร้าง CSV ที่ไม่มีคอลัมน์ โปรดระบุทุกคอลัมน์ที่การส่งออกควรมี ไม่ใช่แค่เมตริกที่คุณต้องการเพิ่มเติมนอกเหนือจากชุดเริ่มต้น
</Aside>

##### ตัวอย่างคำขอ

```json
{
  "type": "TASK_TYPE_EXPORT_MESSAGES_V2",
  "export_messages_v2": {
    "application_code": "XXXXX-XXXXX",
    "filters": {
      "created_date": {
        "date_from": "2026-01-01",
        "date_to": "2026-06-30"
      },
      "statuses": ["MESSAGE_STATUS_DONE"],
      "platforms": [1, 3]
    },
    "properties": [
      "EXPORT_MESSAGE_PROPERTY_ID",
      "EXPORT_MESSAGE_PROPERTY_TIMESTAMP",
      "EXPORT_MESSAGE_PROPERTY_STATUS",
      "EXPORT_MESSAGE_PROPERTY_PLATFORMS",
      "EXPORT_MESSAGE_PROPERTY_SENT",
      "EXPORT_MESSAGE_PROPERTY_OPENED"
    ]
  }
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "uid": "177458"
}
```
</TabItem>
<TabItem label="401: API access token ไม่ถูกต้อง">
```json
{
  "error": "account not found"
}
```
</TabItem>
</Tabs>

### status

ส่งคืนความคืบหน้าของงานส่งออก

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/status`

##### พารามิเตอร์ในส่วนเนื้อหาของคำขอ (Request body)

ส่งตัวระบุงานที่ได้จาก `export`:

| ชื่อ | จำเป็น | ประเภท | คำอธิบาย |
|-------|----------|---------|--------------------------------------------------|
| `uid` | ใช่ | String (int64) | ตัวระบุงานจากการตอบกลับของ `export` เช่น `"177458"` |

##### ตัวอย่างคำขอ

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "status": "STATUS_SUCCESS",
  "progress": 1
}
```
</TabItem>
</Tabs>

`status` เป็นหนึ่งใน `"STATUS_PENDING"`, `"STATUS_SUCCESS"` หรือ `"STATUS_FAILED"` ส่วน `progress` เป็นเศษส่วนระหว่าง `0` ถึง `1`; ให้ตรวจสอบ `status` จนกว่าจะถึง `"STATUS_SUCCESS"` ก่อนที่จะเรียก `result`

### result

ส่งคืนชื่อไฟล์ที่สร้างขึ้นเมื่องานเสร็จสมบูรณ์

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/result`

##### พารามิเตอร์ในส่วนเนื้อหาของคำขอ (Request body)

ส่งตัวระบุงานเดียวกันกับที่ได้จาก `export`:

| ชื่อ | จำเป็น | ประเภท | คำอธิบาย |
|-------|----------|---------|--------------------------------------------------|
| `uid` | ใช่ | String (int64) | ตัวระบุงานจากการตอบกลับของ `export` เช่น `"177458"` |

##### ตัวอย่างคำขอ

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "export_messages_v2_result": {
    "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
  }
}
```
</TabItem>
</Tabs>

การเรียก `result` ก่อนที่ `status` จะรายงาน `"STATUS_SUCCESS"` จะส่งคืนผลลัพธ์ที่ว่างเปล่า ส่งค่า `file` ตามที่เป็นอยู่ไปยัง [endpoint สำหรับดาวน์โหลด](#download)

### lastTasks

แสดงรายการงานส่งออกล่าสุดสำหรับแอปพลิเคชัน โดยเรียงจากล่าสุดก่อน

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/lastTasks`

##### พารามิเตอร์ในส่วนเนื้อหาของคำขอ (Request body)

พารามิเตอร์ทุกตัวเป็นตัวกรองที่ไม่บังคับ หากไม่ระบุเลยจะแสดงรายการงานทั้งหมดที่โทเค็นสามารถเข้าถึงได้:

| ชื่อ | จำเป็น | ประเภท | คำอธิบาย |
|------------------|----------|---------|---------------------------------------------------------------------------------------|
| `application` | ไม่ | String | [รหัสแอปพลิเคชัน Pushwoosh](/th/developer/api-reference/api-identifiers/#application-code) หากไม่ระบุจะแสดงรายการงานของทุกแอปพลิเคชันที่โทเค็นสามารถเข้าถึงได้ |
| `types` | ไม่ | Array | จำกัดเฉพาะประเภทงานที่ระบุ ใช้ <code>["TASK_TYPE_EXPORT<wbr/>_MESSAGES_V2"]</code> เพื่อดูเฉพาะการส่งออกข้อความ |
| `campaign` | ไม่ | String | กรองตาม [รหัสแคมเปญ](/th/developer/api-reference/api-identifiers/#campaign-code) |
| `message_id` | ไม่ | String (uint64) | กรองตาม ID ข้อความตัวเลขเดียว อยู่ในเครื่องหมายคำพูด |
| `message_code` | ไม่ | String | กรองตาม [รหัสข้อความ](/th/developer/api-reference/api-identifiers/#message-code) เดียว |
| `limit` | ไม่ | Integer | จำนวนงานสูงสุดที่จะส่งคืน |
| `timestamp_from` | ไม่ | String | ส่งคืนเฉพาะงานที่สร้างขึ้นหลังจากการประทับเวลานี้ (RFC 3339) |

<Aside type="note">
งานจะถูกเก็บไว้เป็นเวลา 30 วัน โดยไม่คำนึงว่าไฟล์ของงานนั้นถูกลบไปแล้วหลังจากระยะเวลาการเก็บรักษาไฟล์ 7 วันหรือไม่ `lastTasks` ยังคงสามารถแสดงงานที่ `result` ไม่สามารถเชื่อมโยงไปยังไฟล์ที่ดาวน์โหลดได้อีกต่อไป
</Aside>

##### ตัวอย่างคำขอ

```json
{
  "application": "XXXXX-XXXXX",
  "types": ["TASK_TYPE_EXPORT_MESSAGES_V2"],
  "limit": 10
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "tasks": [
    {
      "id": "177458",
      "timestamp": "2026-08-13T12:00:00Z",
      "status": "STATUS_SUCCESS",
      "requested_by_user": "user@example.com",
      "export_messages_v2": {
        "application_code": "XXXXX-XXXXX"
      },
      "export_messages_v2_result": {
        "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
      }
    }
  ]
}
```
</TabItem>
</Tabs>

### delete

ลบงานและไฟล์ของงานนั้นก่อนที่ระยะเวลาการเก็บรักษา 7 วันจะหมดอายุ

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/delete`

##### พารามิเตอร์ในส่วนเนื้อหาของคำขอ (Request body)

ส่งตัวระบุงานที่ได้จาก `export`:

| ชื่อ | จำเป็น | ประเภท | คำอธิบาย |
|-------|----------|---------|--------------------------------------------------|
| `uid` | ใช่ | String (int64) | ตัวระบุงานจากการตอบกลับของ `export` เช่น `"177458"` |

##### ตัวอย่างคำขอ

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{}
```
</TabItem>
</Tabs>

### ดาวน์โหลด

ดาวน์โหลดไฟล์ CSV ที่สร้างโดย `result` ตามชื่อ

`GET` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/<file>`

##### ส่วนหัว (Headers)

รับรองความถูกต้องด้วยวิธีเดียวกับเมธอดอื่นๆ หรือใช้เซสชัน Control Panel ที่ใช้งานอยู่:

| ชื่อ | จำเป็น | คำอธิบาย |
|------------------|----------|-----------------------------------------------------------------------------------------------------|
| `Authorization`| ใช่ | [Server API token](/th/developer/api-reference/api-access-token/#server-api-token) ในรูปแบบเดียวกับเมธอด `exportMessagesStatistics` อื่นๆ: `Authorization: Api <Server Key>` (รูปแบบ `Api` ไม่คำนึงถึงตัวพิมพ์ใหญ่-เล็ก) คำขอที่ไม่มีส่วนหัว `Authorization` และไม่มีเซสชัน Control Panel ที่เข้าสู่ระบบอยู่จะได้รับ `401 Unauthorized` |

แทนที่ `<file>` ด้วยค่า `file` ที่แน่นอนจากการตอบกลับของ `result` ตัวอย่างเช่น:

```
https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv
```

ไฟล์เป็น CSV ที่มีคอลัมน์ที่เลือกใน `properties` ไฟล์จะพร้อมใช้งานเป็นเวลา 7 วันหลังจากการส่งออกเสร็จสิ้น จากนั้นงานล้างข้อมูลจะลบไฟล์ออกและ URL จะไม่สามารถใช้งานได้อีกต่อไป