Kakao API

createKakaoMessage

用于向用户发送 Kakao 消息。

POST https://api.pushwoosh.com/json/1.3/createKakaoMessage

先决条件

在使用此端点之前，请确保：

已配置 Kakao 平台：您的 Pushwoosh 应用程序必须已配置 Kakao 凭据。了解更多
模板已获批准：必须先创建并批准 Kakao 模板才能使用。了解更多
设备已注册：设备必须以 kakao: 前缀注册，才能被识别为 Kakao 端点。

请求正文

名称	必需	类型	描述
auth*	是	string	来自 Pushwoosh 控制面板的 API 访问令牌。
application*	是	string	Pushwoosh 应用程序代码
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 模板名称。必须是预先批准的模板。了解更多
kakao_content_variables	否	object	用于模板变量替换的键值对。键必须与您 Kakao 模板中定义的变量匹配。可选，但允许动态个性化您的 Kakao 消息。

禁用参数

此端点不允许使用以下参数，否则将导致验证错误：

platforms：平台自动设置为 Kakao
filter：不支持设备筛选
filter_code：不支持筛选代码
conditions：不支持条件定位

请求示例

{
  "request": {
    "auth": "your-api-access-token",        // 必需。来自 Pushwoosh 控制面板的 API 访问令牌。
    "application": "XXXXX-XXXXX",           // 必需。Pushwoosh 应用程序代码。
    "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"
        }
      }
    ]
  }
}

响应示例

{
  "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	找不到的电话号码

{
  "status_code": 210,
  "status_message": "Error description"
}

常见错误消息

错误消息	原因
`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 凭据

{
  "status_code": 500,
  "status_message": "Internal server error"
}

代码示例

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
$url = 'https://api.pushwoosh.com/json/1.3/createKakaoMessage';

$data = [
    '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'
                ]
            ]
        ]
    ]
];

$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;

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())

示例：发送给用户而非设备

{
  "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"
        }
      }
    ]
  }
}

示例：定时消息

{
  "request": {
    "auth": "your-api-access-token",
    "application": "XXXXX-XXXXX",
    "notifications": [
      {
        "send_date": "2024-12-25 09:00:00",
        "devices": ["kakao:user123"],
        "template": "holiday_greeting"
      }
    ]
  }
}