API do Kakao

createKakaoMessage

Usado para enviar mensagens do Kakao para os usuários

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

Pré-requisitos

Antes de usar este endpoint, certifique-se de que:

A plataforma Kakao está configurada: Seu aplicativo Pushwoosh deve ter as credenciais do Kakao configuradas. Saiba mais
Os modelos estão aprovados: Os modelos do Kakao devem ser criados e aprovados antes de poderem ser usados. Saiba mais
Os dispositivos estão registrados: Os dispositivos devem ser registrados com o prefixo kakao: para serem reconhecidos como endpoints do Kakao.

Corpo da solicitação

Nome	Obrigatório	Tipo	Descrição
auth*	Sim	string	Token de acesso à API do Painel de Controle da Pushwoosh.
application*	Sim	string	Código do aplicativo Pushwoosh
notifications*	Sim	array	Array de objetos de notificação. Veja os detalhes abaixo.

Parâmetros de notificação

Nome	Obrigatório	Tipo	Descrição
send_date*	Sim	string	Data e hora para enviar a mensagem. Use o formato `AAAA-MM-DD HH:MM:SS` (UTC) ou `"now"` para enviar imediatamente. Todos os horários são interpretados como UTC.
devices*	Obrigatório se `users` não for fornecido	array[string]	Lista de tokens de dispositivo. Cada token deve ser prefixado com `kakao:` (por exemplo, `"kakao:user_token"`).
users*	Obrigatório se `devices` não for fornecido	array[string]	Lista de IDs de usuário para direcionar.
template*	Sim	string	Nome do modelo do Kakao. Deve ser um modelo pré-aprovado. Saiba mais
kakao_content_variables	Não	object	Pares de chave-valor para substituição de variáveis do modelo. As chaves devem corresponder às variáveis definidas no seu modelo do Kakao. Opcional, mas permite a personalização dinâmica das suas mensagens do Kakao.

Parâmetros proibidos

Os seguintes parâmetros não são permitidos para este endpoint e resultarão em um erro de validação:

platforms: A plataforma é definida automaticamente como Kakao
filter: Filtragem de dispositivos não suportada
filter_code: Códigos de filtro não suportados
conditions: Direcionamento condicional não suportado

Exemplo de solicitação

{
  "request": {
    "auth": "your-api-access-token",        // obrigatório. Token de acesso à API do Painel de Controle da Pushwoosh.
    "application": "XXXXX-XXXXX",           // obrigatório. Código do aplicativo Pushwoosh.
    "notifications": [
      {
        "send_date": "now",                 // obrigatório. AAAA-MM-DD HH:MM:SS (UTC) OU "now".
        "devices": ["kakao:user123@kakao.com", "kakao:device_abc"],  // obrigatório se users não for fornecido. Tokens de dispositivo com prefixo kakao:.
        "users": ["user_001", "user_002"],  // obrigatório se devices não for fornecido. IDs de usuário para direcionar.
        "template": "welcome_message",      // obrigatório. Nome do modelo do Kakao (deve ser pré-aprovado).
        "kakao_content_variables": {        // opcional. Substituição de variáveis do modelo.
          "user_name": "John Doe",
          "order_number": "12345"
        }
      }
    ]
  }
}

Exemplo de resposta

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

Campo	Tipo	Descrição
`Messages`	array[string]	Array de IDs de mensagem criados para rastreamento
`Warnings`	array	Quaisquer avisos gerados durante o processamento
`UnknownDevices`	object	Dispositivos que não puderam ser encontrados
`UnknownUsers`	object	IDs de usuário que não puderam ser resolvidos
`FailedDevices`	object	Dispositivos que falharam durante o processamento
`UnknownPhoneNumbers`	object	Números de telefone que não puderam ser encontrados

{
  "status_code": 210,
  "status_message": "Descrição do erro"
}

Mensagens de erro comuns

Mensagem de Erro	Causa
`Missing required parameter: send_date`	O campo `send_date` não foi fornecido na notificação
`Missing required parameter: devices or users`	Nem o array `devices` nem o `users` foi fornecido
`Invalid Kakao devices list`	Um ou mais tokens de dispositivo estão sem o prefixo `kakao:`
`Invalid parameter: platforms`	Tentativa de definir platforms manualmente (não permitido)
`Kakao template is required`	O nome do modelo não foi fornecido
`Invalid Kakao template`	O modelo especificado não existe
`Kakao template not approved`	O modelo existe, mas não está aprovado pelo Kakao
`Please configure Kakao platform`	O aplicativo não tem as credenciais do Kakao configuradas

{
  "status_code": 500,
  "status_message": "Erro interno do servidor"
}

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

Exemplo: Enviando para usuários em vez 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"
        }
      }
    ]
  }
}

Exemplo: Mensagem agendada

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