# /createMessage 参数 在这里，您将找到 [`/createMessage`](/zh/developer/api-reference/messages-api/#createmessage) API 参数的描述。 - [必需参数](#required-parameters) 必须包含在内，才能成功发送 `/createMessage` API 请求并在指定时间广播推送通知。 - [可选参数](#optional-parameters) 允许您自定义推送通知的属性。 ## 必需参数 在 [`/createMessage`](/zh/developer/api-reference/messages-api/#createmessage) 请求中必须使用必需参数。否则，请求将无法提交。 ### application 在您的 Pushwoosh 帐户中创建的应用的唯一代码。应用代码可以在 Control Panel 的左上角找到，也可以在 [`/createApplication`](/zh/developer/api-reference/applications/#createapplication) 请求的响应中找到。应用代码是由 10 个字符（字母和数字）组成的、以连字符分隔的集合。 Pushwoosh 应用代码显示在 Control Panel 的左上角 通过 API 创建应用时，您将在 [`/createApplication`](/zh/developer/api-reference/applications/#createapplication) 请求的响应中获得一个应用代码。 要通过 API 获取先前创建的应用的代码，请调用 [`/getApplications`](/zh/developer/api-reference/applications/#getapplications)。在 [`/getApplications`](/zh/developer/api-reference/applications/#getapplications) 请求的响应中，您将收到在您的 Pushwoosh 帐户中创建的所有应用的列表，其中包含它们的名称和代码。 ### auth 来自 Pushwoosh Control Panel 的 API 访问令牌。转到 **设置** → **API 访问** 并复制您要使用的令牌或生成一个新令牌。 Pushwoosh Control Panel 中的 API 访问设置页面，显示 API 访问令牌 生成访问令牌时，请指定其权限。为您将要使用 API 令牌的活动类型勾选复选框。您可以通过勾选“应用”复选框来创建特定于应用的 API 令牌。 API 令牌生成对话框，带有权限和应用复选框 ### content 定义消息内容的字符串或对象。“content”参数以字符串类型值提交时，将为所有收件人发送相同的消息。 ```txt title="字符串" "content": "Hello world!", ``` JSON 对象用于指定使用 [动态内容](/zh/developer/guides/personalization/dynamic-content/) 的内容，例如，用于多语言消息。 ```txt title="对象" "content": { "en": "Hello!", "es": "¡Hola!", "de": "Hallo!" }, ``` ### notifications 推送属性的 JSON 数组。必须至少包含必需的 `content` 和 `send_date` 参数。 在 "notifications" 数组中使用的可选参数： * [campaign](#campaign) * [capping_days](#capping_days) * [capping_count](#capping_count) * [conditions](#conditions) * [data](#data) * [devices](#devices) * [dynamic_content](#dynamic_content) * [filter](#filter) * [ignore_user_timezone](#ignore_user_timezone) * [inbox_date](#inbox_date) * [inbox_image](#inbox_image) * [link](#link) * [minimize_link](#minimize_link) * [message_type](#message_type) * [platforms](#platforms) * [preset](#preset) * [rich_media](#rich_media) * [send_rate](#send_rate) * [timezone](#timezone) * [template_bindings](#template_bindings) * [transactionId](#transactionid) * [users](#users) ### send_date 发送消息的日期和时间。可以是格式为 YYYY-MM-DD HH:mm 的任何日期和时间，或 'now'。如果设置为 'now'，消息将在提交请求后立即发送。 ## 可选参数 ### campaign Campaign 的代码。要获取 Campaign 代码，请转到 **统计** → **聚合统计** 并选择您要使用的 Campaign。Campaign 代码将显示在页面 URL 的末尾，格式为 `XXXXX-XXXXX`。 **示例：** **URL:** `https://app.pushwoosh.com/applications/AAAAA-AAAAA/statistics/aggregated-message?campaignCode=XXXXX-XXXXX` **Campaign 代码：** `XXXXX-XXXXX` 要获取包含其代码的 Campaign 列表，请调用 [`/getCampaigns`](/zh/developer/api-reference/campaigns/#getcampaigns)。在 `/getCampaigns` 请求的响应中，您将收到为您的 Pushwoosh 帐户中特定应用创建的所有 Campaign 的列表，其中包含它们的编码、名称和描述。 ### capping_days 用于频率上限的周期，以天为单位（最多 30 天）。详情请参阅 [频率上限](/zh/product/messaging-channels/global-frequency-capping/)。 频率上限不适用于 `message_type: transactional` 的消息。在所有其他情况下，都会应用频率上限，包括省略 `message_type` 的请求。 ### capping_count 在 "capping_days" 周期内，可以从特定应用发送到特定设备的最大推送次数。如果创建的消息超过了设备的 "capping_count" 限制，它将不会被发送到该设备。详情请参阅 [频率上限](/zh/product/messaging-channels/global-frequency-capping/)。 ### conditions 条件是像 `[tagName, operator, operand]` 这样的数组，用于根据 [Tags](/zh/developer/guides/audience-and-segmentation/tags/) 及其值发送定向消息，其中： * tagName — 要应用的标签名称， * [operator](/zh/developer/guides/audience-and-segmentation/tags#tag-operators) — 值比较运算符 ("EQ" | "IN" | "NOTEQ" | "NOTIN" | "LTE" | "GTE" | "BETWEEN" | "NOTSET" | "ANY")， * [operand](/zh/developer/guides/audience-and-segmentation/tags#tag-values) — 任何以下类型的标签值：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"]`。 ### conditions_operator 条件数组的逻辑运算符。可能的值：AND | OR。默认为 AND。 如果应用的运算符是 AND（当未指定运算符，或 'conditions_operator' 参数值为 'AND' 时），同时符合所有条件的设备将收到推送通知。 如果运算符是 OR，符合任何指定条件的设备将收到消息。 ### data 用于在推送有效负载中传递任何 [自定义数据](/zh/developer/guides/messaging-channels/using-custom-data) 的 JSON 字符串或 JSON 对象；在有效负载中作为 "u" 参数传递（转换为 JSON 字符串）。 ### devices 用于发送定向推送通知的 [推送令牌](/zh/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token) 或 [hwids](/zh/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) 数组。如果设置，消息将仅发送到列表中的设备。 ### dynamic_content 用于 [动态内容](/zh/product/personalization/dynamic-content) 的占位符，以替代设备标签值。以下示例将向您定位的每个用户发送 "Hello, John!" 消息。如果未设置，动态内容值将从设备标签中获取。 ``` "content": "Hello, {firstname|CapitalizeFirst}!", "dynamic_content_placeholders": { "firstname": "John", "lastname": "Doe" }, ``` ### filter [Segment](/zh/product/audience-data-and-segmentation/segmentation/) 的名称，与在 Pushwoosh Control Panel 中或通过 [`/createFilter`](/zh/developer/api-reference/segmentation-filters-api/#createfilter) API 请求创建的名称完全相同。转到 **受众** → **Segments** 部分并检查已创建的 Segments 列表。 Pushwoosh Control Panel 受众部分的 Segments 列表 要通过 API 获取 Segments 列表，请调用 [`/listFilters`](/zh/developer/api-reference/segmentation-filters-api/#listfilters) API 方法。在 `/listFilters` 请求的响应中，您将收到在您的 Pushwoosh 帐户中创建的所有 Segments 的列表，其中包含 Segments 的名称、条件和到期日期。 ### ignore_user_timezone 如果设置为 'true'，则根据 UTC-0 在 "send_date" 参数中指定的日期和时间发送消息。 如果设置为 'false'，用户将根据其设备的设置在指定的本地时间收到消息。 ### inbox_date 消息应保留在用户 [收件箱](/zh/developer/guides/message-inbox/mobile-message-inbox) 中的截止日期。如果未指定，消息将在发送日期的第二天从收件箱中删除。 ### inbox_image 要在 [收件箱](/zh/developer/guides/message-inbox/mobile-message-inbox) 中消息旁边显示的自定义图像的 URL。 ### inbox_days 收件箱消息的生命周期，以天为单位，最多 30 天。此期限后，消息将从收件箱中删除。可替代 **inbox_date** 参数使用。 ### link 用户打开推送通知后要打开的 URL。 ### message_type 指定推送消息类型。可用值为 `marketing` 和 `transactional`。详情请参阅 [营销消息与交易消息](/zh/product/messaging-channels/marketing-vs-transactional/)。 此参数是可选的。如果省略，`PW_ControlGroup: true` 的用户将不会收到消息。 ### 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](/zh/product/content/push-presets/) 的代码。要获取预设代码，请转到 **内容** → **预设**，展开您要使用的预设，并从预设的详细信息中复制 **预设代码**。 内容部分中的预设列表，显示预设代码 ### rich_media 您要附加到消息中的 [富媒体](/zh/product/content/in-apps/) 页面的代码。要获取代码，请转到 **内容** → **富媒体**，打开您要使用的富媒体页面，并从浏览器的 URL 栏中复制该代码。该代码是由 10 个字符（字母和数字）组成的、以连字符分隔的集合。 内容部分中的富媒体页面，浏览器 URL 栏中显示富媒体代码 ### send_rate 用于限制推送发送速度的节流。有效值为 100 到 1000 推送/秒。 ### timezone 在特定日期和时间发送消息时要考虑的时区。如果设置，则忽略设备的市区。如果忽略，则以 UTC 发送消息。有关支持的时区，请参阅 [https://php.net/manual/timezones.php](https://php.net/manual/timezones.php)。 ### template_bindings 用于您的内容模板的模板占位符。详情请参阅 [Liquid 模板指南](/zh/developer/guides/personalization/liquid-templates/)。 ### transactionId 唯一的消息标识符，用于在网络问题情况下防止消息重复。您可以为通过 [`/createMessage`](/zh/developer/api-reference/messages-api/#createmessage) 或 [`/createTargetedMessage`](/zh/developer/api-reference/messages-api/#createtargetedmessage) 请求创建的消息分配任何 ID。在 Pushwoosh 端存储 5 分钟。 ### users [userIds](/zh/developer/pushwoosh-knowledge-hub/users-userids/) 数组。用户 ID 是通过 [`/registerUser`](/zh/developer/api-reference/user-centric-api/)、[`/registerDevice`](/zh/developer/api-reference/device-api/#registerdevice) 或 [`/registerEmail`](/zh/developer/api-reference/email-api/) API 请求设置的唯一用户标识符。