KakaoTalk

Tous les connecteursBoîte de réceptionKakaoTalk

Liste de contrôle de la configuration#

La carte KakaoTalk de Make Agent Fast affiche cette liste avec vos propres valeurs déjà renseignées ; la plupart des propriétaires la suivent donc directement depuis cette carte. Toutes les étapes se déroulent dans la console de Kakao, à l'exception des deux champs indiqués ci-dessous.

1. Créez un bot dans Kakao i Open Builder. Un bot regroupe tous les blocs de scénario avec lesquels la chaîne répond ; ignorez cette étape si la chaîne dispose déjà d'un bot que vous pouvez modifier.
2. Ajoutez une skill et définissez son URL sur l'URL de la skill du connecteur, puis ajoutez un en-tête de requête personnalisé X-Kakao-Bot-Secret contenant votre Secret du bot. Kakao ne signe pas les requêtes de skill : cet en-tête est donc la seule preuve qu'un appel provient bien de votre bot.
3. Faites pointer le bloc de repli vers la skill afin que chaque question non gérée par vos scénarios parvienne à l'agent. Reliez un bloc de scénario nommé à la même skill si l'agent doit aussi y répondre.
4. Activez l'option de rappel (callback) pour ce bloc. Kakao abandonne une réponse de skill qui met plus de cinq secondes à arriver ; avec le callback activé, Make Agent Fast renvoie immédiatement une bulle d'attente, puis publie la réponse finale sur userRequest.callbackUrl dans la minute pendant laquelle cette URL à usage unique reste valide.
5. Connectez la chaîne KakaoTalk au bot, puis collez ce même identifiant de chaîne dans le champ ID de la chaîne du connecteur dans Make Agent Fast.
6. Déployez le bot. Les modifications d'Open Builder n'atteignent les visiteurs qu'après un déploiement, et chaque modification ultérieure d'une skill ou d'un bloc nécessite un nouveau déploiement.

Le reste de cette page détaille ces mêmes six étapes.

Préparer les éléments Kakao#

Créez ou sélectionnez l'application Kakao Developers, la chaîne KakaoTalk et le bot Kakao i Open Builder qui hébergeront l'intégration. Consultez la documentation officielle d'Open Builder de Kakao pour les skills et les blocs.

Rassemblez ou créez ces valeurs :

Le Secret du bot est obligatoire sur les environnements Make Agent Fast déployés, car les appels de skill Kakao ne fournissent aucune signature de plateforme. Générez une valeur unique à forte entropie et ne réutilisez pas la clé d'API REST comme secret.

Enregistrer le connecteur#

Ouvrez la page Canaux de l'agent, choisissez Chaîne KakaoTalk, saisissez les trois valeurs, puis sélectionnez Connecter. Make Agent Fast valide la clé d'API REST lorsque les autorisations de Kakao le permettent et affiche l'URL du webhook propre au connecteur après l'enregistrement.

Make Agent Fast ne peut pas créer la skill Open Builder ni la rattacher à un bloc à votre place ; le reste du travail s'effectue dans la console de Kakao.

Configurer la skill Open Builder#

1. Dans Kakao i Open Builder, créez une skill pour le bot concerné.
2. Définissez l'URL de la skill sur l'URL du webhook copiée depuis le connecteur.
3. Ajoutez un en-tête de requête personnalisé nommé X-Kakao-Bot-Secret dont la valeur correspond exactement au Secret du bot.
4. Reliez la skill au bloc de repli ou au bloc de scénario qui doit invoquer l'agent.
5. Activez l'option de rappel (callback) de ce bloc afin que les réponses lentes respectent le délai de cinq secondes imposé par Kakao aux skills.
6. Enregistrez, puis déployez/publiez la configuration du bot en suivant le processus de Kakao.

L'en-tête n'est pas sensible à la casse selon les règles HTTP, mais la valeur du secret doit être exacte. Toute personne qui connaît l'URL du webhook sans connaître ce secret doit recevoir une réponse « non autorisé ».

Tester les fonctionnalités#

Utilisez d'abord l'outil de test d'Open Builder, puis la chaîne KakaoTalk connectée. Envoyez une question textuelle réaliste en coréen ou dans une langue prise en charge, puis vérifiez la réponse en ligne, le Dernier message et le fil dans Conversations.

La carte du connecteur copie le corps de requête ci-dessous ; ce même corps fonctionne avec curl sur l'URL de la skill. Il ne contient aucun callbackUrl, la réponse revient donc en ligne — c'est le plus simple à vérifier en premier.

{
  "intent": {
    "id": "5a56ec0cf65e53002d34e0f4",
    "name": "Fallback block"
  },
  "userRequest": {
    "timezone": "Asia/Seoul",
    "utterance": "What are your opening hours?",
    "lang": "kr",
    "user": {
      "id": "kakao-test-user",
      "type": "botUserKey",
      "properties": {
        "plusfriendUserKey": "kakao-test-user"
      }
    },
    "block": {
      "id": "5a56ec0cf65e53002d34e0f4",
      "name": "Fallback block"
    }
  },
  "bot": {
    "id": "5a56ec0cf65e53002d34e0f2",
    "name": "Your bot"
  },
  "action": {
    "id": "5a56ec0cf65e53002d34e0f6",
    "name": "Make Agent Fast skill",
    "params": {},
    "detailParams": {},
    "clientExtra": {}
  }
}

Une skill en bon état répond dans le délai de cinq secondes avec une seule sortie simpleText :

{
  "version": "2.0",
  "template": {
    "outputs": [
      {
        "simpleText": {
          "text": "We are open 9:00–18:00 on weekdays."
        }
      }
    ]
  }
}

Une fois l'option de rappel du bloc activée, Open Builder ajoute userRequest.callbackUrl à la requête. Make Agent Fast répond alors d'abord avec une bulle d'attente, puis envoie en POST la réponse finale à cette URL à usage unique :

{
  "version": "2.0",
  "useCallback": true,
  "data": {
    "text": "One moment — I am looking that up."
  }
}

Le contrat actuel de la skill est limité au texte. La réponse de l'agent est un seul skillResponse Kakao en version 2.0 avec une sortie simpleText, plafonnée sous la limite de texte de Kakao, renvoyée en ligne ou sur l'URL de rappel. La voix, les fichiers, les images et l'audio sortant distinct ne sont pas pris en charge.

Renouveler ou déconnecter#

Pour renouveler le Secret du bot, mettez à jour le connecteur et l'en-tête personnalisé d'Open Builder en une seule opération coordonnée, puis testez immédiatement. Toute divergence bloque l'ensemble des requêtes entrantes. Renouvelez la clé d'API REST dans Kakao Developers et dans Make Agent Fast avant de révoquer l'ancienne clé.

Désactiver ou supprimer le connecteur ne supprime ni la skill ni le bloc Open Builder. Supprimez ou détachez ces objets côté fournisseur lorsque vous désactivez définitivement l'intégration.

Dépannage#

N'exposez jamais la clé d'API REST ni le Secret du bot dans du code côté client ou dans une documentation publique.