API de Kakao

createKakaoMessage

Se utiliza para enviar mensajes de Kakao a los usuarios

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

Prerrequisitos

Antes de utilizar este endpoint, asegúrese de que:

La plataforma Kakao está configurada: Su aplicación Pushwoosh debe tener las credenciales de Kakao configuradas. Más información
Las plantillas están aprobadas: Las plantillas de Kakao deben crearse y aprobarse antes de poder utilizarlas. Más información
Los dispositivos están registrados: Los dispositivos deben registrarse con el prefijo kakao: para ser reconocidos como endpoints de Kakao.

Cuerpo de la solicitud

Nombre	Requerido	Tipo	Descripción
auth*	Sí	string	Token de acceso a la API del Panel de Control de Pushwoosh.
application*	Sí	string	Código de aplicación de Pushwoosh
notifications*	Sí	array	Array de objetos de notificación. Vea los detalles a continuación.

Parámetros de notificación

Nombre	Requerido	Tipo	Descripción
send_date*	Sí	string	Fecha y hora para enviar el mensaje. Utilice el formato `YYYY-MM-DD HH:MM:SS` (UTC) o `"now"` para enviar inmediatamente. Todas las horas se interpretan como UTC.
devices*	Requerido si no se proporciona `users`	array[string]	Lista de tokens de dispositivo. Cada token debe tener el prefijo `kakao:` (por ejemplo, `"kakao:user_token"`).
users*	Requerido si no se proporciona `devices`	array[string]	Lista de IDs de usuario a los que dirigirse.
template*	Sí	string	Nombre de la plantilla de Kakao. Debe ser una plantilla preaprobada. Más información
kakao_content_variables	No	object	Pares clave-valor para la sustitución de variables de la plantilla. Las claves deben coincidir con las variables definidas en su plantilla de Kakao. Opcional, pero permite la personalización dinámica de sus mensajes de Kakao.

Parámetros prohibidos

Los siguientes parámetros no están permitidos para este endpoint y darán lugar a un error de validación:

platforms: La plataforma se establece automáticamente en Kakao
filter: Filtrado de dispositivos no soportado
filter_code: Códigos de filtro no soportados
conditions: Segmentación condicional no soportada

Ejemplo de solicitud

{
  "request": {
    "auth": "your-api-access-token",        // requerido. Token de acceso a la API del Panel de Control de Pushwoosh.
    "application": "XXXXX-XXXXX",           // requerido. Código de aplicación de Pushwoosh.
    "notifications": [
      {
        "send_date": "now",                 // requerido. YYYY-MM-DD HH:MM:SS (UTC) O "now".
        "devices": ["kakao:user123@kakao.com", "kakao:device_abc"],  // requerido si no se proporciona users. Tokens de dispositivo con prefijo kakao:.
        "users": ["user_001", "user_002"],  // requerido si no se proporciona devices. IDs de usuario a los que dirigirse.
        "template": "welcome_message",      // requerido. Nombre de la plantilla de Kakao (debe estar preaprobada).
        "kakao_content_variables": {        // opcional. Sustitución de variables de la plantilla.
          "user_name": "John Doe",
          "order_number": "12345"
        }
      }
    ]
  }
}

Ejemplo de respuesta

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

Campo	Tipo	Descripción
`Messages`	array[string]	Array de IDs de mensaje creados para su seguimiento
`Warnings`	array	Cualquier advertencia generada durante el procesamiento
`UnknownDevices`	object	Dispositivos que no se pudieron encontrar
`UnknownUsers`	object	IDs de usuario que no se pudieron resolver
`FailedDevices`	object	Dispositivos que fallaron durante el procesamiento
`UnknownPhoneNumbers`	object	Números de teléfono que no se pudieron encontrar

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

Mensajes de error comunes

Mensaje de error	Causa
`Missing required parameter: send_date`	El campo `send_date` no se proporciona en la notificación
`Missing required parameter: devices or users`	No se proporciona ni el array `devices` ni el de `users`
`Invalid Kakao devices list`	A uno o más tokens de dispositivo les falta el prefijo `kakao:`
`Invalid parameter: platforms`	Se intentó establecer las plataformas manualmente (no permitido)
`Kakao template is required`	No se proporcionó el nombre de la plantilla
`Invalid Kakao template`	La plantilla especificada no existe
`Kakao template not approved`	La plantilla existe pero no está aprobada por Kakao
`Please configure Kakao platform`	La aplicación no tiene las credenciales de Kakao configuradas

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

Ejemplos de código

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

Ejemplo: Envío a usuarios en lugar de a dispositivos

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

Ejemplo: Mensaje programado

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