Chat SDK: 한 로직을 여러 채팅 플랫폼에 배포하기

누구에게 맞나

같은 TypeScript 로직으로 Slack, Microsoft Teams, Google Chat, Discord, Telegram, GitHub, Linear, WhatsApp 같은 플랫폼에 챗봇을 만들 때 Chat SDK를 사용한다. 봇 로직을 한 번 쓰고 곳곳에 배포하는 것을 강조하며, 플랫폼마다 이름 없는 프레임워크를 따로 쓰는 것이 아니다.

더 알맞은 전제는 Node / TypeScript 프로젝트에 핵심 패키지를 넣고 이어서 해당 플랫폼 adapter를 넣을 준비가 되어 있다는 것이다. 자료는 이들 플랫폼을 배타적 명단으로 쓰지 않으며 뒤에 and more가 있다. 공식 설명 페이지는

https://github.com/vercel/chat

3분 안에 첫 시도 끝내기

권장하는 첫 경로는 핵심 패키지 설치이며 설치기 세 개를 동시에 열지 말 것:

npm i chat

전제: 이 머신에 이미 npm이 있다. 이 명령은 package.json과 node_modules를 바꾸므로 현재 디렉터리가 봇 프로젝트인지 먼저 확인한다. 설치 후 읽기 전용으로 확인한다: 자료의 가져오기를 스크립트에 쓴다. 아직 실제 워크스페이스에 연결하지 말고 밖으로 메시지도 보내지 말 것.

import { Chat } from "chat";
import { createSlackAdapter } from "@chat-adapter/slack";
import { createRedisState } from "@chat-adapter/state-redis";

성공 신호: 핵심 패키지를 가져올 수 있다. adapter는 플랫폼별로 추가 설치가 필요하며 발췌는 Install one or more adapters for your platforms라고 적는다. 요약은 예를 들어 @chat-adapter/slack을 지목한다. adapter 가져오기가 실패하면 누락 의존성에서 멈추고 다른 패키지 이름을 지어내지 말 것.

같은 페이지에는 npx skills add vercel/chat과 npx create-chat-sdk@latest my-bot도 나온다. 첫 시도에서 스캐폴드를 병렬로 돌리지 말 것. 프로젝트 파일이 생기므로 디렉터리 이름 my-bot이 기존 폴더를 덮어쓰지 않는지 먼저 확인한다.

사용 사례

사례 1: 기존 TypeScript 프로젝트에 Slack을 붙인다. 먼저 npm i chat, 그다음 Slack adapter를 설치한 뒤 Chat, createSlackAdapter, createRedisState로 인스턴스를 조립한다. 요약은 onNewMention과 onSubscribedMessage 처리도 언급하지만 발췌는 두 콜백의 완전한 함수 본문을 쓰지 않는다. 이 사례의 완료 기준은 가져오기와 조립 성공이며 Slack에서 이미 회신한 것이 아니다. Redis에 연결하거나 webhook을 등록하기 전에 연결 대상과 라우트가 잘못된 환경에 쓰이지 않는지 확인한다.

사례 2: 공식 스캐폴드로 새 bot 디렉터리를 만든다. 명령은 npx create-chat-sdk@latest my-bot. 요약은 Chat 설정, webhook 라우트, .env.example을 생성한다고 한다. 디스크 쓰기이므로 my-bot 디렉터리가 없거나 덮어써도 되는지 확인한 뒤 실행한다. 완료 기준은 디렉터리가 만들어지고 생성물을 볼 수 있는 것이다. .env.example에 자리 표시자 밖의 가짜 비밀을 넣지 말고, 설정을 바꾸기 전에 외부 서비스를 시작하지 말 것. 자료는 환경 변수 이름을 쓰지 않으므로 지어내지 말 것.

사용 경계

핵심 설치는 npm i chat이며 플랫폼 능력은 adapter에 달려 있다. 가져오기 예는 Slack adapter와 Redis state만 준다. 스캐폴드와 agent skill 설치는 나란히 나오는 다른 입구이므로 핵심 패키지 설치와 반드시 같이 실행하는 한 단계로 섞지 말 것.

목록의 모든 플랫폼에 이미 적힌 adapter 패키지 이름이 있다고 가정하지 말 것. 자료는 클라이언트 목록도, adapter 없이 Teams나 WhatsApp에 바로 치는 방법도 쓰지 않는다. 여기에 적힌 설치, 가져오기, 스캐폴드 명령을 넘는 범위는 이 설명이 다루지 않는다.