Kakao API

createKakaoMessage

Используется для отправки сообщений Kakao пользователям

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

Предварительные условия

Перед использованием этой конечной точки убедитесь, что:

Платформа Kakao настроена: В вашем приложении Pushwoosh должны быть настроены учетные данные Kakao. Подробнее
Шаблоны одобрены: Шаблоны Kakao должны быть созданы и одобрены, прежде чем их можно будет использовать. Подробнее
Устройства зарегистрированы: Устройства должны быть зарегистрированы с префиксом kakao:, чтобы быть распознанными как конечные точки Kakao.

Тело запроса

Имя	Обязательный	Тип	Описание
auth*	Да	string	Токен доступа API из панели управления Pushwoosh.
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]	Список User ID для таргетинга.
template*	Да	string	Имя шаблона Kakao. Должен быть предварительно одобренным шаблоном. Подробнее
kakao_content_variables	Нет	object	Пары “ключ-значение” для подстановки переменных в шаблон. Ключи должны соответствовать переменным, определенным в вашем шаблоне Kakao. Необязательно, но позволяет динамически персонализировать ваши сообщения Kakao.

Запрещенные параметры

Следующие параметры не допускаются для этой конечной точки и приведут к ошибке валидации:

platforms: Платформа автоматически устанавливается на Kakao
filter: Фильтрация устройств не поддерживается
filter_code: Коды фильтров не поддерживаются
conditions: Условный таргетинг не поддерживается

Пример запроса

{
  "request": {
    "auth": "your-api-access-token",        // обязательно. Токен доступа API из панели управления Pushwoosh.
    "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 не указан. User 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	User 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"
      }
    ]
  }
}