Kakao API

createKakaoMessage

使用此端点向用户发送 Kakao 消息。

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

注意

此端点仅用于 Kakao 消息传递。对于多渠道消息传递，请使用 /createMessage。

前提条件

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

1. 已配置 Kakao 平台：您的 Pushwoosh 应用程序必须已配置 Kakao 凭据。了解更多

2. 模板已获批准：Kakao 模板在使用前必须创建并获得批准。了解更多

3. 设备已注册：设备必须以 kakao: 前缀注册，才能被识别为 Kakao 端点。

请求正文

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

重要提示

您必须提供 devices 或 users。不要将两者都留空。

禁用参数

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

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

请求示例

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

响应示例

200

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

210

{
  "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 凭据

500

{
  "status_code": 500,
  "status_message": "内部服务器错误"
}

代码示例

cURL

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

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

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

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

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