# WhatsApp API
import { Badge } from '@astrojs/starlight/components';
## createWhatsAppMessage
用于向用户发送 WhatsApp 消息
`POST` `https://api.pushwoosh.com/json/1.3/createWhatsAppMessage`
### 请求正文
| 名称 | 是否必需 | 类型 | 描述 |
| :---- | :---- | :---- | :---- |
| auth\* | 是 | string | 来自 Pushwoosh 控制面板的 [API access token](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| application\* | 是 | string | [Pushwoosh 应用代码](/zh/developer/api-reference/api-identifiers/#application-code) |
| notifications\* | 是 | array | 内容设置。消息参数的 JSON 数组。详见下文。 |
### 通知参数
| 名称 | 是否必需 | 类型 | 描述 |
|:----------------------|:------------------------------------------|:--------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| send_date* | 是 | string | 发送通知的日期和时间。使用 `YYYY-MM-DD HH:mm` 格式或 `'now'` 立即发送。 |
| content | 如果未提供 `content_id` 则为必需。 | string | WhatsApp 消息的文本内容。 |
| content_id | 如果未提供 `content` 则为必需。 | string | 来自您 Meta 账户的预批准 WhatsApp 模板的标识符。 |
| devices* | 是 | array | 客户电话号码（必须使用 [`/registerDevice`](/zh/developer/api-reference/device-api#registerdevice) 与 [User ID](/zh/developer/api-reference/api-identifiers/#user-id) 关联并在 `hwid` 参数中指定，或使用 `use_auto_registration`）。此处只能指定一个号码。 |
| use_auto_registration | 否 | boolean | 如果设置为 `true`，在 `devices` 参数中指定的电话号码将被自动注册。 |
| content_variables | 否 | object | 用于自定义消息内容的内容变量。每个占位符都将被相应的动态值替换。 |
| button_url_variables | 否 | object | 按钮的动态 URL 变量。每个键代表一个按钮索引，其值是按钮 URL 中要替换的动态变量。**注意**：按钮索引从 0 开始，第一个按钮为 0，第二个为 1，依此类推。 |
| header_variables | 否 | object | WhatsApp 模板消息中头部的变量。指定 `type`（例如 `text`、`image`、`video`、`document`）和相应的值。**示例**：`"header_variables": {"image": "https://image-url.png"}` |
| preset | 否 | string | 来自您控制面板的 WhatsApp Preset Code。 |
| language | 否 | string | WhatsApp 模板的语言区域设置（必须与 Meta WhatsApp 模板编辑器中的区域设置匹配）。默认值：`"en_US"`。示例：`"en_GB"`。 |
### 请求示例
```json
{
"request": {
"application": "12XXX-67XXX", // 必需。Pushwoosh 应用代码。
"auth": "yxoPUlwqm…………pIyEX4H", // 必需。来自 Pushwoosh 控制面板的 API access token。
"notifications": [{
"send_date": "now", // 必需。YYYY-MM-DD HH:mm 或 "now"。
"content": "Hello! {{1}}", // 如果未提供 content_id 则为必需。消息文本。
"content_id": "hello_world", // 如果未提供 content 则为必需。WhatsApp 模板标识符。
"devices": ["whatsapp:+1234567890"], // 必需。客户的 WhatsApp 电话号码（必须使用 /registerDevice
// 与 User ID 关联并在 "hwid" 参数中指定，
// 或使用 "use_auto_registration"）。
// 此处只能指定一个 WhatsApp 号码。
"preset": "XXXXX-XXXXX", // 可选。来自您控制面板的 WhatsApp Preset Code。
"content_variables": { // 可选。用于自定义消息内容的内容变量。
"1": "John"
},
"header_variables": { // 可选。WhatsApp 消息头部的变量。
"image": "https://image-url.png"
},
"language": "en_GB", // 可选。WhatsApp 模板的语言区域设置（必须与 Meta WhatsApp 模板编辑器中的区域设置匹配）。默认值："en_US"。
"use_auto_registration": true // 可选。自动注册在 "devices" 参数中指定的
// WhatsApp 号码。
}]
}
}
```
### 示例：通过 WhatsApp 发送双因素认证码
```json
{
"request": {
"application":"APP_CODE", "auth":"AUTH_TOKEN",
"notifications":[{
"send_date":"now",
"content_id":"replace_with_your_meta_two_factor_template_name",
"content_variables":{"1":"AUTH_CODE"},
"button_url_variables":{"0":"AUTH_CODE"},
"devices":["whatsapp:REPLACE_WITH_YOUR_PHONE_NO"]
}]
}
}
```
### 响应示例
```json
{
"status_code": 200,
"status_message": "OK",
"response": {
"Messages": [
"9648-0B10EXXX-0D9F2XXX"
]
}
}
```
### 错误响应
```json
{
"status_code": 210,
"status_message": "Invalid devices list. \"devices\" must be an array.",
"response": {
"Messages": []
}
}
```