# API Kakao

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

<Aside type="caution" title="/createKakaoMessage est obsolète">
Les nouvelles intégrations doivent utiliser l'[API de Messagerie v2](/fr/developer/api-reference/messaging-api-v2/) — passez `platforms: ["KAKAO"]` à `Notify` et utilisez le bloc `kakao` à l'intérieur de `payload.content.localized_content`. Consultez le [guide de migration](/fr/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createkakaomessage).
</Aside>

## createKakaoMessage <Badge text="Obsolète" variant="caution" size="small" />

Utilisez ce point de terminaison pour envoyer des messages Kakao aux utilisateurs.

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

<Aside type="note">
Ce point de terminaison est dédié uniquement à la messagerie Kakao. Pour la messagerie multicanal, utilisez [`/createMessage`](/fr/developer/api-reference/messages-api/).
</Aside>

### Prérequis

Avant d'utiliser ce point de terminaison, assurez-vous que :

1.  **La plateforme Kakao est configurée** : Votre application Pushwoosh doit avoir les identifiants Kakao configurés. [En savoir plus](/fr/developer/first-steps/connect-messaging-services/kakao-configuration/)

2.  **Les modèles sont approuvés** : Les modèles Kakao doivent être créés et approuvés avant de pouvoir être utilisés. [En savoir plus](/fr/product/content/kakao-presets/)

3.  **Les appareils sont enregistrés** : Les appareils doivent être enregistrés avec le préfixe `kakao:` pour être reconnus comme des points de terminaison Kakao.

### Corps de la requête

| Nom <div style="width:180px"></div> | Requis <div style="width:100px"></div> | Type | Description |
| :---- | :---- | :---- | :---- |
| auth\* | Oui | string | [Jeton d'accès API](/fr/developer/api-reference/api-identifiers/#api-access-token) depuis le Panneau de Contrôle Pushwoosh. |
| application\* | Oui | string | [Code d'application Pushwoosh](/fr/developer/api-reference/api-identifiers/#application-code) |
| notifications\* | Oui | array | Tableau d'objets de notification. Voir les détails ci-dessous. |

### Paramètres de notification

| Nom <div style="width:180px"></div> | Requis | Type | Description |
| :---- | :---- | :---- | :---- |
| send_date* | Oui | string | Date et heure d'envoi du message. Utilisez le format `YYYY-MM-DD HH:MM:SS` (UTC) ou `"now"` pour un envoi immédiat. Toutes les heures sont interprétées en UTC. |
| devices* | Requis si `users` n'est pas fourni | array[string] | Liste des jetons d'appareil. Chaque jeton **doit** être préfixé par `kakao:` (par ex., `"kakao:user_token"`). |
| users* | Requis si `devices` n'est pas fourni | array[string] | Liste des ID utilisateur à cibler. |
| template* | Oui | string | Nom du modèle Kakao. Doit être un modèle pré-approuvé. [En savoir plus](/fr/product/content/kakao-presets/) |
| kakao_content_variables | Non | object | Paires clé-valeur pour la substitution des variables du modèle. Les clés doivent correspondre aux variables définies dans votre modèle Kakao. Optionnel mais permet la personnalisation dynamique de vos messages Kakao. |

<Aside type="caution" title="Important">
Vous devez fournir soit `devices` soit `users`. Ne laissez pas les deux vides.
</Aside>

#### Paramètres interdits

Les paramètres suivants ne sont pas autorisés pour ce point de terminaison et entraîneront une erreur de validation :

- `platforms` : La plateforme est automatiquement définie sur Kakao
- `filter` : Le filtrage des appareils n'est pas pris en charge
- `filter_code` : Les codes de filtre ne sont pas pris en charge
- `conditions` : Le ciblage conditionnel n'est pas pris en charge

### Exemple de requête

```json
{
  "request": {
    "auth": "your-api-access-token",        // requis. Jeton d'accès API depuis le Panneau de Contrôle Pushwoosh.
    "application": "XXXXX-XXXXX",           // requis. Code d'application Pushwoosh.
    "notifications": [
      {
        "send_date": "now",                 // requis. YYYY-MM-DD HH:MM:SS (UTC) OU "now".
        "devices": ["kakao:user123@kakao.com", "kakao:device_abc"],  // requis si users n'est pas fourni. Jetons d'appareil avec le préfixe kakao:.
        "users": ["user_001", "user_002"],  // requis si devices n'est pas fourni. ID utilisateur à cibler.
        "template": "welcome_message",      // requis. Nom du modèle Kakao (doit être pré-approuvé).
        "kakao_content_variables": {        // optionnel. Substitution des variables du modèle.
          "user_name": "John Doe",
          "order_number": "12345"
        }
      }
    ]
  }
}
```

### Exemple de réponse

<Tabs>
<TabItem label="200">

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

| Champ | Type | Description |
|-------|------|-------------|
| `Messages` | array[string] | Tableau des ID de message créés pour le suivi |
| `Warnings` | array | Tout avertissement généré pendant le traitement |
| `UnknownDevices` | object | Appareils qui n'ont pas pu être trouvés |
| `UnknownUsers` | object | ID utilisateur qui n'ont pas pu être résolus |
| `FailedDevices` | object | Appareils qui ont échoué pendant le traitement |
| `UnknownPhoneNumbers` | object | Numéros de téléphone qui n'ont pas pu être trouvés |

</TabItem>

<TabItem label="210">

```json
{
  "status_code": 210,
  "status_message": "Description de l'erreur"
}
```

##### Messages d'erreur courants

| Message d'erreur | Cause |
| :---- | :---- |
| `Missing required parameter: send_date` | Le champ `send_date` n'est pas fourni dans la notification |
| `Missing required parameter: devices or users` | Ni le tableau `devices` ni `users` n'est fourni |
| `Invalid Kakao devices list` | Un ou plusieurs jetons d'appareil n'ont pas le préfixe `kakao:` |
| `Invalid parameter: platforms` | Tentative de définir les plateformes manuellement (non autorisé) |
| `Kakao template is required` | Le nom du modèle n'a pas été fourni |
| `Invalid Kakao template` | Le modèle spécifié n'existe pas |
| `Kakao template not approved` | Le modèle existe mais n'est pas approuvé par Kakao |
| `Please configure Kakao platform` | L'application n'a pas les identifiants Kakao configurés |

</TabItem>

<TabItem label="500">

```json
{
  "status_code": 500,
  "status_message": "Erreur interne du serveur"
}
```

</TabItem>
</Tabs>

### Exemples de code

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

### Exemple : Envoi aux utilisateurs au lieu des appareils

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

### Exemple : Message programmé

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