# WhatsApp API
import { Badge } from '@astrojs/starlight/components';
## createWhatsAppMessage
Used to send WhatsApp messages to users
`POST` `https://api.pushwoosh.com/json/1.3/createWhatsAppMessage`
### Request body
| Name | Required | Type | Description |
| :---- | :---- | :---- | :---- |
| auth\* | Yes | string | [API access token](/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. |
| application\* | Yes | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) |
| notifications\* | Yes | array | Content settings. JSON array of message parameters. See details below. |
### Notification parameters
| Name | Required | Type | Description |
|:----------------------|:------------------------------------------|:--------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| send_date* | Yes | string | Date and time to send the notification. Use format `YYYY-MM-DD HH:mm` or `'now'` to send immediately. |
| content | Required if `content_id` is not provided. | string | Text content of the WhatsApp message. |
| content_id | Required if `content` is not provided. | string | Identifier for a pre-approved WhatsApp template from your Meta account. |
| devices* | Yes | array | Customer phone number (must be associated with a [User ID](/developer/api-reference/api-identifiers/#user-id) using [`/registerDevice`](/developer/api-reference/device-api#registerdevice) and specified in the `hwid` parameter, or use `use_auto_registration`). Only one number can be specified here. |
| use_auto_registration | No | boolean | If set to `true`, the phone number specified in the `devices` parameter will be automatically registered. |
| content_variables | No | object | Content variables to customize the message content. Each placeholder will be replaced with corresponding dynamic values. |
| button_url_variables | No | object | Dynamic URL variables for buttons. Each key represents a button index, and its value is the dynamic variable to replace in the button's URL. **Note**: Button indexing starts at 0, with the first button as 0, the second as 1, and so on. |
| header_variables | No | object | Variables for the header in a WhatsApp template message. Specify the `type` (e.g., `text`, `image`, `video`, `document`) and the corresponding value. **Example**: `"header_variables": {"image": "https://image-url.png"}` |
| preset | No | string | WhatsApp Preset Code from your Control Panel. |
| language | No | string | Language locale of the WhatsApp template (must match the locale in Meta WhatsApp template editor). Default: `"en_US"`. Example: `"en_GB"`. |
### Request example
```json
{
"request": {
"application": "12XXX-67XXX", // required. Pushwoosh application code.
"auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel.
"notifications": [{
"send_date": "now", // required. YYYY-MM-DD HH:mm OR "now".
"content": "Hello! {{1}}", // required if content_id is not provided. Message text.
"content_id": "hello_world", // required if content is not provided. WhatsApp template identifier.
"devices": ["whatsapp:+1234567890"], // required. Customer WhatsApp phone number (must be associated
// with a UserId using /registerDevice and specified in
// the "hwid" parameter or use "use_auto_registration").
// Only one WhatsApp number can be specified here.
"preset": "XXXXX-XXXXX", // optional. WhatsApp Preset Code from your Control Panel.
"content_variables": { // optional. Content variables to customize the message content.
"1": "John"
},
"header_variables": { // optional. Variables for the WhatsApp message header.
"image": "https://image-url.png"
},
"language": "en_GB", // optional. Language locale for the WhatsApp template (must match the locale in Meta WhatsApp template editor). Default: "en_US".
"use_auto_registration": true // optional. Automatically register WhatsApp number specified
// in "devices" parameter.
}]
}
}
```
### Example: Sending a two-factor authentication code via 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"]
}]
}
}
```
### Response example
```json
{
"status_code": 200,
"status_message": "OK",
"response": {
"Messages": [
"9648-0B10EXXX-0D9F2XXX"
]
}
}
```
### Error response
```json
{
"status_code": 210,
"status_message": "Invalid devices list. \"devices\" must be an array.",
"response": {
"Messages": []
}
}
```