# Kakao API

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

<Aside type="caution" title="/createKakaoMessage เลิกใช้งานแล้ว">
การผสานรวมใหม่ควรใช้ [Messaging API v2](/th/developer/api-reference/messaging-api-v2/) — ส่ง `platforms: ["KAKAO"]` ไปยัง `Notify` และใช้บล็อก `kakao` ภายใน `payload.content.localized_content` ดู [คู่มือการย้ายข้อมูล](/th/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createkakaomessage)
</Aside>

## createKakaoMessage <Badge text="เลิกใช้งานแล้ว" variant="caution" size="small" />

ใช้ endpoint นี้เพื่อส่งข้อความ Kakao ไปยังผู้ใช้

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

<Aside type="note">
endpoint นี้มีไว้สำหรับการส่งข้อความ Kakao เท่านั้น สำหรับการส่งข้อความหลายช่องทาง ให้ใช้ [`/createMessage`](/th/developer/api-reference/messages-api/)
</Aside>

### ข้อกำหนดเบื้องต้น

ก่อนใช้ endpoint นี้ โปรดตรวจสอบให้แน่ใจว่า:

1. **แพลตฟอร์ม Kakao ได้รับการกำหนดค่าแล้ว**: แอปพลิเคชัน Pushwoosh ของคุณต้องมีการกำหนดค่าข้อมูลประจำตัวของ Kakao [เรียนรู้เพิ่มเติม](/th/developer/first-steps/connect-messaging-services/kakao-configuration/)

2. **เทมเพลตได้รับการอนุมัติแล้ว**: เทมเพลต Kakao ต้องถูกสร้างและอนุมัติก่อนจึงจะสามารถใช้งานได้ [เรียนรู้เพิ่มเติม](/th/product/content/kakao-presets/)

3. **อุปกรณ์ได้รับการลงทะเบียนแล้ว**: อุปกรณ์ต้องลงทะเบียนด้วยคำนำหน้า `kakao:` เพื่อให้รู้จักว่าเป็น endpoint ของ Kakao

### Request body

| ชื่อ <div style="width:180px"></div> | จำเป็น <div style="width:100px"></div> | ประเภท | คำอธิบาย |
| :---- | :---- | :---- | :---- |
| auth\* | ใช่ | string | [API access token](/th/developer/api-reference/api-identifiers/#api-access-token) จาก Pushwoosh Control Panel |
| application\* | ใช่ | string | [Pushwoosh application code](/th/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] | รายการของ device tokens แต่ละ token **ต้อง** มีคำนำหน้า `kakao:` (เช่น `"kakao:user_token"`) |
| users* | จำเป็นหากไม่ได้ระบุ `devices` | array[string] | รายการของ User ID ที่จะกำหนดเป้าหมาย |
| template* | ใช่ | string | ชื่อเทมเพลต Kakao ต้องเป็นเทมเพลตที่ได้รับการอนุมัติล่วงหน้า [เรียนรู้เพิ่มเติม](/th/product/content/kakao-presets/) |
| kakao_content_variables | ไม่ | object | คู่คีย์-ค่าสำหรับการแทนที่ตัวแปรในเทมเพลต คีย์ต้องตรงกับตัวแปรที่กำหนดในเทมเพลต Kakao ของคุณ เป็นทางเลือกแต่ช่วยให้สามารถปรับแต่งข้อความ Kakao ของคุณแบบไดนามิกได้ |

<Aside type="caution" title="สำคัญ">
คุณต้องระบุ `devices` หรือ `users` อย่างใดอย่างหนึ่ง อย่าปล่อยให้ทั้งสองว่างเปล่า
</Aside>

#### พารามิเตอร์ที่ห้ามใช้

พารามิเตอร์ต่อไปนี้ไม่ได้รับอนุญาตสำหรับ endpoint นี้และจะส่งผลให้เกิดข้อผิดพลาดในการตรวจสอบความถูกต้อง:

- `platforms`: แพลตฟอร์มถูกตั้งค่าเป็น Kakao โดยอัตโนมัติ
- `filter`: ไม่รองรับการกรองอุปกรณ์
- `filter_code`: ไม่รองรับรหัสตัวกรอง
- `conditions`: ไม่รองรับการกำหนดเป้าหมายตามเงื่อนไข

### ตัวอย่าง Request

```json
{
  "request": {
    "auth": "your-api-access-token",        // จำเป็น API access token จาก Pushwoosh Control Panel
    "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 Device tokens ที่มีคำนำหน้า kakao:
        "users": ["user_001", "user_002"],  // จำเป็นหากไม่ได้ระบุ devices User IDs ที่จะกำหนดเป้าหมาย
        "template": "welcome_message",      // จำเป็น ชื่อเทมเพลต Kakao (ต้องได้รับการอนุมัติล่วงหน้า)
        "kakao_content_variables": {        // ไม่บังคับ การแทนที่ตัวแปรในเทมเพลต
          "user_name": "John Doe",
          "order_number": "12345"
        }
      }
    ]
  }
}
```

### ตัวอย่าง Response

<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 | User ID ที่ไม่สามารถระบุได้ |
| `FailedDevices` | object | อุปกรณ์ที่ล้มเหลวระหว่างการประมวลผล |
| `UnknownPhoneNumbers` | object | หมายเลขโทรศัพท์ที่ไม่พบ |

</TabItem>

<TabItem label="210">

```json
{
  "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` | device token อย่างน้อยหนึ่งรายการไม่มีคำนำหน้า `kakao:` |
| `Invalid parameter: platforms` | พยายามตั้งค่า platforms ด้วยตนเอง (ไม่ได้รับอนุญาต) |
| `Kakao template is required` | ไม่ได้ระบุชื่อเทมเพลต |
| `Invalid Kakao template` | เทมเพลตที่ระบุไม่มีอยู่ |
| `Kakao template not approved` | มีเทมเพลตอยู่แต่ยังไม่ได้รับการอนุมัติจาก Kakao |
| `Please configure Kakao platform` | แอปพลิเคชันยังไม่ได้กำหนดค่าข้อมูลประจำตัวของ Kakao |

</TabItem>

<TabItem label="500">

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

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