# Audience API

## bulkSetTags

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

Устанавливает значения тегов для списка устройств.

<Aside type="caution" title="Важно">
  При использовании метода `bulkSetTags` убедитесь, что значения тегов устанавливаются как минимум для 50 устройств. Чтобы установить теги для одного устройства, используйте метод [`setTags`](/ru/developer/api-reference/device-api/#settags).
</Aside>

#### Тело запроса

| Имя                                           | Тип    | Описание                                                                 |
| ---------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| application\*  | String  | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code)                                                     |
| auth\*         | String  | [Токен доступа API](/ru/developer/api-reference/api-identifiers/#api-access-token) из Панели управления Pushwoosh.                              |
| create\_missing\_tags                          | Boolean | Если `true`, недостающие теги создаются автоматически.                            |
| devices\*      | Object  | Массив устройств.                                                           |
| devices.hwid                                   | String  | Может использоваться для идентификации устройства вместо `user_id` или `push_token`. [Подробнее](/ru/developer/api-reference/api-identifiers/#hardware-id)         |
| devices.user\_id                               | String  | Может использоваться для идентификации пользователя вместо `hwid` или `push_token`. [Подробнее](/ru/developer/api-reference/api-identifiers/#user-id)               |
| devices.push\_token                            | String  | Может использоваться для идентификации устройства вместо `hwid` или `user_id`. [Подробнее](/ru/developer/api-reference/api-identifiers/#push-token)                |
| devices.list\_operator                         | String  | Определяет, как устанавливать значения для [тегов](/ru/developer/api-reference/api-identifiers/#tag) типа list: `set`, `append` или `remove` |
| devices.tags\* | Object  | Значения для указанных тегов.                                       |

<Tabs>
  <TabItem label="OK">
    ```json
    {
      "request_id": "request_id для использования в GET-методе для получения статуса задачи",
      "status": "Pending"
    }
    ```
  </TabItem>

  <TabItem label="Ошибка">
    ```json
    {
      "message": "неверный запрос"
    }
    ```
  </TabItem>
</Tabs>


```json title="Запрос:"
{
  "application": "application code",   // обязательно. Код приложения Pushwoosh
  "auth": "Pushwoosh auth token",      // обязательно. Токен доступа API из Панели управления Pushwoosh
  "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",            // обязательно. Для тегов типа list. Определяет, как устанавливать значения для
                                       //           тегов типа list: set, append или remove
    "tags": {                          // обязательно. Значения для указанных тегов.
      "tag_name": "tagvalue",          //           используйте правильный тип значения
      "tag_name2": "tagvalue2"
    }
  }]
}

```

```json title="Ответ:"
{
  "request_id": "request_id для использования в GET-методе для получения статуса задачи",
  "status": "Pending"
}
```

## bulkSetTags status

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

Возвращает статус операции `/bulkSetTags`

#### Параметры пути

| Имя        | Тип   | Описание                                |
| ----------- | ------ | ------------------------------------------ |
| request\_id | String | id запроса из предыдущего вызова `/bulkSetTags` |

#### Параметры запроса

| Имя     | Тип    | Описание                                             |
| -------- | ------- | ------------------------------------------------------- |
| detailed | Boolean | (`true`/`false`) возвращать ли подробную информацию по каждому устройству |

```json title="Ответ:"
{
  "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": "тег не найден",
      "tagName3": "неверное значение. ожидается :string"
    }
  }]
}

```

## bulkRegisterDevice

Регистрирует несколько устройств в Pushwoosh за один запрос. Также позволяет указывать различные теги для каждого устройства.

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

### Параметры тела запроса

| Параметр | Тип | Обязательный | Описание |
| :---- | ----- | ----- | ----- |
| application | string | Да | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code) |
| auth | string | Да | [Токен доступа API](/ru/developer/api-reference/api-identifiers/#api-access-token). |
| devices | array | Да | Массив объектов устройств. Каждый объект представляет устройство и связанные с ним данные. Подробности см. в таблице **Параметры объекта устройства** ниже. |

#### Параметры объекта устройства

| Параметр       | Тип     | Обязательный | Описание                                                                                     |
|-----------------|----------|----------|-------------------------------------------------------------------------------------------------|
| hwid          | string | Да      | [Hardware ID](/ru/developer/api-reference/api-identifiers/#hardware-id) или уникальный идентификатор устройства.                                           |
| push_token    | string | Да      | [Push-токен](/ru/developer/api-reference/api-identifiers/#push-token) для устройства.                                                                     |
| platform      | integer| Да      | Идентификатор платформы. [Подробнее](/ru/developer/api-reference/messages-api/api-prerequisites/#platforms) |
| list_operator | string | Нет       | Определяет действие для тегов типа list: <br/> - **"append"**: Добавить указанное значение в список тегов. <br/> - **"remove"**: Удалить указанное значение из списка тегов. <br/> **Примечание**: Если параметр `list_operator` не указан, все существующие значения в списке тегов будут заменены предоставленными значениями. |
| tags          | object | Нет       | Пользовательские [теги](/ru/developer/api-reference/api-identifiers/#tag), присвоенные устройству. Теги — это пары ключ-значение, используемые для сегментации.            |



#### Пример запроса

```json
{
  "application": "application code",   // обязательно. Код приложения Pushwoosh
  "auth": "Pushwoosh auth token",      // обязательно. Токен доступа API из Панели управления Pushwoosh
  "devices": [{                        // обязательно. Массив устройств
    "hwid": "device hwid",             // обязательно. Уникальный идентификатор устройства (может быть email).
    "push_token": "device push token", // обязательно. Push-токен для устройства.
    "platform": 14,                    // обязательно. Платформа устройства (например, 14 для email).
    "list_operator": "append",         // необязательно. Для тегов типа list. Добавляет или удаляет указанное(ые) значение(я) из тега типа list.
    "tags": {                          // необязательно. Значения для указанных тегов.
      "language": "en",                //           используйте правильный тип значения.
      "CSV_Import": "summer_camp"
    }
  },
  {
    "hwid": "device hwid 2",           // обязательно. Уникальный идентификатор второго устройства.
    "push_token": "device push token 2", // обязательно. Push-токен для устройства.
    "platform": 14,                    // обязательно. Платформа устройства.
    "list_operator": "remove",         // необязательно. Добавляет или удаляет значения из тегов типа list.
    "tags": {                          // необязательно. Значения для удаления из указанных тегов.
      "language": "en",
      "CSV_Import": "summer_camp2"
    }
  },
  {
    "hwid": "device hwid 3",           // обязательно. Уникальный идентификатор третьего устройства.
    "push_token": "device push token 3", // обязательно. Push-токен для устройства.
    "platform": 14,                    // обязательно. Платформа устройства.
    "tags": {                          // необязательно. Значения для указанных тегов.
      "language": "en",
      "CSV_Import": "summer_camp3"
    }
  }]
}

```

### Ответ

Метод возвращает ID операции, который можно использовать для отслеживания статуса и результатов процесса массовой регистрации.

```json
{
  "request_id": "request_id для использования в GET-методе для получения статуса задачи",
  "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`, ответ будет содержать подробные результаты для каждого зарегистрированного устройства. |


#### Пример ответа

```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`

### Параметры тела запроса

| Параметр | Тип | Обязательный | Описание |
| :---- | ----- | ----- | ----- |
| application | string | Да | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code) |
| auth | string | Да | [Токен доступа API](/ru/developer/api-reference/api-identifiers/#api-access-token) |
| devices | array | Да | Массив объектов устройств. Каждый объект представляет устройство и связанные с ним данные. Подробности см. в таблице **Параметры объекта устройства** ниже. |

#### Параметры объекта устройства

| Параметр       | Тип     | Обязательный | Описание                                                                                     |
|-----------------|----------|----------|-------------------------------------------------------------------------------------------------|
| hwid          | string | Да      | Hardware ID или уникальный идентификатор устройства. [Подробнее](/ru/developer/api-reference/api-identifiers/#hardware-id)                                          |



#### Пример запроса

```json
{
  "application": "application code",   // обязательно. Код приложения Pushwoosh
  "auth": "Pushwoosh auth token",      // обязательно. Токен доступа API из Панели управления Pushwoosh
  "devices": [{                        // обязательно. Массив устройств
    "hwid": "device hwid",             // обязательно. Уникальный идентификатор устройства (может быть email).
  },
  {
    "hwid": "device hwid 2",           // обязательно. Уникальный идентификатор второго устройства.
  },
  {
    "hwid": "device hwid 3",           // обязательно. Уникальный идентификатор третьего устройства.
  }]
}

```

### Ответ

Метод возвращает ID операции, который можно использовать для отслеживания статуса и результатов массового процесса.

```json
{
  "request_id": "request_id для использования в GET-методе для получения статуса задачи",
  "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`, ответ будет содержать подробные результаты для каждого устройства, чья регистрация была отменена. |


#### Пример ответа

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

```