본문으로 건너뛰기

Frogtalk

v1
작성 2026-07-12읽는 시간 10분

유료 SaaS 없이 script 한 줄로 붙이는 텔레그램 상담톡

Frogtalk 동작 구조 — 방문자 위젯이 보낸 메시지가 Vercel 서버리스 함수를 거쳐 Supabase에 먼저 저장되고 텔레그램의 방문자별 토픽으로 전달되며, 운영자 답장은 웹훅으로 돌아와 5초 폴링으로 방문자에게 표시되는 흐름도

이건 뭐예요?​

오늘 소개할 repo(저장소, 코드를 모아두는 온라인 보관함)는 조금 특별합니다. 남이 만든 좋은 도구를 큐레이션하는 게 아니라, 저희가 오늘 직접 만들어서 공개한 자작 오픈소스거든요. 이름은 Frogtalk(프로그톡) — 네, 오토프로그의 그 개구리 맞습니다.

비유로 시작할게요. 동네 가게 문 옆에 "무엇이든 물어보세요" 쪽지함을 하나 달아뒀다고 상상해 보세요. 그런데 이 쪽지함이 보통 물건이 아니에요. 손님이 쪽지를 넣는 순간, 그 쪽지가 사장님 주머니 속 휴대폰으로 바로 배달됩니다. 사장님이 휴대폰에 답을 적으면 그 답장이 다시 가게 앞 쪽지함으로 날아가 손님에게 보여요. 그리고 오간 쪽지 전부가 가게 장부에 복사본으로 차곡차곡 보관됩니다. Frogtalk이 하는 일이 정확히 이거예요. 쪽지함이 사이트 우하단의 상담창, 사장님 휴대폰이 텔레그램, 가게 장부가 Supabase(수파베이스, 무료로 시작할 수 있는 온라인 데이터베이스 서비스)입니다.

한 줄로 줄이면 이렇습니다. 채널톡 같은 유료 상담 SaaS(사스, 매달 돈 내고 빌려 쓰는 소프트웨어) 없이, 가벼운 사이트에 script 태그(웹페이지에 기능을 심는 HTML 한 줄) 하나로 붙이는 텔레그램 상담톡.

항목내용
정식명Frogtalk
GitHubdigiwood7/frogtalk
만든이접니다 (코드는 못 쓰니까, 이번에도 AI와 함께)
구조순수 JS 위젯 + Vercel 서버리스 함수 3개 + Supabase
의존성npm 패키지 0개 (내장 fetch만 사용)
라이선스MIT (자유롭게 쓰고 고쳐도 되는 너그러운 오픈소스 라이선스)
공개일2026-07-12 (바로 오늘이에요)
비용인프라 0원 — Vercel Hobby + Supabase Free + 텔레그램

왜 만들었는지부터 말씀드릴게요. 사이트에 상담창을 달고 싶어서 시장을 둘러보니 이랬습니다.

  • 채널톡 무료 플랜은 대화 기록이 30일만 보관돼요. 한 달 지나면 손님과 나눈 이야기가 사라집니다.
  • Tawk.to 는 무료지만, 상담창에 붙는 자사 브랜딩("Powered by tawk.to" 문구)을 떼려면 유료 애드온을 결제해야 해요.
  • 이 니치(틈새 시장)의 원조 오픈소스인 intergram(별 1.4k 개)은 마지막 커밋이 2023년 5월일 만큼 손을 놓은 상태고, 결정적으로 대화 기록을 저장하지 않아요.

"무료 + 기록 영구 보존 + 쓰던 텔레그램 그대로" — 이 세 가지를 다 가진 물건이 없더라고요. 그래서 그 빈자리를 직접 만들었습니다.

부품은 딱 세 개예요.

  1. 위젯 — public/frogtalk.js 파일 하나. 순수 자바스크립트라 설치할 게 없고, data-* 속성(HTML 태그에 붙이는 설정값)으로 브랜드명·인사말·전화번호·포인트색을 바꿀 수 있어요.
  2. 서버 — api/send.js(메시지 접수) · api/poll.js(답장 꺼내 주기) · api/telegram-webhook.js(답장 수신), Vercel 서버리스 함수(요청이 올 때만 잠깐 깨어나는 서버) 3개가 전부입니다.
  3. 저장 — Supabase에 REST 직호출(별도 라이브러리 없이 표준 웹 요청으로 바로 저장하는 방식)로 기록해요. 대화는 덧붙이기만 하고 지우지 않는 방식(append-only)으로 영구 보존되고, RLS(행 단위 접근 잠금장치)를 걸어 서버 외에는 아무도 못 읽습니다.

동작 순서는 이렇습니다. 순서에 철학이 하나 숨어 있어요 — 전달보다 저장이 먼저입니다.

  1. 방문자가 위젯에 메시지를 남기면
  2. 먼저 DB에 저장해요. 혹시 텔레그램 쪽에 장애가 나도 기록은 남습니다.
  3. 그다음 텔레그램 그룹의 "방문자별 포럼 토픽"(그룹 안에 방마다 따로 열리는 대화방)으로 전달돼요. 방문자 1명 = 토픽 1개라 대화가 안 섞입니다.
  4. 운영자는 쓰던 텔레그램 앱에서 그 토픽에 그냥 답장하면 되고
  5. 답장은 웹훅(텔레그램이 우리 서버를 자동으로 호출해 주는 알림 통로)으로 돌아와 DB에 저장돼요. 이때 secret(비밀 문자열)을 상수시간 비교(맞든 틀리든 늘 같은 시간이 걸리게 비교해서, 응답 속도 차이로 비밀값을 유추하지 못하게 하는 방법)로 검증해 가짜 호출을 막습니다.
  6. 위젯은 5초 폴링(주기적으로 "새 답장 있나요?" 하고 물어보는 방식)으로 답장을 받아요. 상담창이 열려 있을 때만 물어보고, 닫으면 서버 호출이 0회라 서버리스 요금 걱정이 없습니다.

자잘하지만 마음 놓이는 디테일도 챙겼어요. 방문자는 로그인 없이 localStorage(브라우저 안의 작은 저장 공간) 익명 UUID(무작위 고유번호)로 식별하고, 토픽을 실수로 지워도 다음 메시지가 오면 자동으로 다시 만들어져요. 스팸봇은 허니팟(사람 눈에는 안 보이는 가짜 입력칸 — 봇이 채우면 그 메시지를 버림)으로 걸러냅니다. 그리고 상담원이 여러 명이어도 텔레그램 그룹에 초대하면 끝 — 상담원 수로 과금하는 SaaS와 달리 몇 명이든 무료예요.

우리는 이렇게 쓰고 있어요​

이번에도 이론이 아니라 실제 운영 기록입니다. autofrog.kr 본채 우하단의 상담 위젯, 보신 적 있으시죠? 그 시스템이 Frogtalk의 원형이에요. 2026년 7월 6일부터 라이브로 돌고 있고, 방문자 메시지가 제 텔레그램의 "오토프로그 상담" 그룹으로 실제로 들어옵니다. Frogtalk은 그중 상담 코어만 뽑아서 누구나 자기 사이트에 붙일 수 있게 추출·일반화한 것이고요.

방문자에게는 이렇게 보입니다. 실제 본채 위젯 화면을 그대로 재현한 목업이에요.

오토프로그 본채 상담 위젯 재현 — "[ 상담 ] 오토프로그" 헤더 아래 인사말, 방문자의 견적 자동화 질문, 대표가 텔레그램에서 보낸 답장이 이어지는 상담창

그리고 같은 대화가 제 텔레그램에는 이렇게 도착해요. 실제 데스크톱 화면을 재현한 목업입니다.

텔레그램 데스크톱 화면 재현 — "오토프로그 상담" 그룹의 "방문자 3c7a" 토픽으로 상담봇이 전달한 질문이 들어오고, 대표가 파란 말풍선으로 답장하는 모습

새 방문자가 말을 걸면 그룹에 "방문자 0f1e" 같은 토픽이 자동으로 생겨요. 저는 지하철에서든 현장에서든, 카톡 답장하듯 그 토픽에 답장만 하면 됩니다. 별도 상담 콘솔에 로그인할 필요도, 새 앱을 깔 필요도 없어요. 그리고 대화 전체가 제 Supabase에 쌓이니까, 나중에 "손님들이 뭘 제일 많이 물어보지?" 하고 돌아볼 수 있는 학습 데이터가 됩니다.

솔직한 고백도 하나 할게요. 본채 위젯과 Frogtalk은 답장 수신 방식이 달라요. 본채는 Supabase Realtime(실시간 구독 기능)을 써서 답장이 0.5초 만에 방문자 화면에 뜹니다. 반면 Frogtalk은 5초 폴링을 골랐어요. 왜냐면 Realtime을 쓰려면 라이브러리를 설치해야 하는데, Frogtalk의 정체성은 "npm 패키지 0개" 거든요. 상담 답장이 5초 늦게 뜨는 건 실사용에서 아무 문제가 없고, 그 대가로 얻는 게 의존성 0 — 즉 버전 충돌도, 보안 업데이트 쫓아다닐 일도 없는 단순함입니다. 이런 맞바꿈(트레이드오프)을 어디서 하느냐가 설계의 재미예요.

한번 써볼까요?​

설치는 6단계예요. 참고로 이번 글에는 패키지 버전 표기가 없습니다 — 설치할 npm 패키지가 0개니까요. 버전 충돌 걱정 없이 따라오시면 됩니다.

1단계 — Vercel에 배포. 저장소 첫 화면의 "Deploy with Vercel" 버튼을 누르면 내 계정으로 복제 + 배포가 한 번에 진행돼요. 환경변수(봇 토큰 같은 비밀값을 코드 밖에 따로 보관하는 설정 칸)는 아래 단계에서 만든 값을 나중에 넣고 재배포해도 됩니다.

2단계 — Supabase 테이블 만들기. supabase.com에서 무료 프로젝트를 만들고, SQL Editor(SQL 명령을 실행하는 화면)에 저장소의 supabase/migration.sql 내용을 붙여넣어 한 번만 실행하세요. 실행할 SQL은 이 파일 하나가 전부예요.

3단계 — 텔레그램 봇 + 상담 그룹. 텔레그램에서 @BotFather(봇을 만들어 주는 공식 봇)에게 /newbot을 보내 봇 토큰을 발급받고 → 상담용 그룹을 만들어 설정에서 토픽(Topics)을 켜고 → 봇을 그룹에 초대해 관리자로 지정합니다(토픽을 만들 권한이 필요해서요). 그룹의 chat id는 그룹에 아무 메시지나 보낸 뒤 브라우저에서 https://api.telegram.org/bot<토큰>/getUpdates를 열면 "chat":{"id":-100...} 형태로 보여요.

4단계 — 환경변수 5개 등록. Vercel → Settings → Environment Variables에 아래 다섯 개를 넣고 재배포하세요. 키 이름과 설명은 저장소의 .env.example에도 적어뒀어요.

TELEGRAM_BOT_TOKEN         # BotFather가 준 봇 토큰
TELEGRAM_GROUP_ID          # 상담 그룹 chat id (예: -100xxxxxxxxxx)
TELEGRAM_WEBHOOK_SECRET    # 웹훅 검증용 비밀 문자열 (아무 긴 랜덤 값)
SUPABASE_URL               # Supabase 프로젝트 URL (Settings → API)
SUPABASE_SERVICE_ROLE_KEY  # service_role 키 — 서버 전용, 절대 노출 금지

5단계 — 웹훅 등록 (딱 1회). 텔레그램에게 "답장이 오면 이 주소로 알려줘" 하고 등록하는 단계예요. 내 컴퓨터 터미널에서 한 번만 실행합니다.

# 텔레그램 웹훅 등록 — <봇토큰>·<시크릿>·<내-배포주소>를 내 값으로 바꿔서 실행
TELEGRAM_BOT_TOKEN=<봇토큰> TELEGRAM_WEBHOOK_SECRET=<시크릿> \
node scripts/set-webhook.mjs https://<내-배포주소>

6단계 — 사이트에 한 줄 붙이기. 이게 끝이에요.

<script src="https://<내-배포주소>/frogtalk.js" defer
  data-brand="우리가게"
  data-greeting="안녕하세요! 궁금한 점을 편하게 남겨 주세요."
  data-phone="010-0000-0000"
  data-accent="#4ADE80"></script>

워드프레스·카페24·아임웹·Next.js·정적 HTML — script 태그를 넣을 수 있는 곳이면 어디든 됩니다. 참고로 배포 주소를 브라우저로 그냥 열면 위젯이 동작하는 데모 페이지가 나오니까, 사이트에 붙이기 전에 먼저 눌러보실 수 있어요.

클로드 코드 터미널에서는 이렇게​

3단계(봇 만들기)와 4단계(환경변수)가 처음 하는 분께는 제일 낯설 거예요. 클로드 코드에게 손을 잡아 달라고 부탁합시다. 대화창에 아래를 그대로 붙여 넣으세요. (이건 명령어가 아니라 AI에게 거는 부탁이라 !를 붙이지 않아요.)

이 저장소를 내 사이트 상담톡으로 설치하고 싶어: https://github.com/digiwood7/frogtalk
README의 6단계를 나랑 같이 진행해줘. 나는 코드를 전혀 모르니까,
Vercel 배포 → Supabase SQL 실행 → 텔레그램 봇/그룹 만들기 → 환경변수 5개 →
웹훅 등록 순서로, 화면에서 어디를 눌러야 하는지 한 단계씩 알려줘.

클로드가 순서대로 안내해 줍니다. 그 전에 이 물건이 진짜 돌아가는지 눈으로 확인해 보고 싶으시면, 내려받아서 테스트부터 돌려보세요.

클로드 코드 대화창에서 !를 맨 앞에 붙이면 터미널 명령어를 바로 실행할 수 있어요.

# 저장소를 내려받고 단위 테스트 13개 실행 — 설치할 패키지가 없어서 바로 돌아가요 (앞에 ! 붙임)
# (Node.js 20 이상이 필요해요. 버전 확인은 node -v)
! git clone https://github.com/digiwood7/frogtalk.git && cd frogtalk && npm test

Node.js에 내장된 테스트 도구(node --test)라 테스트용 패키지조차 설치하지 않아요. tests 13 / pass 13이 뜨면 정상이에요. 허니팟 거부, 웹훅 secret 검증, 토픽 삭제 감지 같은 핵심 방어 로직이 전부 테스트로 박제되어 있습니다. 웹훅 등록(5단계)도 클로드에게 맡기면 편해요.

# 텔레그램 웹훅 등록 — 클로드에게 <봇토큰> 등을 내 값으로 채워 달라고 하면 돼요 (앞에 ! 붙임)
! TELEGRAM_BOT_TOKEN=<봇토큰> TELEGRAM_WEBHOOK_SECRET=<시크릿> node scripts/set-webhook.mjs https://<내-배포주소>

마지막으로, 내 사이트에 붙이는 것까지 부탁하면 끝입니다.

배포가 끝났어. 내 사이트의 모든 페이지에 Frogtalk 위젯 script 태그를 붙여줘.
브랜드명은 "우리가게", 인사말은 "안녕하세요! 무엇이든 물어보세요",
포인트색은 #4ADE80 으로 해줘. 붙인 다음 사이트를 열어서 상담창이 뜨는지 확인해줘.

여기까지 하면 여러분의 사이트에도, 손님 쪽지가 텔레그램으로 배달되는 쪽지함이 하나 달린 거예요.

이런 분께 추천해요​

Frogtalk은 "상담창은 달고 싶은데, 매달 나가는 돈과 사라지는 기록이 아까운" 분들을 위한 물건이에요. 특히 이런 세 분께 권해드립니다.

  1. 채널톡 무료 플랜의 30일 제한이 아쉬운 쇼핑몰·예약제 가게 사장님 — 카페24나 아임웹으로 사이트를 운영하시면서, 손님과 나눈 대화가 한 달 뒤 사라지는 게 찜찜했던 분이요. script 한 줄이면 상담은 텔레그램으로 받고, 기록은 내 DB에 평생 남습니다. 단골손님이 석 달 전에 뭘 물어봤는지 다시 찾아볼 수 있어요.

  2. 첫 풀스택 구조를 통째로 읽어보고 싶은 바이브 코더 — 프론트(위젯) + 백엔드(서버리스 함수 3개) + DB(Supabase)의 3층 구조가 파일 몇 개에 전부 담겨 있어요. npm 패키지가 0개라 남의 라이브러리 속을 파고들 필요 없이, "웹 서비스 한 채가 어떻게 서 있는지"를 처음부터 끝까지 눈으로 따라갈 수 있는 교재입니다.

  3. 상담원이 여러 명인데 인원당 과금이 부담스러운 소규모 팀 — 직원 3명이 돌아가며 응대하는 팀이라면, 상담원 수만큼 돈을 받는 SaaS 대신 텔레그램 그룹에 3명을 초대하면 끝이에요. 방문자별로 토픽이 나뉘니 누가 어느 손님을 응대 중인지도 한눈에 보입니다.

반대로, 상담원 자동 배정·챗봇 시나리오·통계 대시보드 같은 본격 콜센터 기능이 필요한 분께는 맞지 않아요. 그건 유료 SaaS가 잘하는 영역이고, Frogtalk은 "작은 사이트에 0원으로, 기록 잃지 않고" 상담을 붙이는 물건입니다.

혹시 코드를 열어보다 궁금한 게 생기면 편하게 물어봐 주세요. 저희도 만들면서 배운 걸 나누려고 공개한 거라, 같이 뜯어보고 같이 공부하는 분이 생기면 그게 제일 반갑습니다.

참고 링크​

▸개정 이력1건
  • v12026-07-12초판