# API de Kakao

import { Badge } from '@astrojs/starlight/components';

<Aside type="caution" title="/createKakaoMessage está obsoleto">
Las nuevas integraciones deberían usar la [API de Mensajería v2](/es/developer/api-reference/messaging-api-v2/) — pase `platforms: ["KAKAO"]` a `Notify` y use el bloque `kakao` dentro de `payload.content.localized_content`. Consulte la [guía de migración](/es/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createkakaomessage).
</Aside>

## createKakaoMessage <Badge text="Obsoleto" variant="caution" size="small" />

Use este endpoint para enviar mensajes de Kakao a los usuarios.

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

<Aside type="note">
Este endpoint está dedicado únicamente a la mensajería de Kakao. Para mensajería multicanal, use [`/createMessage`](/es/developer/api-reference/messages-api/).
</Aside>

### Prerrequisitos

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

1. **La plataforma Kakao está configurada**: Su aplicación de Pushwoosh debe tener las credenciales de Kakao configuradas. [Más información](/es/developer/first-steps/connect-messaging-services/kakao-configuration/)

2. **Las plantillas están aprobadas**: Las plantillas de Kakao deben crearse y aprobarse antes de que puedan ser utilizadas. [Más información](/es/product/content/kakao-presets/)

3. **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 <div style="width:180px"></div> | Requerido <div style="width:100px"></div> | Tipo | Descripción |
| :---- | :---- | :---- | :---- |
| auth\* | Sí | string | [Token de acceso a la API](/es/developer/api-reference/api-identifiers/#api-access-token) del Panel de Control de Pushwoosh. |
| application\* | Sí | string | [Código de aplicación de Pushwoosh](/es/developer/api-reference/api-identifiers/#application-code) |
| notifications\* | Sí | array | Array de objetos de notificación. Vea los detalles a continuación. |

### Parámetros de notificación

| Nombre <div style="width:180px"></div> | Requerido | Tipo | Descripción |
| :---- | :---- | :---- | :---- |
| send_date* | Sí | string | Fecha y hora para enviar el mensaje. Use 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 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](/es/product/content/kakao-presets/) |
| 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. |

<Aside type="caution" title="Importante">
Debe proporcionar `devices` o `users`. No deje ambos vacíos.
</Aside>

#### Parámetros prohibidos

Los siguientes parámetros no están permitidos para este endpoint y resultarán en 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

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

<Tabs>
<TabItem label="200">

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

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `Messages` | array[string] | Array de IDs de mensajes creados para 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 |

</TabItem>

<TabItem label="210">

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

</TabItem>

<TabItem label="500">

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

</TabItem>
</Tabs>

### Ejemplos de código

<Tabs>
<TabItem label="cURL">

```bash
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"
          }
        }
      ]
    }
  }'
```

</TabItem>

<TabItem label="PHP">

```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;
```

</TabItem>

<TabItem label="Python">

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

</TabItem>
</Tabs>

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

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

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