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]	قائمة بمعرفات المستخدمين المراد استهدافهم.
template*	نعم	string	اسم قالب Kakao. يجب أن يكون قالبًا معتمدًا مسبقًا. اعرف المزيد
kakao_content_variables	لا	object	أزواج المفتاح-القيمة لاستبدال متغيرات القالب. يجب أن تتطابق المفاتيح مع المتغيرات المحددة في قالب Kakao الخاص بك. اختياري ولكنه يسمح بالتخصيص الديناميكي لرسائل Kakao الخاصة بك.

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

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

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

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

{
  "request": {
    "auth": "your-api-access-token",        // required. API access token from Pushwoosh Control Panel.
    "application": "XXXXX-XXXXX",           // required. Pushwoosh application code.
    "notifications": [
      {
        "send_date": "now",                 // required. YYYY-MM-DD HH:MM:SS (UTC) OR "now".
        "devices": ["kakao:user123@kakao.com", "kakao:device_abc"],  // required if users is not provided. Device tokens with kakao: prefix.
        "users": ["user_001", "user_002"],  // required if devices is not provided. User IDs to target.
        "template": "welcome_message",      // required. Kakao template name (must be pre-approved).
        "kakao_content_variables": {        // optional. Template variable substitution.
          "user_name": "John Doe",
          "order_number": "12345"
        }
      }
    ]
  }
}

مثال على الاستجابة

{
  "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	أرقام الهواتف التي لم يتم العثور عليها

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