KakaoTalk

Alle ConnectorsPosteingangKakaoTalk

Checkliste für die Einrichtung#

Die KakaoTalk-Karte in Make Agent Fast zeigt diese Liste bereits mit Ihren eigenen Werten an, sodass die meisten Owner sie dort abarbeiten. Alle Schritte finden in der Kakao-Konsole statt, mit Ausnahme der beiden unten markierten Felder.

1. Erstellen Sie einen Bot in Kakao i Open Builder. Ein Bot enthält alle Szenarioblöcke, mit denen der Channel antwortet; überspringen Sie diesen Schritt, wenn der Channel bereits über einen Bot verfügt, den Sie bearbeiten können.
2. Fügen Sie einen Skill hinzu und legen Sie als URL die Skill-URL des Connectors fest. Ergänzen Sie dann einen benutzerdefinierten Request-Header X-Kakao-Bot-Secret mit Ihrem Bot-Secret. Kakao signiert Skill-Anfragen nicht, daher ist dieser Header der einzige Nachweis, dass ein Aufruf von Ihrem Bot stammt.
3. Richten Sie den Fallback-Block auf den Skill aus, sodass jede Frage, die Ihre Szenarien nicht behandeln, beim Agent ankommt. Verknüpfen Sie einen benannten Szenarioblock mit demselben Skill, wenn auch dieser vom Agent beantwortet werden soll.
4. Aktivieren Sie die Callback-Option für diesen Block. Kakao verwirft eine Skill-Antwort, die länger als fünf Sekunden dauert. Bei aktiviertem Callback gibt Make Agent Fast sofort eine Wartenachricht zurück und sendet die fertige Antwort innerhalb der Minute, in der wir diese einmalig verwendbare URL als gültig behandeln, an userRequest.callbackUrl.
5. Verbinden Sie den KakaoTalk Channel mit dem Bot und fügen Sie dieselbe Channel-ID anschließend in das Feld Channel-ID des Connectors in Make Agent Fast ein.
6. Stellen Sie den Bot bereit (Deploy). Änderungen in Open Builder erreichen Besucher erst nach einem Deploy, und jede spätere Änderung an einem Skill oder Block erfordert einen weiteren.

Der Rest dieser Seite ist die ausführliche Fassung derselben sechs Schritte.

Kakao-Ressourcen vorbereiten#

Erstellen oder wählen Sie die Kakao-Developers-Anwendung, den KakaoTalk Channel und den Kakao i Open Builder Bot aus, die die Integration tragen sollen. Informationen zu Skills und Blöcken finden Sie in Kakaos offizieller Open-Builder-Dokumentation.

Sammeln oder erstellen Sie diese Werte:

Das Bot-Secret ist in bereitgestellten Make-Agent-Fast-Umgebungen erforderlich, weil Kakao-Skill-Aufrufe keine Plattformsignatur mitliefern. Erzeugen Sie einen eindeutigen Wert mit hoher Entropie und verwenden Sie den REST-API-Schlüssel nicht als Secret.

Connector speichern#

Öffnen Sie die Seite Channels des Agents, wählen Sie KakaoTalk Channel, geben Sie alle drei Werte ein und klicken Sie auf Verbinden. Make Agent Fast validiert den REST-API-Schlüssel, soweit die Kakao-Berechtigungen dies zulassen, und zeigt nach dem Speichern die eindeutige Webhook-URL des Connectors an.

Make Agent Fast kann den Open-Builder-Skill nicht für Sie erstellen oder mit einem Block verknüpfen; die restlichen Schritte erledigen Sie in der Kakao-Konsole.

Open-Builder-Skill konfigurieren#

1. Erstellen Sie in Kakao i Open Builder einen Skill für den vorgesehenen Bot.
2. Legen Sie als Skill-URL die kopierte Webhook-URL des Connectors fest.
3. Fügen Sie einen benutzerdefinierten Request-Header namens X-Kakao-Bot-Secret hinzu, dessen Wert exakt dem Bot-Secret entspricht.
4. Verknüpfen Sie den Skill mit dem Fallback- oder Szenarioblock, der den Agent aufrufen soll.
5. Aktivieren Sie die Callback-Option dieses Blocks, damit langsame Antworten Kakaos Skill-Frist von fünf Sekunden überstehen.
6. Speichern Sie die Bot-Konfiguration und stellen Sie sie gemäß Kakaos Ablauf bereit bzw. veröffentlichen Sie sie.

Beim Header wird laut HTTP-Regeln die Groß- und Kleinschreibung nicht unterschieden, der Wert des Secrets muss jedoch exakt stimmen. Wer die Webhook-URL kennt, nicht aber dieses Secret, sollte eine Antwort „unauthorized“ erhalten.

Funktionen testen#

Verwenden Sie zuerst das Testtool von Open Builder und anschließend den verbundenen KakaoTalk Channel. Senden Sie eine realistische Textfrage auf Koreanisch oder in einer anderen unterstützten Sprache und prüfen Sie die Inline-Antwort, die Letzte Nachricht sowie den Thread unter Unterhaltungen.

Die Connector-Karte kopiert den unten stehenden Request-Body; derselbe Body funktioniert mit curl gegen die Skill-URL. Er enthält keine callbackUrl, die Antwort kommt also inline zurück – das ist die einfachere Variante für den ersten Test.

{
  "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": {}
  }
}

Ein funktionierender Skill antwortet innerhalb der Fünf-Sekunden-Frist mit einer einzelnen simpleText-Ausgabe:

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

Sobald die Callback-Option des Blocks aktiviert ist, fügt Open Builder der Anfrage userRequest.callbackUrl hinzu. Make Agent Fast antwortet dann zunächst mit einer Wartenachricht und sendet die fertige Antwort per POST an diese einmalig verwendbare URL:

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

Der aktuelle Skill-Vertrag unterstützt nur Text. Die Antwort des Agents ist eine einzelne Kakao-skillResponse in Version 2.0 mit einer simpleText-Ausgabe, die unterhalb von Kakaos Textlimit bleibt und inline oder an die Callback-URL zurückgegeben wird. Sprache, Dateien, Bilder und separate ausgehende Audioinhalte werden nicht unterstützt.

Rotieren oder trennen#

Um das Bot-Secret zu rotieren, aktualisieren Sie den Connector und den benutzerdefinierten Header in Open Builder in einem abgestimmten Schritt und testen Sie anschließend sofort. Eine Abweichung blockiert jede eingehende Anfrage. Rotieren Sie den REST-API-Schlüssel in Kakao Developers und in Make Agent Fast, bevor Sie den alten Schlüssel widerrufen.

Das Deaktivieren oder Entfernen des Connectors löscht weder den Open-Builder-Skill noch den Block. Entfernen oder lösen Sie diese Objekte auf Anbieterseite, wenn Sie die Integration dauerhaft außer Betrieb nehmen.

Fehlerbehebung#

Machen Sie den REST-API-Schlüssel und das Bot-Secret weder in Client-Code noch in öffentlicher Dokumentation zugänglich.