# واجهة برمجة تطبيقات Kakao

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

<Aside type="caution" title="تم إيقاف /createKakaoMessage">
يجب أن تستخدم عمليات الدمج الجديدة [Messaging API v2](/ar/developer/api-reference/messaging-api-v2/) — قم بتمرير `platforms: ["KAKAO"]` إلى `Notify` واستخدم كتلة `kakao` داخل `payload.content.localized_content`. راجع [دليل الترحيل](/ar/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createkakaomessage).
</Aside>

## createKakaoMessage <Badge text="مهمل" variant="caution" size="small" />

استخدم نقطة النهاية هذه لإرسال رسائل Kakao إلى المستخدمين.

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

<Aside type="note">
نقطة النهاية هذه مخصصة لرسائل Kakao فقط. للمراسلة متعددة القنوات، استخدم [`/createMessage`](/ar/developer/api-reference/messages-api/).
</Aside>

### المتطلبات الأساسية

قبل استخدام نقطة النهاية هذه، تأكد من:

1. **تم تكوين منصة Kakao**: يجب أن يحتوي تطبيق Pushwoosh الخاص بك على بيانات اعتماد Kakao التي تم تكوينها. [اعرف المزيد](/ar/developer/first-steps/connect-messaging-services/kakao-configuration/)

2. **تمت الموافقة على القوالب**: يجب إنشاء قوالب Kakao والموافقة عليها قبل استخدامها. [اعرف المزيد](/ar/product/content/kakao-presets/)

3. **الأجهزة مسجلة**: يجب تسجيل الأجهزة بالبادئة `kakao:` ليتم التعرف عليها كنقاط نهاية Kakao.

### نص الطلب

| الاسم <div style="width:180px"></div> | مطلوب <div style="width:100px"></div> | النوع | الوصف |
| :---- | :---- | :---- | :---- |
| auth\* | نعم | string | [رمز الوصول إلى API](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| application\* | نعم | string | [رمز تطبيق Pushwoosh](/ar/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] | قائمة بمعرفات المستخدمين المراد استهدافهم. |
| template* | نعم | string | اسم قالب Kakao. يجب أن يكون قالبًا معتمدًا مسبقًا. [اعرف المزيد](/ar/product/content/kakao-presets/) |
| kakao_content_variables | لا | object | أزواج المفتاح-القيمة لاستبدال متغيرات القالب. يجب أن تتطابق المفاتيح مع المتغيرات المحددة في قالب Kakao الخاص بك. اختياري ولكنه يسمح بالتخصيص الديناميكي لرسائل Kakao الخاصة بك. |

<Aside type="caution" title="هام">
يجب عليك توفير `devices` أو `users`. لا تترك كليهما فارغًا.
</Aside>

#### المعلمات المحظورة

المعلمات التالية غير مسموح بها لنقطة النهاية هذه وستؤدي إلى خطأ في التحقق:

- `platforms`: يتم تعيين المنصة تلقائيًا إلى Kakao
- `filter`: تصفية الأجهزة غير مدعومة
- `filter_code`: رموز التصفية غير مدعومة
- `conditions`: الاستهداف الشرطي غير مدعوم

### مثال على الطلب

```json
{
  "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. معرفات المستخدمين المراد استهدافهم.
        "template": "welcome_message",      // مطلوب. اسم قالب Kakao (يجب أن يكون معتمدًا مسبقًا).
        "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] | مصفوفة من معرفات الرسائل التي تم إنشاؤها للتتبع |
| `Warnings` | array | أي تحذيرات تم إنشاؤها أثناء المعالجة |
| `UnknownDevices` | object | الأجهزة التي لم يتم العثور عليها |
| `UnknownUsers` | object | معرفات المستخدمين التي لا يمكن حلها |
| `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` | رمز جهاز واحد أو أكثر يفتقد البادئة `kakao:` |
| `Invalid parameter: 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"
      }
    ]
  }
}
```