kakao-channel-chat

No oficial. Es una ingeniería inversa de la API interna no documentada del Centro de administración de canales de Kakao (chat empresarial, nombre en clave interno "rocket"). No es un producto oficial de Kakao; la especificación puede cambiar sin previo aviso y romperse, y puede contravenir los términos de uso de Kakao. Úselo bajo su responsabilidad, para automatización de canales de su propiedad. Más detalles en DISCLAIMER.

Kit de herramientas Node para manejar por código el chat del canal de Kakao reutilizando la sesión ya iniciada del navegador. Se ofrece en tres formatos: biblioteca de API · CLI · servidor MCP. La única dependencia de runtime externa es el SDK de MCP (la biblioteca/CLI tiene 0 dependencias).

Lo que hace

• ✅ Comprobación del estado de inicio de sesión y refresco infinito de tokens (la sesión no se corta)

• ✅ Lista de salas de chat + distinción leído/no leído + deep link a la sala

• ✅ Consulta del historial de conversación (distinción de mensajes nuestros/del cliente/del sistema, extracción de enlaces)

• ✅ Marcar como leído, envío de mensajes (respuestas)

• ✅ Vigilancia de nuevos mensajes en tiempo real (SSE / polling)

• ✅ Demonio permanente (renovación automática de tokens + keepalive + vigilancia + respuesta automática opcional)

• ✅ Servidor MCP — uso como herramienta en Claude/Cursor, etc.

Related MCP server: @chatmaid/mcp

Principio de funcionamiento

La API de chat del canal de Kakao (business.kakao.com/api/*) se autentica solo con la cookie de inicio de sesión de kakao (no se necesita token aparte). Esta herramienta obtiene una cookie de sesión kakao válida y llama directamente a esa API. Consulte el mapa completo de endpoints invertidos en API.md.

3 métodos de autenticación (elija uno)

1) Extracción automática de macOS + Chrome (predeterminado) Si solo ha iniciado sesión en Chrome con el canal de destino, la sesión se extrae automáticamente del almacén de cookies (incluidas las HttpOnly). No se necesita configuración adicional.

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

2) Inicio de sesión propio con Playwright (multiplataforma · headless · recomendado) La herramienta inicia sesión con su propio navegador y conserva la sesión → funciona incluso sin macOS, también en servidores. La 2FA/captcha solo se gestiona manualmente la primera vez.

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

• La sesión se guarda en .kbc-auth/state.json (gitignore). El daemon toca el sitio periódicamente para mantener la sesión activa.

• Reinicio de sesión automático: si la sesión se pierde por completo, el demonio lo detecta → vuelve a abrir el navegador de inicio de sesión (solo gestiona la 2FA manualmente) → recuperación automática. En headless/servidor, si vuelve a ejecutar kbc login, el demonio recoge automáticamente la nueva sesión y se recupera sin reiniciar.

3) Inyección directa de cookies

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

(DevTools del navegador → Network → copiar el encabezado Cookie de la petición, o "Copy as cURL")

Requisitos

• Node ≥ 20.12

• Para usar la extracción automática de cookies: macOS + Google Chrome con la sesión iniciada en el canal kakao de destino (internamente usa /usr/bin/sqlite3 + Keychain, incluidos de serie en macOS)

• Otros SO/navegadores: se puede usar con inyección manual de KBC_COOKIE

Instalación

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=...               # (선택) 쿠키 자동추출 대신 직접 주입

Uso de la CLI

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      # + 안읽은 새 메시지 자동응답

Uso como biblioteca

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, '답장');              // ⚠️ 실발송
}

Vigilancia en tiempo real:

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

Servidor MCP

Añadir a la configuración de MCP de Claude Code / Claude Desktop / Cursor, etc.:

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

Herramientas expuestas: kakao_login_status, kakao_unread_count, kakao_list_chats, kakao_get_chat, kakao_get_messages, kakao_mark_read. La herramienta de envío (kakao_send_message) está desactivada por defecto por seguridad — añada KBC_MCP_ALLOW_SEND=1 al env para exponerla.

Ejecución permanente (PM2)

Renueva automáticamente el token antes de que expire y mantiene la sesión viva para que no se corte. Reinicio automático en caso de caída:

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

El método de extracción automática de cookies de macOS requiere que Chrome permanezca con la sesión iniciada para que la sesión se mantenga indefinidamente (Chrome renueva las cookies automáticamente). Para ejecutarlo completamente headless sin Chrome, debe renovar KBC_COOKIE periódicamente o implementar por separado el flujo de refresco de SSO de kakao.

Seguridad / Avisos

• Política de seguridad detallada en SECURITY.md — especifica a qué accede y a qué no.

• Las cookies y tokens existen solo localmente y no se envían al exterior (la comunicación es solo con dominios de Kakao).

• Nunca haga commit de .env ni de las cookies (incluidos en .gitignore).

• send/--autoreply se entregan inmediatamente a clientes reales.

• Úselo solo en canales de su propiedad.

Licencia

MIT — LICENSE. Kakao/KakaoTalk son marcas comerciales de Kakao Corp. y no están relacionadas con este proyecto.