Kakao-API

/createKakaoMessage ist veraltet

Neue Integrationen sollten die Messaging API v2 verwenden — übergeben Sie platforms: ["KAKAO"] an Notify und verwenden Sie den kakao-Block innerhalb von payload.content.localized_content. Siehe die Migrationsanleitung.

createKakaoMessage Veraltet

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-Messaging verwenden Sie /createMessage.

Voraussetzungen

Stellen Sie vor der Verwendung dieses Endpunkts sicher:

1. Die Kakao-Plattform ist konfiguriert: Ihre Pushwoosh-Anwendung muss mit konfigurierten Kakao-Anmeldeinformationen versehen 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-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. Mehr erfahren
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.

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 nicht unterstützt
• filter_code: Filtercodes nicht unterstützt
• conditions: Bedingtes Targeting nicht unterstützt

Anfragebeispiel

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

Antwortbeispiel

200

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

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	Ein oder mehrere Geräte-Token haben nicht das Präfix kakao:
Invalid parameter: platforms	Versuch, Plattformen manuell zu setzen (nicht erlaubt)
Kakao template is required	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

500

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

Codebeispiele

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