Kakao API

createKakaoMessage

Verwenden Sie diesen Endpunkt, um Kakao-Nachrichten an Benutzer zu senden.

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

Hinweis

Dieser Endpunkt ist ausschließlich für Kakao-Nachrichten vorgesehen. Für Multi-Channel-Nachrichten verwenden Sie /createMessage.

Voraussetzungen

Bevor Sie diesen Endpunkt verwenden, stellen Sie Folgendes sicher:

1. Kakao-Plattform ist konfiguriert: In Ihrer Pushwoosh-Anwendung müssen Kakao-Anmeldeinformationen konfiguriert sein. Mehr erfahren

2. Vorlagen sind genehmigt: Kakao-Vorlagen müssen erstellt und genehmigt werden, bevor sie verwendet werden können. Mehr erfahren

3. Geräte sind registriert: Geräte müssen mit dem Präfix kakao: registriert sein, um als Kakao-Endpunkte erkannt zu werden.

Anfrage-Body

Name	Erforderlich	Typ	Beschreibung
auth*	Ja	string	API Access Token aus dem Pushwoosh Control Panel.
application*	Ja	string	Pushwoosh Application Code
notifications*	Ja	array	Array von Benachrichtigungsobjekten. Siehe Details unten.

Benachrichtigungsparameter

Name	Erforderlich	Typ	Beschreibung
send_date*	Ja	string	Datum und Uhrzeit für den Versand der Nachricht. Verwenden Sie das Format YYYY-MM-DD HH:MM:SS (UTC) oder "now", um sofort zu senden. Alle Zeiten werden als UTC interpretiert.
devices*	Erforderlich, wenn users nicht angegeben ist	array[string]	Liste von Device Tokens. Jedem Token muss das Präfix kakao: vorangestellt werden (z. B. "kakao:user_token").
users*	Erforderlich, wenn devices nicht angegeben ist	array[string]	Liste der Ziel-User-IDs.
template*	Ja	string	Name der Kakao-Vorlage. Muss eine vorab genehmigte Vorlage sein. Mehr erfahren
kakao_content_variables	Nein	object	Schlüssel-Wert-Paare (Key-Value) für die Ersetzung von Vorlagenvariablen. Die Schlüssel müssen mit den in Ihrer Kakao-Vorlage definierten Variablen übereinstimmen. Optional, ermöglicht aber die dynamische Personalisierung Ihrer Kakao-Nachrichten.

Wichtig

Sie müssen entweder devices oder users angeben. Lassen Sie nicht beide leer.

Verbotene Parameter

Die folgenden Parameter sind für diesen Endpunkt nicht zulässig und führen zu einem Validierungsfehler:

• platforms: Die Plattform wird automatisch auf Kakao gesetzt
• filter: Gerätefilterung wird nicht unterstützt
• filter_code: Filtercodes werden nicht unterstützt
• conditions: Bedingtes Targeting wird nicht unterstützt

Anfrage-Beispiel

{
  "request": {
    "auth": "your-api-access-token",        // erforderlich. API Access Token aus dem Pushwoosh Control Panel.
    "application": "XXXXX-XXXXX",           // erforderlich. Pushwoosh Application Code.
    "notifications": [
      {
        "send_date": "now",                 // erforderlich. YYYY-MM-DD HH:MM:SS (UTC) ODER "now".
        "devices": ["kakao:user123@kakao.com", "kakao:device_abc"],  // erforderlich, wenn users nicht angegeben ist. Device Tokens mit kakao:-Präfix.
        "users": ["user_001", "user_002"],  // erforderlich, wenn devices nicht angegeben ist. Ziel-User-IDs.
        "template": "welcome_message",      // erforderlich. Name der Kakao-Vorlage (muss vorab genehmigt sein).
        "kakao_content_variables": {        // optional. Ersetzung von Vorlagenvariablen.
          "user_name": "John Doe",
          "order_number": "12345"
        }
      }
    ]
  }
}

Antwort-Beispiel

200

{
  "status_code": 200,
  "response": {
    "Messages": ["MESSAGE_ID_1"],
    "Warnings": [],
    "UnknownDevices": {},
    "UnknownUsers": {},
    "FailedDevices": {},
    "UnknownPhoneNumbers": {}
  }
}

Feld	Typ	Beschreibung
Messages	array[string]	Array von Nachrichten-IDs, die für das Tracking erstellt wurden
Warnings	array	Alle während der Verarbeitung generierten Warnungen
UnknownDevices	object	Geräte, die nicht gefunden werden konnten
UnknownUsers	object	User-IDs, die nicht aufgelöst werden konnten
FailedDevices	object	Geräte, bei denen während der Verarbeitung ein Fehler aufgetreten ist
UnknownPhoneNumbers	object	Telefonnummern, die nicht gefunden werden konnten

210

{
  "status_code": 210,
  "status_message": "Error description"
}

Häufige Fehlermeldungen

Fehlermeldung	Ursache
Missing required parameter: send_date	Das Feld send_date ist in der Benachrichtigung nicht angegeben
Missing required parameter: devices or users	Weder das devices- noch das users-Array ist angegeben
Invalid Kakao devices list	Bei einem oder mehreren Device Tokens fehlt das Präfix kakao:
Invalid parameter: platforms	Es wurde versucht, Plattformen manuell festzulegen (nicht zulässig)
Kakao template is required	Der Vorlagenname wurde nicht angegeben
Invalid Kakao template	Die angegebene Vorlage existiert nicht
Kakao template not approved	Die Vorlage existiert, ist aber nicht von Kakao genehmigt
Please configure Kakao platform	Für die Anwendung sind keine Kakao-Anmeldeinformationen konfiguriert

500

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

Code-Beispiele

cURL

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

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

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

Beispiel: Senden an Benutzer anstelle von Geräten

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

Beispiel: Geplante Nachricht

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