카카오 API

createKakaoMessage

사용자에게 카카오 메시지를 보내는 데 사용됩니다.

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

사전 요구 사항

이 엔드포인트를 사용하기 전에 다음을 확인하세요:

카카오 플랫폼 구성: Pushwoosh 애플리케이션에 카카오 자격 증명이 구성되어 있어야 합니다. 자세히 알아보기
템플릿 승인: 카카오 템플릿은 사용하기 전에 생성 및 승인되어야 합니다. 자세히 알아보기
디바이스 등록: 디바이스는 카카오 엔드포인트로 인식되도록 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_content_variables	아니요	object	템플릿 변수 대체를 위한 키-값 쌍입니다. 키는 카카오 템플릿에 정의된 변수와 일치해야 합니다. 선택 사항이지만 카카오 메시지를 동적으로 개인화할 수 있습니다.

금지된 파라미터

다음 파라미터는 이 엔드포인트에서 허용되지 않으며 유효성 검사 오류가 발생합니다:

platforms: 플랫폼은 자동으로 카카오로 설정됩니다
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_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`	템플릿은 존재하지만 카카오에서 승인되지 않았습니다
`Please configure Kakao platform`	애플리케이션에 카카오 자격 증명이 구성되어 있지 않습니다

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