Kakao-API

createKakaoMessage

Wird verwendet, um Kakao-Nachrichten an Benutzer zu senden

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

Voraussetzungen

Bevor Sie diesen Endpunkt verwenden, stellen Sie sicher:

Die Kakao-Plattform ist konfiguriert: Ihre Pushwoosh-Anwendung muss mit konfigurierten Kakao-Anmeldeinformationen versehen sein. Erfahren Sie mehr
Vorlagen sind genehmigt: Kakao-Vorlagen müssen erstellt und genehmigt werden, bevor sie verwendet werden können. Erfahren Sie mehr
Geräte sind registriert: Geräte müssen mit dem Präfix kakao: registriert sein, um als Kakao-Endpunkte erkannt zu werden.

Request-Body

Name	Erforderlich	Typ	Beschreibung
auth*	Ja	string	API-Zugriffstoken aus dem Pushwoosh Control Panel.
application*	Ja	string	Pushwoosh-Anwendungscode
notifications*	Ja	array	Array von Benachrichtigungsobjekten. Siehe Details unten.

Benachrichtigungsparameter

Name	Erforderlich	Typ	Beschreibung
send_date*	Ja	string	Datum und Uhrzeit zum Senden 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 der Geräte-Token. Jeder Token muss das Präfix `kakao:` haben (z. B. `„kakao:user_token“`).
users*	Erforderlich, wenn `devices` nicht angegeben ist	array[string]	Liste der anzusprechenden Benutzer-IDs.
template*	Ja	string	Name der Kakao-Vorlage. Muss eine vorab genehmigte Vorlage sein. Erfahren Sie mehr
kakao_content_variables	Nein	object	Schlüssel-Wert-Paare 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.

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

Anfragebeispiel

{
  "request": {
    "auth": "your-api-access-token",        // erforderlich. API-Zugriffstoken aus dem Pushwoosh Control Panel.
    "application": "XXXXX-XXXXX",           // erforderlich. Pushwoosh-Anwendungscode.
    "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. Geräte-Token mit dem Präfix kakao:.
        "users": ["user_001", "user_002"],  // erforderlich, wenn devices nicht angegeben ist. Anzusprechende Benutzer-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"
        }
      }
    ]
  }
}

Antwortbeispiel

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

Feld	Typ	Beschreibung
`Messages`	array[string]	Array der zur Nachverfolgung erstellten Nachrichten-IDs
`Warnings`	array	Alle während der Verarbeitung generierten Warnungen
`UnknownDevices`	object	Geräte, die nicht gefunden werden konnten
`UnknownUsers`	object	Benutzer-IDs, die nicht aufgelöst werden konnten
`FailedDevices`	object	Geräte, die während der Verarbeitung fehlgeschlagen sind
`UnknownPhoneNumbers`	object	Telefonnummern, die nicht gefunden werden konnten

{
  "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`	Ein oder mehrere Geräte-Token haben nicht das Präfix `kakao:`
`Invalid parameter: platforms`	Es wurde versucht, die 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`	Die Anwendung hat keine konfigurierten Kakao-Anmeldeinformationen

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

Codebeispiele

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

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