kakao-channel-chat

Неофициальный (Unofficial). Это реверс-инжиниринг недокументированного внутреннего API Центра управления каналами Kakao (бизнес-чат, внутреннее кодовое имя "rocket"). Это не официальный продукт Kakao; спецификация может измениться без предупреждения и сломаться, а также может противоречить условиям использования Kakao. Используйте на свой страх и риск для автоматизации собственных каналов. Подробнее см. DISCLAIMER.

Node-инструментарий для работы с чатами каналов Kakao через код, повторно использующий сессию браузера с выполненным входом. Предоставляется в трёх формах: библиотека API · CLI · MCP-сервер. Единственная внешняя зависимость — MCP SDK (у библиотеки/CLI зависимостей 0).

Возможности

• ✅ Проверка статуса входа и бесконечное обновление токена (сессия не прерывается)

• ✅ Список чатов + разделение прочитанных/непрочитанных + диплинки на комнаты

• ✅ Просмотр истории переписки (разделение наших/клиентских/системных сообщений, извлечение ссылок)

• ✅ Отметка о прочтении, отправка сообщений (ответы)

• ✅ Мониторинг новых сообщений в реальном времени (SSE / polling)

• ✅ Постоянный демон (автообновление токена + keepalive + мониторинг + опциональный автоответ)

• ✅ MCP-сервер — использование как инструмента в Claude/Cursor и др.

Related MCP server: @chatmaid/mcp

Принцип работы

API чатов каналов Kakao (business.kakao.com/api/*) аутентифицируется только cookie входа kakao (отдельный токен не нужен). Этот инструмент получает действительную cookie сессии kakao и напрямую вызывает этот API. Полную карту реверс-инжиниринга эндпоинтов см. в API.md.

3 способа аутентификации (выберите один)

1) macOS + автоматическое извлечение из Chrome (по умолчанию) Если в Chrome выполнен вход в целевой канал, сессия автоматически извлекается из хранилища cookie (включая HttpOnly). Дополнительная настройка не требуется.

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

2) Собственный вход через Playwright (кроссплатформенный · headless · рекомендуется) Инструмент выполняет вход в собственном браузере и хранит сессию → работает не только на macOS, но и на сервере. 2FA/капчу нужно пройти вручную только один раз при первом входе.

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

• Сессия сохраняется в .kbc-auth/state.json (gitignore). daemon периодически обращается к сайту, чтобы сессия не истекала.

• Автоматический повторный вход: если сессия полностью истекла, демон это обнаруживает → снова открывает браузер входа (вручную обрабатывается только 2FA) → автоматическое восстановление. В headless-режиме/на сервере повторный запуск kbc login позволит демону автоматически подхватить новую сессию и восстановиться без перезапуска.

3) Прямая инъекция cookie

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

(DevTools браузера → Network → скопируйте заголовок Cookie запроса или используйте «Copy as cURL»)

Требования

• Node ≥ 20.12

• Для автоматического извлечения cookie: macOS + Google Chrome с выполненным входом в целевой канал Kakao (внутри использует /usr/bin/sqlite3 + Keychain, встроено в macOS)

• Другие ОС/браузеры: можно использовать с ручной инъекцией KBC_COOKIE

Установка

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

Использование 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      # + 안읽은 새 메시지 자동응답

Использование библиотеки

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

Мониторинг в реальном времени:

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

MCP-сервер

Добавьте в настройки MCP в Claude Code / Claude Desktop / Cursor и др.:

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

Доступные инструменты: kakao_login_status, kakao_unread_count, kakao_list_chats, kakao_get_chat, kakao_get_messages, kakao_mark_read. Инструмент отправки (kakao_send_message) по умолчанию отключён из соображений безопасности — он будет доступен, если добавить KBC_MCP_ALLOW_SEND=1 в env.

Постоянная работа (PM2)

Автоматически обновляет токен до истечения срока и поддерживает сессию, чтобы не прерывалась работа. Автоматический перезапуск при сбое:

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

Способ автоматического извлечения cookie на macOS требует, чтобы Chrome оставался в состоянии входа, и тогда сессия поддерживается бесконечно (Chrome автоматически обновляет cookie). Для полностью headless-работы без Chrome необходимо периодически обновлять KBC_COOKIE или отдельно реализовать поток обновления kakao SSO.

Безопасность / внимание

• Подробная политика безопасности — в SECURITY.md: указано, к чему есть доступ, а к чему нет.

• Cookie и токены существуют только локально и не передаются наружу (связь только с доменами Kakao).

• Никогда не коммитьте .env и cookie (они включены в .gitignore).

• send/--autoreply немедленно доставляются реальным клиентам.

• Используйте только для собственных каналов.

Лицензия

MIT — LICENSE. Kakao/KakaoTalk — товарные знаки Kakao Corp. и не связаны с этим проектом.