/createMessage 参数

已弃用

/createMessage 已被弃用。新的集成应使用 Messaging API v2 — 请参阅迁移指南，了解以下参数的逐字段映射。

在这里，您将找到 /createMessage API 参数的描述。

• 必需参数 必须包含在内，才能成功发送 /createMessage API 请求并在指定时间广播推送通知。

• 可选参数 允许您自定义推送通知的属性。

注意

如果您使用 /createMessage 发送 SMS，请参阅发送 SMS 的参数。其他参数将不会被传递。

必需参数

在 /createMessage 请求中必须使用必需参数。否则，请求将不会被提交。

application

在您的 Pushwoosh 帐户中创建的应用的唯一代码。应用代码可以在 Control Panel 的左上角或在对 /createApplication 请求的响应中找到。应用代码是由 10 个字符（字母和数字）组成的、以连字符分隔的集合。

通过 API 创建应用时，您将在对 /createApplication 请求的响应中获得应用代码。

要通过 API 获取先前创建的应用的代码，请调用 /getApplications。在对 /getApplications 请求的响应中，您将收到在您的 Pushwoosh 帐户中创建的所有应用的列表，其中包含它们的名称和代码。

auth

来自 Pushwoosh Control Panel 的 API access token。转到 Settings → API Access 并复制您要使用的 token 或生成一个新的。

生成 access token 时，请指定其权限。选中您将要使用该 API token 的活动类型的复选框。您可以通过选中 Applications 复选框来创建特定于应用的 API token。

content

定义消息内容的字符串或对象。以字符串类型值提交的 “content” 参数将为所有收件人发送相同的消息。

字符串

"content": "Hello world!",

JSON 对象用于指定使用 Dynamic Content 的内容，例如，用于多语言消息。

对象

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

notifications

推送属性的 JSON 数组。必须至少包含必需的 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

Campaign 的代码。要获取 Campaign 代码，请转到 Statistics → Aggregated statistics 并选择您要使用的 Campaign。Campaign 代码将显示在页面 URL 的末尾，格式为 XXXXX-XXXXX。

示例：

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

Campaign 代码： XXXXX-XXXXX

要获取包含其代码的 Campaign 列表，请调用 /getCampaigns。在对 /getCampaigns 请求的响应中，您将收到为您的 Pushwoosh 帐户中特定应用创建的所有 Campaign 的列表，其中包含它们的代码、名称和描述。

capping_days

用于频率上限的周期，以天为单位（最多 30 天）。有关详细信息，请参阅频率上限。

频率上限不适用于 message_type: transactional 的消息。在所有其他情况下，都会应用频率上限，包括省略 message_type 的请求。

capping_count

在 “capping_days” 周期内，可以从特定应用发送到特定设备的最大推送次数。如果创建的消息超过了设备的 “capping_count” 限制，则该消息将不会发送到该设备。有关详细信息，请参阅频率上限。

conditions

条件是类似 [tagName, operator, operand] 的数组，用于根据 Tags 及其值发送定向消息，其中：

• 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 时间戳 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 的大写双字母代码。

例如，要向巴西的葡萄牙语订阅者发送推送通知，您需要指定以下条件："conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]

conditions_operator

用于条件数组的逻辑运算符。可能的值：AND | OR。默认为 AND。

如果应用的运算符是 AND（当未指定运算符时，或 ‘conditions_operator’ 参数的值为 ‘AND’），同时符合所有条件的设备将收到推送通知。

如果运算符是 OR，符合任何指定条件的设备将收到消息。

data

用于在推送有效负载中传递任何自定义数据的 JSON 字符串或 JSON 对象；在有效负载中作为 “u” 参数传递（转换为 JSON 字符串）。

devices

用于发送定向推送通知的 push tokens 或 hwids 数组。如果设置，消息将仅发送到列表中的设备。

dynamic_content

用于替代设备 Tag 值的 Dynamic Content 占位符。以下示例将向您定位的每个用户发送 “Hello, John!” 消息。如果未设置，Dynamic Content 值将从设备 Tags 中获取。

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

filter

与在 Pushwoosh Control Panel 中或通过 /createFilter API 请求创建的 Segment 名称完全相同。转到 Audience → Segments 部分并检查已创建的 Segments 列表。

要通过 API 获取 Segments 列表，请调用 /listFilters API 方法。在对 /listFilters 请求的响应中，您将收到在您的 Pushwoosh 帐户中创建的所有 Segments 的列表，其中包含 Segments 的名称、条件和到期日期。

ignore_user_timezone

如果设置为 ‘true’，则根据 UTC-0 在 “send_date” 参数中指定的时间和日期发送消息。

如果设置为 ‘false’，用户将根据其设备的设置在指定的本地时间收到消息。

inbox_date

消息应保留在用户 Inbox 中的截止日期。如果未指定，消息将在发送日期的第二天从 Inbox 中删除。

注意

要将消息保存到 Inbox，请至少使用一个 ‘inbox’ 参数：“inbox_date” 或 “inbox_image”。

警告

消息将在指定日期的 00:00:01 从 Inbox 中删除，因此前一天是用户可以在其 Inbox 中看到消息的最后一天。

inbox_image

在 Inbox 中消息旁边显示的自定义图片的 URL。

注意

要将消息保存到 Inbox，请至少使用一个 ‘inbox’ 参数：“inbox_date” 或 “inbox_image”。

inbox_days

收件箱消息的生命周期（以天为单位），最长 30 天。此期限过后，消息将从收件箱中删除。可用于替代 inbox_date 参数。

link

用户打开推送通知后要打开的 URL。

message_type

指定推送消息类型。可用值为 marketing 和 transactional。有关详细信息，请参阅营销消息与事务性消息。

此参数是可选的。如果省略，消息将被视为事务性消息并发送给所有人，包括对照组。营销消息不会发送给对照组成员。

minimize_link

用于最小化在 “link” 参数中提交的 URL 的缩短器。请注意，推送通知有效负载大小有限，因此请考虑创建短 URL 以免超出限制。可用值：0 — 不最小化，2 — bitly。默认 = 2。Google URL 缩短器自 2019 年 3 月 30 日起已停用。

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, and 21 — WhatsApp。

preset

在 Pushwoosh Control Panel 中或通过 API 创建的 Preset 的代码。要获取 preset 代码，请转到 Content → Presets，展开您要使用的 preset，并从 preset 的详细信息中复制 Preset Code。

rich_media

您要附加到消息中的 In-Apps 页面的代码。要获取代码，请转到 Content → In-Apps，打开您要使用的页面，并从浏览器的 URL 栏中复制该代码。该代码是由 10 个字符（字母和数字）组成的、以连字符分隔的集合。

send_rate

用于限制推送发送速度的节流。有效值为 100 到 1000 推送/秒。

timezone

在特定日期和时间发送消息时要考虑的时区。如果设置，则忽略设备的 timezone。如果忽略，则以 UTC 发送消息。有关支持的 timezone，请参阅 https://php.net/manual/timezones.php。

template_bindings

在您的内容模板中使用的模板占位符。有关详细信息，请参阅 Liquid Templates 指南。

transactionId

唯一的消息标识符，用于在出现网络问题时防止消息重复。您可以为通过 /createMessage 或 /createTargetedMessage 请求创建的消息分配任何 ID。在 Pushwoosh 端存储 5 分钟。

use_latest_user_device

如果设置为 true，则每个用户发送一个推送，而不是每个设备一个：只有在 platforms 中具有最新“上次应用打开”时间的设备才会收到它。如果用户在这些平台上的设备都没有该数据，则第一个匹配的设备会收到它，因此发送永远不会被丢弃。没有用户 ID 的设备不受影响。无论受众是如何定位的——通过 users、filter 还是 conditions——都适用。其工作方式与 Messaging API v2 中的 use_latest_user_device 相同。默认为 false（发送到每个设备）。

users

userIds 数组。User ID 是由 /registerUser、/registerDevice 或 /registerEmail API 请求设置的唯一用户标识符。