Параметры /createMessage

Устарело

Метод /createMessage устарел. В новых интеграциях следует использовать Messaging API v2 — см. руководство по миграции для сопоставления полей для приведенных ниже параметров.

Здесь вы найдете описания параметров API /createMessage.

• Обязательные параметры должны быть включены для успешной отправки API-запроса /createMessage и рассылки push-уведомлений в указанное время.

• Необязательные параметры позволяют настраивать свойства push-уведомлений.

Примечание

Если вы используете /createMessage для отправки SMS, обратитесь к разделу Параметры для отправки SMS. Другие параметры передаваться не будут.

Обязательные параметры

Обязательные параметры должны использоваться в запросах /createMessage. В противном случае запрос не будет отправлен.

application

Уникальный код приложения, созданного в вашей учетной записи Pushwoosh. Код приложения можно найти в левом верхнем углу Control Panel или в ответе на запрос /createApplication. Код приложения представляет собой набор из 10 символов (букв и цифр), разделенных дефисами.

При создании приложения через API вы получите код приложения в ответе на ваш запрос /createApplication.

Чтобы получить код ранее созданного приложения через API, вызовите /getApplications. В ответе на запрос /getApplications вы получите список всех приложений, созданных в вашей учетной записи Pushwoosh, с их названиями и кодами.

auth

Токен доступа к API из Pushwoosh Control Panel. Перейдите в Settings → API Access и скопируйте токен, который вы хотите использовать, или сгенерируйте новый.

При генерации токена доступа укажите его разрешения. Установите флажки для тех типов действий, с которыми вы собираетесь использовать токен API. Вы можете создавать токены API для конкретных приложений, установив флажки Applications.

content

Строка или объект, определяющий содержание сообщения. Параметр “content”, переданный со строковым значением, отправит одно и то же сообщение всем получателям.

String

"content": "Hello world!",

Объекты JSON используются для указания контента с помощью динамического контента, например, для многоязычных сообщений.

Object

"content": {
  "en": "Hello!",
  "es": "¡Hola!",
  "de": "Hallo!"
},

notifications

Массив JSON со свойствами push-уведомления. Должен включать как минимум обязательные параметры content и send_date.

Необязательные параметры для использования в массиве “notifications”:

• campaign
• capping_days
• capping_count
• conditions
• data
• devices
• dynamic_content
• filter
• ignore_user_timezone
• inbox_date
• inbox_image
• link
• minimize_link
• message_type
• platforms
• preset
• rich_media
• send_rate
• timezone
• template_bindings
• transactionId
• users

send_date

Дата и время отправки сообщения. Может быть любой датой и временем в формате YYYY-MM-DD HH:mm или ‘now’. Если установлено значение ‘now’, сообщение будет отправлено сразу после отправки запроса.

Необязательные параметры

campaign

Код кампании. Чтобы получить код кампании, перейдите в Statistics → Aggregated statistics и выберите кампанию, которую вы собираетесь использовать. Код кампании будет виден в конце URL-адреса страницы в формате XXXXX-XXXXX.

Пример:

URL: https://app.pushwoosh.com/applications/AAAAA-AAAAA/statistics/aggregated-message?campaignCode=XXXXX-XXXXX

Код кампании: XXXXX-XXXXX

Чтобы получить список кампаний с их кодами, вызовите /getCampaigns. В ответе на запрос /getCampaigns вы получите список всех кампаний, созданных для конкретного приложения в вашей учетной записи Pushwoosh, с их кодами, названиями и описаниями.

capping_days

Период, применяемый для ограничения частоты, в днях (максимум 30 дней). Подробнее см. в разделе Ограничение частоты.

Ограничение частоты не применяется к сообщениям с message_type: transactional. Во всех остальных случаях ограничение частоты применяется, включая запросы, в которых message_type опущен.

capping_count

Максимальное количество push-уведомлений, которое может быть отправлено из определенного приложения на конкретное устройство в течение периода “capping_days”. В случае, если созданное сообщение превышает лимит “capping_count” для устройства, оно не будет отправлено на это устройство. Подробнее см. в разделе Ограничение частоты.

conditions

Условия — это массивы вида [tagName, operator, operand], используемые для отправки целевых сообщений на основе тегов и их значений, где:

• tagName — имя применяемого тега,
• operator — оператор сравнения значений (“EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN” | “NOTSET” | “ANY”),
• operand — значения тегов любого из следующих типов: string | integer | array | date | boolean | list

Описание операторов

EQ	значение тега равно операнду.
IN	значение тега пересекается с операндом (операнд всегда должен быть массивом).
NOTEQ	значение тега не равно операнду.
NOTIN	значение тега не пересекается с операндом (операнд всегда должен быть массивом).
GTE	значение тега больше или равно операнду.
LTE	значение тега меньше или равно операнду.
BETWEEN	значение тега больше или равно минимальному значению операнда, но меньше или равно максимальному значению операнда (операнд всегда должен быть массивом).
NOTSET	тег не установлен. Операнд не учитывается.
ANY	тег имеет любое значение. Операнд не учитывается.

Строковые теги

Допустимые операторы: EQ, IN, NOTEQ, NOTIN, NOTSET, ANY

Допустимые операнды:

EQ, NOTEQ	операнд должен быть строкой
IN, NOTIN	операнд должен быть массивом строк, например ["value 1", "value 2", "value N"]
NOTSET	тег не установлен. Операнд не учитывается
ANY	тег имеет любое значение. Операнд не учитывается

Целочисленные теги

Допустимые операторы: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE, NOTSET, ANY

Допустимые операнды:

EQ, NOTEQ, GTE, LTE	операнд должен быть целым числом
IN, NOTIN	операнд должен быть массивом целых чисел, например [value 1, value 2, value N]
BETWEEN	операнд должен быть массивом целых чисел, например [min_value, max_value]
NOTSET	тег не установлен. Операнд не учитывается
ANY	тег имеет любое значение. Операнд не учитывается

Теги даты

Допустимые операторы: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE, NOTSET, ANY

Допустимые операнды:

• "YYYY-MM-DD 00:00" (строка)
• unix timestamp 1234567890 (целое число)
• "N days ago" (строка) для операторов EQ, BETWEEN, GTE, LTE

Логические теги

Допустимые операторы: EQ, NOTSET, ANY

Допустимые операнды: 0, 1, true, false

Теги списка

Допустимые операторы: IN, NOTIN, NOTSET, ANY

Допустимые операнды: операнд должен быть массивом строк, например ["value 1", "value 2", "value N"].

Важно

Помните, что параметры “filter” и “conditions” не должны использоваться вместе.
Также оба они будут проигнорированы, если в том же запросе используется параметр “devices”.

Теги страны и языка

Значение тега языка — это двухбуквенный код в нижнем регистре в соответствии с ISO-639-1. Значение тега страны — это двухбуквенный код в ВЕРХНЕМ РЕГИСТРЕ в соответствии с ISO_3166-2.

Например, чтобы отправить push-уведомление португалоязычным подписчикам в Бразилии, вам нужно будет указать следующее условие: "conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]

conditions_operator

Логический оператор для массивов условий. Возможные значения: AND | OR. По умолчанию используется AND.

Если применяется оператор AND (когда оператор не указан или параметр ‘conditions_operator’ имеет значение ‘AND’), push-уведомление получат устройства, одновременно соответствующие всем условиям.

Если оператор — OR, сообщение получат устройства, соответствующие любому из указанных условий.

data

Строка JSON или объект JSON, используемый для передачи любых пользовательских данных в полезной нагрузке push-уведомления; передается как параметр “u” в полезной нагрузке (преобразуется в строку JSON).

devices

Массив push-токенов или hwid для отправки целевых push-уведомлений. Если установлено, сообщение будет отправлено только на устройства из списка.

dynamic_content

Заполнители для динамического контента, которые будут использоваться вместо значений тегов устройства. Приведенный ниже пример отправит сообщение “Hello, John!” каждому пользователю, на которого вы нацелены. Если не установлено, значения динамического контента берутся из тегов устройства.

"content": "Hello, {firstname|CapitalizeFirst}!",
"dynamic_content_placeholders": {
  "firstname": "John",
  "lastname": "Doe"
},

filter

Название сегмента в точности так, как он создан в Pushwoosh Control Panel или через API-запрос /createFilter. Перейдите в раздел Audience → Segments и проверьте список созданных сегментов.

Чтобы получить список сегментов через API, вызовите API-метод /listFilters. В ответе на запрос /listFilters вы получите список всех сегментов, созданных в вашей учетной записи Pushwoosh, с названиями, условиями и датами истечения срока действия сегментов.

ignore_user_timezone

Если установлено значение ‘true’, сообщение отправляется в дату и время, указанные в параметре “send_date” в соответствии с UTC-0.

Если установлено значение ‘false’, пользователи получат сообщение в указанное местное время в соответствии с настройками своего устройства.

inbox_date

Дата, до которой сообщение должно храниться в Inbox пользователей. Если не указано, сообщение будет удалено из Inbox на следующий день после даты отправки.

Примечание

Чтобы сохранить сообщение в Inbox, используйте хотя бы один из параметров ‘inbox’: “inbox_date” или “inbox_image”.

Осторожно

Сообщение будет удалено из Inbox в 00:00:01 указанной даты, поэтому предыдущая дата — это последний день, когда пользователь может видеть сообщение в своем Inbox.

inbox_image

URL-адрес пользовательского изображения, которое будет отображаться рядом с сообщением в Inbox.

Примечание

Чтобы сохранить сообщение в Inbox, используйте хотя бы один из параметров ‘inbox’: “inbox_date” или “inbox_image”.

inbox_days

Срок жизни сообщения в Inbox в днях, до 30 дней. По истечении этого периода сообщение будет удалено из Inbox. Может использоваться вместо параметра inbox_date.

link

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

message_type

Указывает тип push-сообщения. Доступные значения: marketing и transactional. Подробнее см. в разделе Маркетинговые и транзакционные сообщения.

Этот параметр является необязательным. Если он опущен, сообщение рассматривается как транзакционное и доставляется всем, включая контрольную группу. Маркетинговые сообщения не доставляются членам контрольной группы.

minimize_link

Сокращатель для минимизации URL-адреса, указанного в параметре “link”. Обратите внимание, что размер полезной нагрузки push-уведомления ограничен, поэтому рассмотрите возможность создания коротких URL-адресов, чтобы не превышать лимит. Доступные значения: 0 — не минимизировать, 2 — bitly. По умолчанию = 2. Сокращатель URL-адресов Google отключен с 30 марта 2019 года.

platforms

Массив кодов платформ для отправки сообщения только на определенные платформы.

Доступные коды платформ включают: 1 — iOS, 3 — Android, 7 — Mac OS X, 8 — Windows, 9 — Amazon, 10 — Safari, 11 — Chrome, 12 — Firefox, 14 — Email, 17 — Huawei, 18 — SMS и 21 — WhatsApp.

preset

Код пресета, созданного в Pushwoosh Control Panel или через API. Чтобы получить код пресета, перейдите в Content → Presets, разверните пресет, который вы собираетесь использовать, и скопируйте Preset Code из сведений о пресете.

rich_media

Код страницы Rich Media, которую вы собираетесь прикрепить к своему сообщению. Чтобы получить код, перейдите в Content → Rich Media, откройте страницу Rich Media, которую вы собираетесь использовать, и скопируйте код из адресной строки вашего браузера. Код представляет собой набор из 10 символов (букв и цифр), разделенных дефисами.

send_rate

Ограничение скорости отправки push-уведомлений. Допустимые значения от 100 до 1000 push-уведомлений в секунду.

timezone

Часовой пояс, который следует учитывать при отправке сообщения в определенную дату и время. Если установлено, часовой пояс устройства игнорируется. Если проигнорировано, сообщение отправляется в UTC. Поддерживаемые часовые пояса см. на https://php.net/manual/timezones.php.

template_bindings

Заполнители шаблона для использования в вашем шаблоне контента. Подробнее см. в руководстве по шаблонам Liquid.

transactionId

Уникальный идентификатор сообщения для предотвращения дублирования сообщений в случае проблем с сетью. Вы можете присвоить любой ID сообщению, созданному с помощью запроса /createMessage или /createTargetedMessage. Хранится на стороне Pushwoosh в течение 5 минут.

use_latest_user_device

Если установлено значение true, доставляет одно push-уведомление на пользователя вместо одного на устройство: его получает только устройство с самым последним Last Application Open среди платформ в platforms. Если ни одно из устройств пользователя на этих платформах не имеет этих данных, его получает первое подходящее устройство, поэтому отправка никогда не отменяется. Устройства без User ID не затрагиваются. Применяется независимо от того, как была нацелена аудитория — по users, filter или conditions. Работает так же, как use_latest_user_device в Messaging API v2. По умолчанию false (отправлять на каждое устройство).

users

Массив userIds. User ID — это уникальный идентификатор пользователя, установленный с помощью API-запроса /registerUser, /registerDevice или /registerEmail.