# Audience API

## bulkSetTags

`POST` `https://api.pushwoosh.com/api/v2/audience/bulkSetTags`

ตั้งค่าแท็กสำหรับรายการอุปกรณ์

<Aside type="caution" title="สำคัญ">
  เมื่อใช้เมธอด `bulkSetTags` ตรวจสอบให้แน่ใจว่าได้ตั้งค่าแท็กสำหรับอุปกรณ์อย่างน้อย 50 เครื่อง หากต้องการตั้งค่าแท็กสำหรับอุปกรณ์เครื่องเดียว ให้ใช้เมธอด [`setTags`](/th/developer/api-reference/device-api/#settags)
</Aside>

#### Request Body

| ชื่อ                                           | ประเภท    | คำอธิบาย                                                                 |
| ---------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| application\*  | String  | [รหัสแอปพลิเคชัน Pushwoosh](/th/developer/api-reference/api-identifiers/#application-code)                                                     |
| auth\*         | String  | [โทเค็นการเข้าถึง API](/th/developer/api-reference/api-identifiers/#api-access-token) จาก Pushwoosh Control Panel                              |
| create\_missing\_tags                          | Boolean | หากเป็น true แท็กที่ขาดหายไปจะถูกสร้างขึ้นโดยอัตโนมัติ                            |
| devices\*      | Object  | อาร์เรย์ของอุปกรณ์                                                           |
| devices.hwid                                   | String  | สามารถใช้เพื่อระบุอุปกรณ์แทน user\_id หรือ push\_token [เรียนรู้เพิ่มเติม](/th/developer/api-reference/api-identifiers/#hardware-id)         |
| devices.user\_id                               | String  | สามารถใช้เพื่อระบุผู้ใช้แทน hwid หรือ push\_token [เรียนรู้เพิ่มเติม](/th/developer/api-reference/api-identifiers/#user-id)               |
| devices.push\_token                            | String  | สามารถใช้เพื่อระบุอุปกรณ์แทน hwid หรือ user\_id [เรียนรู้เพิ่มเติม](/th/developer/api-reference/api-identifiers/#push-token)                |
| devices.list\_operator                         | String  | กำหนดวิธีการตั้งค่าสำหรับ [แท็ก](/th/developer/api-reference/api-identifiers/#tag) ประเภทรายการ: set, append, หรือ remove |
| devices.tags\* | Object  | ค่าที่จะตั้งสำหรับแท็กที่ระบุ                                       |

<Tabs>
  <TabItem label="สำเร็จ">
    ```json
    {
      "request_id": "request_id to use in GET method to obtain job status",
      "status": "Pending"
    }
    ```
  </TabItem>

  <TabItem label="ข้อผิดพลาด">
    ```json
    {
      "message": "invalid request"
    }
    ```
  </TabItem>
</Tabs>


```json title="Request:"
{
  "application": "application code",   // จำเป็น รหัสแอป Pushwoosh
  "auth": "Pushwoosh auth token",      // จำเป็น โทเค็นการเข้าถึง API จาก Pushwoosh Control Panel
  "create_missing_tags": false,        // ไม่จำเป็น ควรสร้างแท็กที่ขาดหายไปโดยอัตโนมัติ
  "devices": [{                        // จำเป็น อาร์เรย์ของอุปกรณ์
    "hwid": "device hwid",             // ไม่จำเป็น สามารถใช้เพื่อระบุอุปกรณ์แทน
                                       //           "user_id" หรือ "push_token"
    "user_id": "user ID",              // ไม่จำเป็น สามารถใช้เพื่อระบุผู้ใช้แทน "hwid" หรือ "push_token"
    "push_token": "device push token", // ไม่จำเป็น สามารถใช้เพื่อระบุอุปกรณ์แทน "hwid" หรือ "user_id"
    "list_operator": "set",            // จำเป็น สำหรับแท็กรายการ กำหนดวิธีการตั้งค่าสำหรับ
                                       //           แท็กประเภทรายการ: set, append, หรือ remove
    "tags": {                          // จำเป็น ค่าที่จะตั้งสำหรับแท็กที่ระบุ
      "tag_name": "tagvalue",          //           ใช้ประเภทค่าที่ถูกต้อง
      "tag_name2": "tagvalue2"
    }
  }]
}

```

```json title="Response:"
{
  "request_id": "request_id to use in GET method to obtain job status",
  "status": "Pending"
}
```

## bulkSetTags status

`GET` `https://api.pushwoosh.com/api/v2/audience/bulkSetTags/{request_id}?detailed=false`

ส่งคืนสถานะของการดำเนินการ `/bulkSetTags`

#### Path Parameters

| ชื่อ        | ประเภท   | คำอธิบาย                                |
| ----------- | ------ | ------------------------------------------ |
| request\_id | String | request id จากการเรียก `/bulkSetTags` ก่อนหน้า |

#### Query Parameters

| ชื่อ     | ประเภท    | คำอธิบาย                                             |
| -------- | ------- | ------------------------------------------------------- |
| detailed | Boolean | (true/false) ว่าจะส่งคืนข้อมูลโดยละเอียดต่ออุปกรณ์หรือไม่ |

```json title="Response:"
{
  "request_id": "id of the request",
  "status": "Completed",          // อาจเป็น "Pending", "Failed"
  "progress": 100,                // ความคืบหน้าของงาน 0-100
  "devices_success": 100,         // อุปกรณ์ที่สำเร็จ
  "devices_not_found": 0,         // อุปกรณ์ที่ไม่พบใน Pushwoosh
  "devices_failed": 0,            // เกิดข้อผิดพลาด
  "devices": [{                   // รายงานอุปกรณ์ (เฉพาะใน detailed = true)
    "hwid": "device hwid",
    "status": "done",             // อาจเป็น "failed", "not found"
    "tags": {
      "tagName": "ok",
      "tagName2": "tag not found",
      "tagName3": "wrong value. expect :string"
    }
  }]
}

```

## bulkRegisterDevice

ลงทะเบียนอุปกรณ์หลายเครื่องใน Pushwoosh ในคำขอเดียว นอกจากนี้ยังอนุญาตให้ระบุแท็กต่างๆ สำหรับแต่ละอุปกรณ์ได้อีกด้วย

`POST` `https://api.pushwoosh.com/api/v2/audience/bulkRegisterDevice`

### Request body parameters

| พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
| :---- | ----- | ----- | ----- |
| application | string | ใช่ | [รหัสแอปพลิเคชัน Pushwoosh](/th/developer/api-reference/api-identifiers/#application-code) |
| auth | string | ใช่ | [โทเค็นการเข้าถึง API](/th/developer/api-reference/api-identifiers/#api-access-token) |
| devices | array | ใช่ | อาร์เรย์ของอ็อบเจกต์อุปกรณ์ แต่ละอ็อบเจกต์แทนอุปกรณ์และข้อมูลที่เกี่ยวข้อง ดูรายละเอียดในตาราง **Device object parameters** ด้านล่าง |

#### Device object parameters

| พารามิเตอร์       | ประเภท     | จำเป็น | คำอธิบาย                                                                                     |
|-----------------|----------|----------|-------------------------------------------------------------------------------------------------|
| hwid          | string | ใช่      | [ID ฮาร์ดแวร์](/th/developer/api-reference/api-identifiers/#hardware-id) หรือตัวระบุที่ไม่ซ้ำกันสำหรับอุปกรณ์                                           |
| push_token    | string | ใช่      | [Push token](/th/developer/api-reference/api-identifiers/#push-token) สำหรับอุปกรณ์                                                                     |
| platform      | integer| ใช่      | ตัวระบุแพลตฟอร์ม [เรียนรู้เพิ่มเติม](/th/developer/api-reference/messages-api/api-prerequisites/#platforms) |
| list_operator | string | ไม่       | กำหนดการดำเนินการสำหรับแท็กประเภทรายการ: <br/> - **"append"**: เพิ่มค่าที่ระบุลงในรายการแท็ก <br/> - **"remove"**: ลบค่าที่ระบุออกจากรายการแท็ก <br/> **หมายเหตุ**: หากไม่ได้ระบุพารามิเตอร์ `list_operator` ค่าที่มีอยู่ทั้งหมดในรายการแท็กจะถูกแทนที่ด้วยค่าที่ให้มา |
| tags          | object | ไม่       | [แท็ก](/th/developer/api-reference/api-identifiers/#tag) ที่กำหนดเองซึ่งกำหนดให้กับอุปกรณ์ แท็กคือคู่คีย์-ค่าที่ใช้สำหรับการแบ่งกลุ่ม            |



#### Request example

```json
{
  "application": "application code",   // จำเป็น รหัสแอป Pushwoosh
  "auth": "Pushwoosh auth token",      // จำเป็น โทเค็นการเข้าถึง API จาก Pushwoosh Control Panel
  "devices": [{                        // จำเป็น อาร์เรย์ของอุปกรณ์
    "hwid": "device hwid",             // จำเป็น ตัวระบุที่ไม่ซ้ำกันสำหรับอุปกรณ์ (อาจเป็นอีเมล)
    "push_token": "device push token", // จำเป็น โทเค็นการแจ้งเตือนแบบพุชสำหรับอุปกรณ์
    "platform": 14,                    // จำเป็น แพลตฟอร์มอุปกรณ์ (เช่น 14 สำหรับอีเมล)
    "list_operator": "append",         // ไม่จำเป็น สำหรับแท็กรายการ เพิ่มหรือลบค่าที่ระบุจากแท็กประเภทรายการ
    "tags": {                          // ไม่จำเป็น ค่าที่จะตั้งสำหรับแท็กที่ระบุ
      "language": "en",                //           ใช้ประเภทค่าที่ถูกต้อง
      "CSV_Import": "summer_camp"
    }
  },
  {
    "hwid": "device hwid 2",           // จำเป็น ตัวระบุที่ไม่ซ้ำกันสำหรับอุปกรณ์ที่สอง
    "push_token": "device push token 2", // จำเป็น โทเค็นการแจ้งเตือนแบบพุชสำหรับอุปกรณ์
    "platform": 14,                    // จำเป็น แพลตฟอร์มอุปกรณ์
    "list_operator": "remove",         // ไม่จำเป็น เพิ่มหรือลบค่าจากแท็กประเภทรายการ
    "tags": {                          // ไม่จำเป็น ค่าที่จะลบออกจากแท็กที่ระบุ
      "language": "en",
      "CSV_Import": "summer_camp2"
    }
  },
  {
    "hwid": "device hwid 3",           // จำเป็น ตัวระบุที่ไม่ซ้ำกันสำหรับอุปกรณ์ที่สาม
    "push_token": "device push token 3", // จำเป็น โทเค็นการแจ้งเตือนแบบพุชสำหรับอุปกรณ์
    "platform": 14,                    // จำเป็น แพลตฟอร์มอุปกรณ์
    "tags": {                          // ไม่จำเป็น ค่าที่จะตั้งสำหรับแท็กที่ระบุ
      "language": "en",
      "CSV_Import": "summer_camp3"
    }
  }]
}

```

### Response

เมธอดจะตอบกลับด้วย ID การดำเนินการ ซึ่งสามารถใช้เพื่อติดตามสถานะและผลลัพธ์ของกระบวนการลงทะเบียนจำนวนมาก

```json
{
  "request_id": "request_id to use in GET method to obtain job status",
  "status": "Pending"
}

```

## bulkRegisterDevice status

คุณสามารถตรวจสอบสถานะของกระบวนการลงทะเบียนจำนวนมากได้โดยการส่งคำขอ **GET** ต่อไปนี้:

`GET` `https://api.pushwoosh.com/api/v2/audience/bulkRegisterDevice/{request_id}?detailed=true`

| พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
| ----- | ----- | ----- | ----- |
| request_id | string | ใช่ | ID คำขอที่ส่งคืนโดยคำขอ POST |
| detailed | boolean | ไม่ | หากตั้งค่าเป็น `true` การตอบกลับจะรวมผลลัพธ์โดยละเอียดสำหรับแต่ละอุปกรณ์ที่ลงทะเบียน |


#### Example response

```json
{
  "request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782",
  "status": "Completed",
  "progress": 100,
  "devices_success": 4,
  "devices": [
    {
      "hwid": "user1@example.com",
      "status": "done"
    },
    {
      "hwid": "user2@example.com",
      "status": "done"
    },
    {
      "hwid": "user3@example.com",
      "status": "done"
    },
    {
      "hwid": "invalid_email@example.com",
      "status": "failed"
    }
  ]
}

```

## bulkUnregisterDevice

ยกเลิกการลงทะเบียนอุปกรณ์หลายเครื่องจาก Pushwoosh ในคำขอเดียว

`POST` `https://api.pushwoosh.com/api/v2/audience/bulkUnregisterDevice`

### Request body parameters

| พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
| :---- | ----- | ----- | ----- |
| application | string | ใช่ | [รหัสแอปพลิเคชัน Pushwoosh](/th/developer/api-reference/api-identifiers/#application-code) |
| auth | string | ใช่ | [โทเค็นการเข้าถึง API](/th/developer/api-reference/api-identifiers/#api-access-token) |
| devices | array | ใช่ | อาร์เรย์ของอ็อบเจกต์อุปกรณ์ แต่ละอ็อบเจกต์แทนอุปกรณ์และข้อมูลที่เกี่ยวข้อง ดูรายละเอียดในตาราง **Device object parameters** ด้านล่าง |

#### Device object parameters

| พารามิเตอร์       | ประเภท     | จำเป็น | คำอธิบาย                                                                                     |
|-----------------|----------|----------|-------------------------------------------------------------------------------------------------|
| hwid          | string | ใช่      | ID ฮาร์ดแวร์หรือตัวระบุที่ไม่ซ้ำกันสำหรับอุปกรณ์ [เรียนรู้เพิ่มเติม](/th/developer/api-reference/api-identifiers/#hardware-id)                                          |



#### Request example

```json
{
  "application": "application code",   // จำเป็น รหัสแอป Pushwoosh
  "auth": "Pushwoosh auth token",      // จำเป็น โทเค็นการเข้าถึง API จาก Pushwoosh Control Panel
  "devices": [{                        // จำเป็น อาร์เรย์ของอุปกรณ์
    "hwid": "device hwid",             // จำเป็น ตัวระบุที่ไม่ซ้ำกันสำหรับอุปกรณ์ (อาจเป็นอีเมล)
  },
  {
    "hwid": "device hwid 2",           // จำเป็น ตัวระบุที่ไม่ซ้ำกันสำหรับอุปกรณ์ที่สอง
  },
  {
    "hwid": "device hwid 3",           // จำเป็น ตัวระบุที่ไม่ซ้ำกันสำหรับอุปกรณ์ที่สาม
  }]
}

```

### Response

เมธอดจะตอบกลับด้วย ID การดำเนินการ ซึ่งสามารถใช้เพื่อติดตามสถานะและผลลัพธ์ของกระบวนการจำนวนมาก

```json
{
  "request_id": "request_id to use in GET method to obtain job status",
  "status": "Pending"
}

```

## bulkUnregisterDevice status

คุณสามารถตรวจสอบสถานะของกระบวนการยกเลิกการลงทะเบียนจำนวนมากได้โดยการส่งคำขอ **GET** ต่อไปนี้:

`GET` `https://api.pushwoosh.com/api/v2/audience/bulkUnregisterDevice/{request_id}?detailed=true`

| พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
| ----- | ----- | ----- | ----- |
| request_id | string | ใช่ | ID คำขอที่ส่งคืนโดยคำขอ POST |
| detailed | boolean | ไม่ | หากตั้งค่าเป็น `true` การตอบกลับจะรวมผลลัพธ์โดยละเอียดสำหรับแต่ละอุปกรณ์ที่ยกเลิกการลงทะเบียน |


#### Example response

```json
{
  "request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782",
  "status": "Completed",
  "progress": 100,
  "devices_success": 4,
  "devices": [
    {
      "hwid": "user1@example.com",
      "status": "done"
    },
    {
      "hwid": "user2@example.com",
      "status": "done"
    },
    {
      "hwid": "user3@example.com",
      "status": "done"
    },
    {
      "hwid": "invalid_email@example.com",
      "status": "failed"
    }
  ]
}

```