API de Kakao

createKakaoMessage

Utilice este endpoint 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 de 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 estar registrados 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 desde el 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:` (p. ej., `"kakao:user_token"`).
users*	Requerido si no se proporciona `devices`	array[string]	Lista de ID 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 como resultado un error de validación:

platforms: La plataforma se establece automáticamente en Kakao
filter: No se admite el filtrado de dispositivos
filter_code: No se admiten los códigos de filtro
conditions: No se admite la segmentación condicional

Ejemplo de solicitud

{
  "request": {
    "auth": "your-api-access-token",        // requerido. Token de acceso a la API desde el 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. ID 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 ID de mensajes creados para el seguimiento
`Warnings`	array	Cualquier advertencia generada durante el procesamiento
`UnknownDevices`	object	Dispositivos que no se pudieron encontrar
`UnknownUsers`	object	ID 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": "Descripción del error"
}

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": "Error interno del servidor"
}

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