# 카카오 API

import { Badge } from '@astrojs/starlight/components';

<Aside type="caution" title="/createKakaoMessage는 더 이상 사용되지 않습니다">
새로운 통합은 [Messaging API v2](/ko/developer/api-reference/messaging-api-v2/)를 사용해야 합니다. `Notify`에 `platforms: ["KAKAO"]`를 전달하고 `payload.content.localized_content` 내에서 `kakao` 블록을 사용하세요. [마이그레이션 가이드](/ko/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createkakaomessage)를 참조하세요.
</Aside>

## createKakaoMessage <Badge text="지원 중단" variant="caution" size="small" />

이 엔드포인트를 사용하여 사용자에게 카카오 메시지를 보냅니다.

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

<Aside type="note">
이 엔드포인트는 카카오 메시징 전용입니다. 다중 채널 메시징의 경우 [`/createMessage`](/ko/developer/api-reference/messages-api/)를 사용하세요.
</Aside>

### 전제 조건

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

1. **카카오 플랫폼 구성**: Pushwoosh 애플리케이션에 카카오 자격 증명이 구성되어 있어야 합니다. [자세히 알아보기](/ko/developer/first-steps/connect-messaging-services/kakao-configuration/)

2. **템플릿 승인**: 카카오 템플릿은 사용하기 전에 생성 및 승인되어야 합니다. [자세히 알아보기](/ko/product/content/kakao-presets/)

3. **기기 등록**: 기기는 카카오 엔드포인트로 인식되도록 `kakao:` 접두사로 등록되어야 합니다.

### 요청 본문

| 이름 <div style="width:180px"></div> | 필수 <div style="width:100px"></div> | 유형 | 설명 |
| :---- | :---- | :---- | :---- |
| auth\* | 예 | string | Pushwoosh Control Panel의 [API access token](/ko/developer/api-reference/api-identifiers/#api-access-token)입니다. |
| application\* | 예 | string | [Pushwoosh application code](/ko/developer/api-reference/api-identifiers/#application-code) |
| notifications\* | 예 | array | 알림 객체의 배열입니다. 자세한 내용은 아래를 참조하세요. |

### 알림 매개변수

| 이름 <div style="width:180px"></div> | 필수 | 유형 | 설명 |
| :---- | :---- | :---- | :---- |
| 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 | 카카오 템플릿 이름입니다. 사전 승인된 템플릿이어야 합니다. [자세히 알아보기](/ko/product/content/kakao-presets/) |
| kakao_content_variables | 아니요 | object | 템플릿 변수 대체를 위한 키-값 쌍입니다. 키는 카카오 템플릿에 정의된 변수와 일치해야 합니다. 선택 사항이지만 카카오 메시지의 동적 개인화를 허용합니다. |

<Aside type="caution" title="중요">
`devices` 또는 `users` 중 하나를 제공해야 합니다. 둘 다 비워두지 마세요.
</Aside>

#### 금지된 매개변수

다음 매개변수는 이 엔드포인트에서 허용되지 않으며 유효성 검사 오류가 발생합니다:

- `platforms`: 플랫폼은 자동으로 카카오로 설정됩니다
- `filter`: 기기 필터링은 지원되지 않습니다
- `filter_code`: 필터 코드는 지원되지 않습니다
- `conditions`: 조건부 타겟팅은 지원되지 않습니다

### 요청 예시

```json
{
  "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_content_variables": {        // 선택 사항. 템플릿 변수 대체.
          "user_name": "John Doe",
          "order_number": "12345"
        }
      }
    ]
  }
}
```

### 응답 예시

<Tabs>
<TabItem label="200">

```json
{
  "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 | 찾을 수 없는 전화번호 |

</TabItem>

<TabItem label="210">

```json
{
  "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` | 템플릿은 존재하지만 카카오에서 승인되지 않았습니다 |
| `Please configure Kakao platform` | 애플리케이션에 카카오 자격 증명이 구성되어 있지 않습니다 |

</TabItem>

<TabItem label="500">

```json
{
  "status_code": 500,
  "status_message": "내부 서버 오류"
}
```

</TabItem>
</Tabs>

### 코드 예시

<Tabs>
<TabItem label="cURL">

```bash
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"
          }
        }
      ]
    }
  }'
```

</TabItem>

<TabItem label="PHP">

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

</TabItem>

<TabItem label="Python">

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

</TabItem>
</Tabs>

### 예시: 기기 대신 사용자에게 보내기

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

### 예시: 예약 메시지

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