# Kakao API
import { Badge } from '@astrojs/starlight/components';
## createKakaoMessage
使用此端点向用户发送 Kakao 消息。
`POST` `https://api.pushwoosh.com/json/1.3/createKakaoMessage`
### 前提条件
在使用此端点之前，请确保：
1. **配置 Kakao 平台**：您的 Pushwoosh 应用程序必须已配置 Kakao 凭据。[了解更多](/zh/developer/first-steps/connect-messaging-services/kakao-configuration/)
2. **模板已批准**：必须先创建并批准 Kakao 模板，然后才能使用。[了解更多](/zh/product/content/kakao-presets/)
3. **设备已注册**：设备必须以 `kakao:` 前缀注册，才能被识别为 Kakao 端点。
### 请求正文
| 名称 | 必需 | 类型 | 描述 |
| :---- | :---- | :---- | :---- |
| auth\* | 是 | string | 来自 Pushwoosh Control Panel 的 [API access token](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| application\* | 是 | string | [Pushwoosh application code](/zh/developer/api-reference/api-identifiers/#application-code) |
| notifications\* | 是 | array | 通知对象数组。详见下文。 |
### 通知参数
| 名称 | 必需 | 类型 | 描述 |
| :---- | :---- | :---- | :---- |
| send_date* | 是 | string | 发送消息的日期和时间。使用 `YYYY-MM-DD HH:MM:SS` (UTC) 格式或 `"now"` 立即发送。所有时间均解释为 UTC。 |
| devices* | 如果未提供 `users` 则为必需 | array[string] | 设备令牌列表。每个令牌**必须**以 `kakao:` 为前缀（例如，`"kakao:user_token"`）。 |
| users* | 如果未提供 `devices` 则为必需 | array[string] | 要定位的用户 ID 列表。 |
| template* | 是 | string | Kakao 模板名称。必须是预先批准的模板。[了解更多](/zh/product/content/kakao-presets/) |
| kakao_content_variables | 否 | object | 用于模板变量替换的键值对。键必须与您 Kakao 模板中定义的变量匹配。可选，但允许对您的 Kakao 消息进行动态个性化。 |
#### 禁用参数
此端点不允许使用以下参数，否则将导致验证错误：
- `platforms`：平台自动设置为 Kakao
- `filter`：不支持设备筛选
- `filter_code`：不支持筛选代码
- `conditions`：不支持条件定位
### 请求示例
```json
{
"request": {
"auth": "your-api-access-token", // 必需。来自 Pushwoosh Control Panel 的 API access token。
"application": "XXXXX-XXXXX", // 必需。Pushwoosh application code。
"notifications": [
{
"send_date": "now", // 必需。YYYY-MM-DD HH:MM:SS (UTC) 或 "now"。
"devices": ["kakao:user123@kakao.com", "kakao:device_abc"], // 如果未提供 users 则为必需。带有 kakao: 前缀的设备令牌。
"users": ["user_001", "user_002"], // 如果未提供 devices 则为必需。要定位的用户 ID。
"template": "welcome_message", // 必需。Kakao 模板名称（必须预先批准）。
"kakao_content_variables": { // 可选。模板变量替换。
"user_name": "John Doe",
"order_number": "12345"
}
}
]
}
}
```
### 响应示例
```json
{
"status_code": 200,
"response": {
"Messages": ["MESSAGE_ID_1"],
"Warnings": [],
"UnknownDevices": {},
"UnknownUsers": {},
"FailedDevices": {},
"UnknownPhoneNumbers": {}
}
}
```
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| `Messages` | array[string] | 为跟踪创建的消息 ID 数组 |
| `Warnings` | array | 处理期间生成的任何警告 |
| `UnknownDevices` | object | 找不到的设备 |
| `UnknownUsers` | object | 无法解析的用户 ID |
| `FailedDevices` | object | 处理期间失败的设备 |
| `UnknownPhoneNumbers` | object | 找不到的电话号码 |
```json
{
"status_code": 210,
"status_message": "错误描述"
}
```
##### 常见错误消息
| 错误消息 | 原因 |
| :---- | :---- |
| `Missing required parameter: send_date` | 通知中未提供 `send_date` 字段 |
| `Missing required parameter: devices or users` | 未提供 `devices` 或 `users` 数组 |
| `Invalid Kakao devices list` | 一个或多个设备令牌缺少 `kakao:` 前缀 |
| `Invalid parameter: platforms` | 尝试手动设置平台（不允许） |
| `Kakao template is required` | 未提供模板名称 |
| `Invalid Kakao template` | 指定的模板不存在 |
| `Kakao template not approved` | 模板存在但未获 Kakao 批准 |
| `Please configure Kakao platform` | 应用程序未配置 Kakao 凭据 |
```json
{
"status_code": 500,
"status_message": "内部服务器错误"
}
```
### 代码示例
```bash
curl -X POST "https://api.pushwoosh.com/json/1.3/createKakaoMessage" \
-H "Content-Type: application/json" \
-d '{
"request": {
"auth": "your-api-access-token",
"application": "XXXXX-XXXXX",
"notifications": [
{
"send_date": "now",
"devices": ["kakao:user123@kakao.com", "kakao:device_abc"],
"template": "welcome_message",
"kakao_content_variables": {
"user_name": "John Doe",
"order_number": "12345"
}
}
]
}
}'
```
```php
[
'auth' => 'your-api-access-token',
'application' => 'XXXXX-XXXXX',
'notifications' => [
[
'send_date' => 'now',
'devices' => ['kakao:user123@kakao.com', 'kakao:device_abc'],
'template' => 'welcome_message',
'kakao_content_variables' => [
'user_name' => 'John Doe',
'order_number' => '12345'
]
]
]
]
];
$options = [
'http' => [
'header' => "Content-Type: application/json\r\n",
'method' => 'POST',
'content' => json_encode($data)
]
];
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;
```
```python
import requests
url = "https://api.pushwoosh.com/json/1.3/createKakaoMessage"
payload = {
"request": {
"auth": "your-api-access-token",
"application": "XXXXX-XXXXX",
"notifications": [
{
"send_date": "now",
"devices": ["kakao:user123@kakao.com", "kakao:device_abc"],
"template": "welcome_message",
"kakao_content_variables": {
"user_name": "John Doe",
"order_number": "12345"
}
}
]
}
}
response = requests.post(url, json=payload)
print(response.json())
```
### 示例：发送给用户而非设备
```json
{
"request": {
"auth": "your-api-access-token",
"application": "XXXXX-XXXXX",
"notifications": [
{
"send_date": "now",
"users": ["user_001", "user_002", "user_003"],
"template": "promotion_alert",
"kakao_content_variables": {
"discount_percent": "20",
"promo_code": "SAVE20"
}
}
]
}
}
```
### 示例：定时消息
```json
{
"request": {
"auth": "your-api-access-token",
"application": "XXXXX-XXXXX",
"notifications": [
{
"send_date": "2024-12-25 09:00:00",
"devices": ["kakao:user123"],
"template": "holiday_greeting"
}
]
}
}
```