kakao-channel-chat

Inoffiziell. Dies ist ein Reverse-Engineering der undokumentierten internen APIs des Kakao-Kanal-Managerzentrums (Business-Chat, interner Codename „rocket“). Es ist kein offizielles Produkt von Kakao; die Spezifikation kann sich ohne Vorankündigung ändern, unter Umständen brechen und gegen die Nutzungsbedingungen von Kakao verstoßen. Verwenden Sie es nur zur Automatisierung von Kanälen, die Ihnen selbst gehören, und on Ihre eigene Verantwortung. Weitere Details finden Sie unter DISCLAIMER.

Ein Node-Toolkit, das die angemeldete Browser-Sitzung wiederverwendet, um Kakao-Kanal-Chats mittels Code zu bearbeiten. Es ist in drei Formaten verfügbar: API-Bibliothek · CLI · MCP-Server. Die einzige externe Laufzeitabhängigkeit ist das MCP-SDK (Bibliothek/CLI: 0 Abhängigkeiten).

Funktionen

• ✅ Anmeldestatus prüfen & unbegrenzter Token-Refresh (die Sitzung bleibt bestehen)

• ✅ Chatroom-Liste – mit Gelesen-/Ungelesen-Unterscheidung und Deep-Link zu den Räumen

• ✅ Konversationsverlauf abrufen (Unterscheidung unserer-/Kunden-/Systemnachrichten, Link-Extraktion)

• ✅ Als gelesen markieren, Nachrichten senden (Antworten)

• ✅ Echtzeit-Überwachung neuer Nachrichten (SSE / Polling)

• ✅ Dauerhafter Daemon (automatischer Token-Refresh + Keepalive + Überwachung + optionales Auto-Reply)

• ✅ MCP-Server – als vollwertiges Tool in Claude, Cursor usw. nutzbar

Related MCP server: @chatmaid/mcp

Funktionsweise

Die Kakao-Kanal-Chat-API (business.kakao.com/api/*) wird nur mit dem Kakao-Login-Cookie authentifiziert, benötigt kein separates Token. Dieses Tool holt sich ein gültiges Kakao-Sitzungs-Cookie und ruft die API direkt auf. Die vollständige Karte der „vor Reverse-Engineering“ erhaltenen Endpunkte finden Sie in API.md.

Drei Authentifizierungsmöglichkeiten (eine auswählen)

1) macOS + Chrome – automatischer Cookie-Abdruck (Standard) Wenn Chrome nur mit einem der Zielkanäle eingloggt ist, werden die Sitzungen automatisch aus dem Cookie-Speicher geholt (httponly). Eine Einrichtung ist nicht erforderlich.

node bin/kbc.js whoami   # 그냥 실행하면 됨(macOS)

2) Playwright eigenes Login (Systemübergreifend · headled - empfohlen) Das Tool meldet sich in einem eigenes Browserfert intern an? Nein – gehalten: Das Tool meldet sich in einem eigenem Browserfert, sitzungen werden gehalten → funktioniert auch unter nichtmacOS und auf Servern. 2FA/Captcha muss nur unabhängig manuell ausgeführt werden.

npm i playwright && npx playwright install chromium
node bin/kbc.js login          # 브라우저가 열림 → 카카오 로그인(2FA 포함) → 세션 저장
KBC_AUTH=playwright node bin/kbc.js whoami   # 이후 저장된 세션 사용

• Die Sitzung wird in .kbc-auth/.json (gitignore) gespeichert. daemon besucht den Stand regelmäßig, damit die Sitzung nicht abläuft.

• Auto-Relogin – Die Sitzung komplett abläuft, erkennt der daemon, offene dann den Login-Browser von neuem (nur 2FA manuell) und stellt wieder her. Für headless/server sortieren einStart kbc login reicht aus: Der daemon übernimmt die neue Sitzung automatisch, ohne restart. Er schickt automatically.

3) Cookie direkt angeben

KBC_COOKIE="_kawlt=...; _kawltea=...; ..." node bin/kbc.js whoami

(Im Browser DevTools → Network → Cookie-Header der Anfrage kopieren oder **"Copy as cURL"*.)

Voraussetzungen

• Node ≥ 20.12

• Cookie-Auto-Extraktion macOS: + Google Chrome in dem Ziel-Kakao-Kanal login (Nordphoo (/usr/bin/sqlite3 + Keychain genutzt werden, in bereits installiert in macOS eingebaut).

• Für Andere Betriebssysteme/Browser: KBC_COOKIE manuelle angesteckt nutzbar.

Installation

git clone <this-repo>
cd kakao-channel-chat
npm install
cp .env.example .env      # KBC_PROFILE_ID 채워넣기

.env:

KBC_PROFILE_ID=_XXXXX     # 관리자센터 URL business.kakao.com/{이값}/chats 의 {이값}
# KBC_CHROME_PROFILE=Default   # (선택) 여러 Chrome 프로필 중 지정. 미지정 시 자동탐지
# KBC_COOKIE=...               # (선택) 쿠키 자동추출 대신 직접 주입

n CLI-Nutzung

node bin/kbc.js whoami                 # 로그인 상태
node bin/kbc.js token                  # 토큰 리프레시(무한로그인 확인)
node bin/kbc.js unread                 # 안읽은 방 (링크 포함)
node bin/kbc.js list --json            # 전체 방 (JSON)
node bin/kbc.js logs <chatId>          # 대화내역
node bin/kbc.js mark <chatId>          # 읽음 처리
node bin/kbc.js send <chatId> "<text>" --yes    # ⚠️ 실제 발송
node bin/kbc.js watch --poll           # 실시간 감시
node bin/kbc.js daemon                  # 상시 구동(토큰 무한유지+감시)
node bin/kbc.js daemon --autoreply      # + 안읽은 새 메시지 자동응답

Anwendung der Bibliothek

import { KakaoBizChatClient } from './src/client.js';

const c = new KakaoBizChatClient({ profileId: process.env.KBC_PROFILE_ID }); // 쿠키 자동
if ((await c.checkLogin()).loggedIn) {
  const unread = await c.getUnreadChats();               // is_read=false 방들 (+ .link)
  const { items } = await c.getChatlogs(unread[0].id);   // 대화내역 (.from = 'us'|'customer')
  await c.markRead(unread[0].id);
  // await c.sendText(unread[0].id, '답장');              // ⚠️ 실발송
}

Echtzeit-Überwachung:

import { watchPolling, watchSSE } from './src/push.js';
watchPolling(c, { onMessage: ({ chat }) => console.log('새 메시지', chat.name, chat.last_message) });

MCP-Server

In der MCP-Konfiguration von Claude Code / Claude Desktop / Cursor usw. einrichten:

{
  "mcpServers": {
    "kakao-channel": {
      "command": "node",
      "args": ["/absolute/path/to/kakao-channel-chat/src/mcp-server.js"],
      "env": {
        "KBC_PROFILE_ID": "_XXXXX",
        "KBC_CHROME_PROFILE": "Default"
      }
    }
  }
}

Verfügebare Tools: kakao_login_status, kakao_unread_count, kakao_list_chats, kakao_get_messages, kakao_mark_read.
Das Sendewerkzeug (kakao_send_message) ist aus Sicherheitsgründen standardmäßig deaktiviert — „ angebot_kakao_mcp“.

Dauerbetrieb (PM2)

Erneuert das Tokenzeits automatisch vor Ablauf und hält dem die Sitzung am Leben, so dass die Verbindung nicht bricht bleibt. Bei Absturz startet er sich automatisch erneut:

npm i -g pm2
pm2 start ecosystem.config.cjs
pm2 logs kakao-channel
pm2 save && pm2 startup   # 부팅 시 자동 실행

Bei macOS read Cookie-Methode muss Chrome zusätzlich eingeloggt bleiben damit die Sitzung unbegrenzt erhalten bleibt (die Cookies von Chrome werden selbst erneuert). Für volle Headless-Laufzeiten ohne Chrome KBC_COOKIE regelmäßig erneuern oder einen eigenen Kakao-SSO-Refresh-Flow implementieren.

Sicherheit / Hinweise

• Ausführliche Informationen in SECURITY.md – und was zugegriffen wird und was nicht.

• Cookies und Token befinden sich nur lokal und werden an niemanden übertragen (Kommunikation ausschließlich mit Kakao-Domains).

• .env und Cookies niemals committen (in .gitignore enthalten).

• send/--autoreply werden sofort an echten Kunden übermittelt.

• Nur eigenen Kanäle verwenden.

Lizenz

MIT – LICENSE. Kakao/Hakao-Delikte sind Marken von Kakao-Corp und stehen in Kee, and mit diesem Projekt keinem Zusammenhang.