위젯 연동 문서
기본 설치부터 디자인 설정까지 TalkTG를 사이트에 추가하는 방법을 알아보세요.
목차
빠른 시작
코드 한 줄만 붙여 넣으면 몇 분 안에 연동할 수 있습니다.
가입하고 사이트 추가
계정을 만든 뒤 “사이트”에서 “사이트 추가”를 선택하고 도메인을 입력하세요.
Telegram 봇 연결
@BotFather에서 봇을 만들고 Token을 복사해 사이트 상세에서 연결한 뒤 봇에 /start를 보내세요.
위젯 코드 붙여넣기
사이트 상세에서 임베드 코드를 복사해 HTML의 </body> 바로 앞에 붙여 넣으세요.
준비 사항
- 1TalkTG 계정
- 2HTML 소스를 수정할 수 있는 웹사이트
- 3@BotFather에서 발급한 Telegram Bot Token
설치
아래 스크립트의 YOUR_SITE_ID를 대시보드에 표시된 사이트 ID로 바꾸세요.
<script src="https://talktg.com/widget.js"
data-site-id="YOUR_SITE_ID" async></script>기본 HTML
</body> 바로 앞에 스크립트를 추가합니다.
Next.js / React
루트 레이아웃에서 Next.js Script 컴포넌트를 사용합니다.
Vue / Nuxt
nuxt.config.ts의 app.head.script에 추가합니다.
WordPress
footer.php의 </body> 앞 또는 헤더/푸터 코드 플러그인으로 추가합니다.
Shopify
theme.liquid의 </body> 앞에 추가합니다.
Wix
사용자 지정 코드에서 Body 끝을 선택하고 모든 페이지에 적용합니다.
위젯 설정
“사이트 → 내 사이트 → 위젯 설정”에서 모양과 동작을 변경할 수 있습니다.
| 옵션 | 기본값 | 설명 |
|---|---|---|
| 기본 색상 | #6366F1 | 버튼, 헤더 및 방문자 메시지의 테마 색상입니다. |
| 위치 | bottom-right | 오른쪽 아래 또는 왼쪽 아래에 표시합니다. |
| 환영 메시지 | Hi there! | 첫 방문자에게 표시할 메시지입니다. |
| 상담원 이름 | Support | 채팅 헤더에 표시할 이름입니다. |
| 자동 팝업 | false | 새 방문자에게 자동으로 표시할지 설정합니다. |
| 알림음 | true | 새 답변 수신 시 소리를 재생합니다. |
API 참고
다음 공개 API는 위젯 내부에서 사용되며 일반적으로 직접 호출할 필요가 없습니다.
/api/widget/config/{siteId}위젯 설정을 가져옵니다.
/api/sites/{siteId}/statusTelegram 봇 상태를 확인합니다.
/api/chat/send방문자 메시지를 전송합니다.
/api/chat/history대화 기록을 불러옵니다.
/api/chat/poll새 메시지를 폴링합니다.
작동 방식
스크립트는 비동기로 로드되고 Shadow DOM으로 스타일을 격리합니다.
방문자 메시지는 TalkTG를 통해 연결된 Telegram으로 전달됩니다.
Telegram에서 보낸 답변은 웹 채팅 창에 표시됩니다.
방문자 정보를 브라우저에 저장해 재방문 시 대화를 이어갑니다.
자주 묻는 질문 및 문제 해결
위젯이 표시되지 않습니다
스크립트 위치와 사이트 ID를 확인하고 브라우저 콘솔 오류를 살펴보세요.
Telegram에서 메시지를 받지 못합니다
봇에 /start를 보냈고 대시보드에 연결됨으로 표시되는지 확인하세요.
여러 도메인에서 사용할 수 있나요?
사이트 하나는 도메인 하나에 연결됩니다. 도메인별로 사이트를 만드세요.
사이트 속도가 느려지나요?
async로 비동기 로드되므로 페이지 렌더링을 차단하지 않습니다.
시작할 준비가 되셨나요?
몇 분이면 설정할 수 있으며 신용카드는 필요하지 않습니다.