API для пресетов

Пресет push-уведомлений — это многоразовый шаблон push-уведомлений, тот же объект, который вы создаете в редакторе push-уведомлений в Панели управления. Этот API управляет только пресетами push-уведомлений; пресеты для SMS, WhatsApp, Kakao, LINE и Viber имеют свои собственные выделенные сервисы, которые здесь не рассматриваются.

Используйте code пресета, чтобы отправить его через Notify (полезная нагрузка preset) или через точку Send push в Customer Journey.

Базовый URL

https://rpc-api.svc-nue.pushwoosh.com

Все эндпоинты обслуживаются по HTTPS. Запросы и ответы используют application/json, если не указано иное.

Аутентификация

Каждый запрос должен содержать заголовок Authorization с вашим токеном Server API:

Authorization: Api YOUR_API_TOKEN

Соглашения

• Именование полей: тела запросов и параметры пути/запроса принимают lowerCamelCase (например, sendType, localizedProperties, searchByName) — сервер десериализует любой регистр. Ответы всегда сериализуются с использованием имен полей proto в snake_case (localized_properties, platform_properties, per_page и так далее). Примеры ответов и справочник по объекту Preset ниже используют этот регистр.
• code: каждый ответ с пресетом содержит его собственный код, сгенерированный при Create. Передавайте этот код в Get, Update, UpdatePartial, Delete, Clone и в вышеупомянутые API для сообщений/Journey.
• Ключи платформ: карты platforms и open_actions используют в качестве ключей числовой код типа устройства (1 для iOS, 3 для Android и так далее). platform_properties вместо этого использует в качестве ключа имя перечисления платформы (IOS, ANDROID, HUAWEI_ANDROID, OSX — единственные четыре платформы, которые он охватывает).
• Незаполненные поля: ответы Get, Create и Clone включают все поля объекта Preset, даже если они пустые или имеют нулевое значение. List возвращает сокращенный набор полей — см. List ниже. Update и UpdatePartial вообще не возвращают поля пресета — см. предупреждение в их разделах.

Ответы об ошибках

HTTP-статус	Значение
400 Bad Request	Неверный аргумент — обязательное поле отсутствует или имеет неверный формат, или не выполнено предварительное условие (например, клонирование без name).
401 Unauthorized	Отсутствует или недействителен заголовок Authorization.
403 Forbidden	Приложение или пресет не принадлежат аккаунту вызывающей стороны.
404 Not Found	Пресет или приложение не найдены.
500 Internal Server Error	Неожиданный сбой на стороне сервера.

Delete для пресета, который все еще используется точкой отправки push-уведомлений в запущенном или приостановленном Journey, также вернет 400 Bad Request (FailedPrecondition на уровне протокола) — а не 409. Сначала удалите пресет из Journey.

Эндпоинты

Метод	Путь	Описание
POST	/api/presets	Создать новый пресет push-уведомлений
GET	/api/presets	Получить список пресетов push-уведомлений для приложения
GET	/api/presets/{code}	Получить один пресет push-уведомлений
PUT	/api/presets/{code}	Обновить пресет push-уведомлений (полная перезапись)
PUT	/api/presets/{code}:partial	Обновить пресет push-уведомлений (частично)
POST	/api/presets/{code}:clone	Клонировать пресет push-уведомлений
DELETE	/api/presets/{code}	Удалить пресет push-уведомлений

Create

Создает новый пресет push-уведомлений в приложении и возвращает его со сгенерированным кодом.

POST /api/presets

Тело запроса

Параметр	Тип	Обязательный	Описание
application	string	Да	Код приложения, в котором нужно создать пресет.
name	string	Да	Название пресета.
sendType	string	Нет	Канал пресета (например, push).
isV2	boolean	Нет	Фиксирует флаг происхождения пресета. Опустите, чтобы по умолчанию было true (v2); установите false только при воспроизведении устаревшего пресета v1.

Все остальные поля — локализованный контент, платформы, Deep Link, Message Inbox, категории и т.д. — являются общими с Update и описаны один раз в справочнике по объекту Preset ниже.

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

{
  "application": "XXXXX-XXXXX",
  "name": "20% discount",
  "platforms": { "1": true, "3": true },
  "localizedContent": {
    "default": "Get your 20% discount right now",
    "es": "Consigue tu 20% de descuento ahora mismo"
  },
  "localizedTitle": { "default": "Hi there" },
  "openAction": { "link": { "url": "https://example.com" } },
  "categories": ["promo"]
}

Ответ

Возвращает { "preset": { ... } }, созданный объект Preset.

List

Возвращает список пресетов push-уведомлений для приложения — сокращенный набор полей, а не полный объект — с пагинацией, сортировкой и фильтрацией по названию или категории.

GET /api/presets

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

Параметр	Тип	Обязательный	Описание
application	string	Да	Код приложения, для которого нужно получить список пресетов.
orderBy	string	Нет	NAME (по умолчанию), CREATED или UPDATED.
orderDirection	string	Нет	ASC (по умолчанию) или DESC.
page	integer	Нет	Индекс страницы, начиная с нуля.
perPage	integer	Нет	Размер страницы. По умолчанию 100, если опущено или 0.
searchByName	string	Нет	Поиск подстроки без учета регистра в названии или коде пресета (ILIKE %value%).
searchByCategory	array of strings	Нет	Повторите параметр для фильтрации по нескольким категориям, например, ?searchByCategory=promo&searchByCategory=lifecycle.
showHidden	boolean	Нет	Включить пресеты, помеченные как hidden.

Примечание

isDefault — это устаревший фильтр, сохраненный только для старой формы отправки push-уведомлений в Панели управления — не полагайтесь на него.

Ответ

Каждый элемент содержит только: name, code, platforms, localized_content (простой текст для каждого языка — не localized_properties), localized_title, localized_subtitle, banner, icon, categories, journey_uuid, custom_data, is_v2, created, updated. Все остальные поля объекта Preset — localized_properties, platform_properties, deeplink, richmedia, url и так далее — опускаются, даже если они установлены в пресете.

Поле	Тип	Описание
presets	array of objects	Текущая страница пресетов в сокращенной форме, описанной выше.
page	integer	Возвращенный индекс страницы.
per_page	integer	Размер страницы, использованный для этого ответа.
total	integer	Общее количество пресетов, соответствующих фильтрам, на всех страницах.

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

{
  "presets": [
    { "name": "20% discount", "code": "AAAAA-BBBBB", "platforms": { "1": true, "3": true }, "categories": ["promo"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

Get

Возвращает один пресет push-уведомлений по его коду, со всеми заполненными полями объекта Preset.

GET /api/presets/{code}

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

Параметр	Тип	Описание
code	string	Код пресета.

Ответ

Возвращает { "preset": { ... } }, полный объект Preset.

Update

Перезаписывает существующий пресет push-уведомлений по коду предоставленными полями.

PUT /api/presets/{code}

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

Параметр	Тип	Описание
code	string	Код пресета для перезаписи.

Тело запроса

Те же поля, что и в Create (минус application), плюс остальные поля объекта Preset. sendType принимается, но игнорируется — канал пресета нельзя изменить после создания.

Пропуск поля не всегда означает 'оставить без изменений'

Update перестраивает свойства контента пресета с нуля при каждом вызове: localizedProperties, platformProperties, openAction/openActions, deeplink, deeplinkParams, richmedia, url, campaignCode, filterCode, geoZones, sendRate, cappingCount/cappingDays, три поля notification*Url, remotePage, wnsContent, originalUrl, четыре флага *Silent, inboxImage/inboxIcon/inboxDays/inboxDate, banner, icon, customData и isV2 — если опустить любое из них, оно будет очищено (или, в случае isV2, сброшено на true).

name, platforms, categories, localizedTitle, localizedSubtitle и localizedContent являются исключением: каждое из них затрагивается только при отправке и остается без изменений, если его опустить.

Используйте UpdatePartial, если вы хотите, чтобы первая группа полей также оставалась без изменений при их пропуске.

Ответ не содержит поля preset

Update возвращает {} — пустой объект. Сообщение ответа технически определяет поле preset, но сервер никогда его не заполняет. Вызовите Get после, если вам нужен обновленный объект.

Ответ

Пустой объект в случае успеха: {}.

UpdatePartial

Обновляет только предоставленные поля существующего пресета push-уведомлений по коду, оставляя неустановленные поля без изменений.

PUT /api/presets/{code}:partial

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

Параметр	Тип	Описание
code	string	Код пресета для частичного обновления.

Тело запроса

Те же поля, что и в Update, минус application. В отличие от Update, здесь каждое поле — включая localizedProperties, platformProperties, categories и остальные поля из группы свойств контента, перечисленных в предупреждении Update — остается без изменений, если его опустить, и затрагивается только при отправке (отправленное вами поле типа map/array все равно полностью заменяет существующее значение для этого поля, но не влияет на то, что вы не включили). sendType также принимается, но игнорируется.

Примечание

isV2 является единственным исключением даже здесь: оно перезаписывается при каждом вызове UpdatePartial, по умолчанию принимая значение true, если его опустить. Отправляйте isV2: false явно, если пресет должен оставаться пресетом в стиле v1.

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

{
  "sendRate": 500,
  "cappingCount": 3,
  "cappingDays": 7
}

Ответ

Также пустой объект — см. предупреждение выше.

Clone

Дублирует существующий пресет push-уведомлений под новым именем в том же приложении.

POST /api/presets/{code}:clone

Примечание

В отличие от Clone в API для шаблонов Email, этот эндпоинт не имеет параметра application — он всегда клонирует в пределах собственного приложения исходного пресета. Клон всегда создается с hidden: false, независимо от источника.

Тело запроса

Параметр	Тип	Обязательный	Описание
code	string	Да	Код исходного пресета для дублирования.
name	string	Да	Название для нового пресета.

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

{ "code": "AAAAA-BBBBB", "name": "20% discount (copy)" }

Ответ

Возвращает { "preset": { ... } }, новый объект Preset.

Delete

Безвозвратно удаляет пресет push-уведомлений по коду.

DELETE /api/presets/{code}

Осторожно

Завершится ошибкой, если пресет все еще используется точкой send_push в запущенном или приостановленном Journey — сначала удалите его из Journey. Это действие необратимо.

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

Параметр	Тип	Описание
code	string	Код пресета для удаления.

Ответ

Пустой объект в случае успеха: {}.

Справочник по объектам

Имена полей ниже соответствуют тому, что фактически возвращают Get, Create, Update и Clone — имена полей proto в snake_case (см. Соглашения). Форма lowerCamelCase, используемая в примерах запросов выше, работает так же на входе.

Объект Preset

Идентификация

Поле	Тип	Описание
code	string	Генерируется при Create. Идентифицирует этот пресет во всем остальном API.
name	string	Название пресета.
send_type	string	Канал пресета (например, push).
is_v2	boolean	true для пресетов, созданных или перенесенных на модель контента v2.
system	boolean	Помечает пресет как системный/внутренний.
hidden	boolean	Скрывает пресет из результатов List (отправьте showHidden: true, чтобы включить его).
created	string (RFC 3339)	Временная метка создания.
updated	string (RFC 3339)	Временная метка последнего обновления.

Таргетинг и контент

Поле	Тип	Описание
platforms	map<string, boolean>	Платформы, на которые нацелен пресет, с ключами в виде кода типа устройства (например, "1" для iOS).
localized_properties	map<string, object>	Локаль → расширенный контент для каждой платформы. Та же структура, что и у LocalizedContent в полезной нагрузке Notify — одна запись на блок платформы (ios, android и т.д.). Это основной способ установки специфичного для платформы контента push-уведомлений.
localized_title / localized_subtitle / localized_content	map<string, string>	Локаль → простой текст. Более простая альтернатива localized_properties для заголовка, подзаголовка и тела, когда вам не нужны переопределения для каждой платформы.
platform_properties	map<string, object>	Устаревшие переопределения для каждой платформы, с ключами в виде имени перечисления платформы (IOS, ANDROID, HUAWEI_ANDROID, OSX). См. объект PlatformProperties ниже.
open_action	OpenAction	Действие, срабатывающее, когда пользователь открывает уведомление, применяется ко всем платформам. Взаимоисключающее с open_actions — ответ устанавливает ровно одно из них.
open_actions	map<string, OpenAction>	Переопределение open_action для каждой платформы, с ключами в виде кода типа устройства.
deeplink	string	Код Deep Link.
deeplink_params	map<string, string>	Параметры, передаваемые в Deep Link.
richmedia	string	Код Rich Media, открываемого уведомлением.
url	string	URL, открываемый уведомлением, если не используется Deep Link или Rich Media.

Message Inbox

Поле	Тип	Описание
inbox_image	string	URL изображения, отображаемого в записи Message Inbox.
inbox_icon	string	URL иконки, отображаемой в записи Message Inbox.
inbox_days	integer	Количество дней, в течение которых запись остается в Message Inbox.
inbox_date	string (RFC 3339)	Явная дата истечения срока действия для записи в Message Inbox, как альтернатива inbox_days.

Организация и метаданные

Поле	Тип	Описание
categories	array of strings	Названия категорий, которыми помечен пресет.
campaign_code	string	Код кампании, к которой относится этот пресет.
filter_code	string	Код сегмента / фильтра, на который по умолчанию нацелен этот пресет.
geo_zones	string	Таргетинг на геозоны, если пресет запускается по геолокации.
journey_uuid	string	UUID Customer Journey, которому принадлежит этот пресет, если он был создан из точки отправки push-уведомлений в Journey.
custom_data	object	Произвольный JSON, пересылаемый в клиентский SDK в качестве параметра u.
banner	string	URL большого изображения / вложения.
icon	string	URL пользовательской иконки уведомления.

Ограничения доставки

Поле	Тип	Описание
send_rate	integer	Ограничение скорости для отправок с использованием этого пресета, в сообщениях/секунду — эквивалент SendRate в Notify на уровне пресета.
capping_count / capping_days	integer	Ограничение частоты для этого пресета на одного пользователя — эквивалент count / days в FrequencyCapping в Notify на уровне пресета.

Вебхуки

Поле	Тип	Описание
notification_sent_url	string	URL обратного вызова, запрашиваемый при отправке уведомления с использованием этого пресета.
notification_delivered_url	string	URL обратного вызова, запрашиваемый при доставке уведомления с использованием этого пресета.
notification_click_url	string	URL обратного вызова, запрашиваемый при клике на уведомление с использованием этого пресета.

Устаревшие поля

Эти поля перенесены из модели пресетов v1. Они заполняются для совместимости с Панелью управления, а не для новых интеграций.

Поле	Тип	Описание
remote_page	string	Устаревшая ссылка на удаленную страницу.
wns_content	string	Устаревший JSON-шаблон для Windows toast, принимаемый методами v1 createPreset/getPreset.
original_url	string	Значение url до сокращения, когда url был заменен сокращенной ссылкой.
ios_silent / android_silent / huawei_android_silent	boolean	Флаги для тихих (только с данными) push-уведомлений для каждой платформы.

Объект PlatformProperties

Поля, доступные в каждой записи platform_properties (IOS, ANDROID, HUAWEI_ANDROID, OSX):

Поле	Тип	Описание
badge	string	Переопределение количества на значке.
sound	string	Имя звукового файла.
sound_off	boolean	Отключить звук уведомления.
priority	string	Приоритет в трее (только для Android/Huawei).
delivery_priority	string	Приоритет доставки NORMAL или HIGH (только для Android/Huawei).
ios_interruption_level	string	passive, active, time-sensitive или critical (только для iOS).

Связанные материалы

Notify

Справочник по полезной нагрузке

Справочник по точкам Customer Journey