Kakao API

createKakaoMessage

Used to send Kakao messages to users

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

Prerequisites

Before using this endpoint, ensure:

Kakao platform is configured: Your Pushwoosh application must have Kakao credentials configured. Learn more
Templates are approved: Kakao templates must be created and approved before they can be used. Learn more
Devices are registered: Devices must be registered with the kakao: prefix to be recognized as Kakao endpoints.

Request body

Name	Required	Type	Description
auth*	Yes	string	API access token from Pushwoosh Control Panel.
application*	Yes	string	Pushwoosh application code
notifications*	Yes	array	Array of notification objects. See details below.

Notification parameters

Name	Required	Type	Description
send_date*	Yes	string	Date and time to send the message. Use format `YYYY-MM-DD HH:MM:SS` (UTC) or `"now"` to send immediately. All times are interpreted as UTC.
devices*	Required if `users` is not provided	array[string]	List of device tokens. Each token must be prefixed with `kakao:` (e.g., `"kakao:user_token"`).
users*	Required if `devices` is not provided	array[string]	List of user IDs to target.
template*	Yes	string	Kakao template name. Must be a pre-approved template. Learn more
kakao_content_variables	No	object	Key-value pairs for template variable substitution. Keys must match variables defined in your Kakao template. Optional but allows dynamic personalization of your Kakao messages.

Forbidden parameters

The following parameters are not allowed for this endpoint and will result in a validation error:

platforms: Platform is automatically set to Kakao
filter: Device filtering not supported
filter_code: Filter codes not supported
conditions: Conditional targeting not supported

Request example

{
  "request": {
    "auth": "your-api-access-token",        // required. API access token from Pushwoosh Control Panel.
    "application": "XXXXX-XXXXX",           // required. Pushwoosh application code.
    "notifications": [
      {
        "send_date": "now",                 // required. YYYY-MM-DD HH:MM:SS (UTC) OR "now".
        "devices": ["kakao:user123@kakao.com", "kakao:device_abc"],  // required if users is not provided. Device tokens with kakao: prefix.
        "users": ["user_001", "user_002"],  // required if devices is not provided. User IDs to target.
        "template": "welcome_message",      // required. Kakao template name (must be pre-approved).
        "kakao_content_variables": {        // optional. Template variable substitution.
          "user_name": "John Doe",
          "order_number": "12345"
        }
      }
    ]
  }
}

Response example

{
  "status_code": 200,
  "response": {
    "Messages": ["MESSAGE_ID_1"],
    "Warnings": [],
    "UnknownDevices": {},
    "UnknownUsers": {},
    "FailedDevices": {},
    "UnknownPhoneNumbers": {}
  }
}

Field	Type	Description
`Messages`	array[string]	Array of message IDs created for tracking
`Warnings`	array	Any warnings generated during processing
`UnknownDevices`	object	Devices that could not be found
`UnknownUsers`	object	User IDs that could not be resolved
`FailedDevices`	object	Devices that failed during processing
`UnknownPhoneNumbers`	object	Phone numbers that could not be found

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

Common error messages

Error Message	Cause
`Missing required parameter: send_date`	The `send_date` field is not provided in the notification
`Missing required parameter: devices or users`	Neither `devices` nor `users` array is provided
`Invalid Kakao devices list`	One or more device tokens are missing the `kakao:` prefix
`Invalid parameter: platforms`	Attempted to set platforms manually (not allowed)
`Kakao template is required`	Template name was not provided
`Invalid Kakao template`	Specified template does not exist
`Kakao template not approved`	Template exists but is not approved by Kakao
`Please configure Kakao platform`	Application does not have Kakao credentials configured

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

Code examples

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

Example: Sending to users instead of devices

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

Example: Scheduled message

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