텔레그램 봇

Starnion을 텔레그램에서 사용하면 스마트폰 어디서나 AI 어시스턴트에 접근할 수 있습니다. 웹 UI와 텔레그램을 동시에 사용할 수 있으며, 대화 내역은 하나의 계정으로 통합됩니다.

개요

텔레그램 채널을 사용하면:

스마트폰 텔레그램 앱으로 Starnion과 대화
이미지, 음성 메시지, 문서 파일 전송
그룹 채팅에서 봇을 멘션하여 사용
웹 UI와 동일한 스킬·메모리 활용

1단계: 텔레그램 봇 만들기

텔레그램 봇은 BotFather를 통해 발급받습니다.

텔레그램에서 @BotFather를 검색하여 채팅을 엽니다.
/start 를 전송합니다.
/newbot 을 전송합니다.
봇 이름을 입력합니다 (예: 나의 Starnion).
봇 사용자명(username)을 입력합니다. 반드시 bot으로 끝나야 합니다 (예: my_starnion_bot).
BotFather가 토큰(Token)을 발급합니다.

BotFather: Done! Congratulations on your new bot. You will find it at t.me/my_starnion_bot.
Use this token to access the HTTP API:
1234567890:ABCDefGHIjklMNOpqrsTUVwxyz1234567890

발급된 토큰을 복사해 두세요. 다음 단계에서 사용합니다.

보안 주의: 토큰은 비밀번호와 같습니다. 절대 공개하지 마세요.

2단계: Starnion에 봇 등록하기

Starnion 웹 UI에 로그인합니다.
좌측 메뉴에서 설정(Settings) 을 클릭합니다.
채널(Channels) 탭을 선택합니다.
텔레그램 섹션에서 봇 토큰 입력 필드에 복사한 토큰을 붙여넣습니다.
저장 버튼을 클릭합니다.
봇 활성화 토글을 켭니다.

저장에 성공하면 상태가 실행 중(running) 으로 표시됩니다.

참고: 하나의 봇 토큰은 한 계정에만 등록할 수 있습니다. 다른 계정에 이미 등록된 토큰을 입력하면 오류가 발생합니다.

3단계: 텔레그램 계정 연결 (페어링)

봇을 등록한 것만으로는 텔레그램과 Starnion 계정이 연결되지 않습니다. 페어링(pairing)을 통해 “이 텔레그램 계정이 내 Starnion 계정이다”라고 연결해야 합니다.

페어링 방법

텔레그램에서 자신의 봇(@my_starnion_bot)을 검색하여 채팅을 엽니다.
아무 메시지나 전송합니다 (예: 안녕).
봇의 DM 정책이 pairing으로 설정된 경우, 봇이 “페어링 요청이 전송되었습니다” 라고 응답합니다.
Starnion 웹 UI > 설정 > 채널 > 텔레그램 에서 페어링 요청 목록을 확인합니다.
자신의 텔레그램 계정 이름을 확인하고 승인(Approve) 을 클릭합니다.
이후 텔레그램에서 봇과 정상 대화가 가능합니다.

페어링 정책

채널 설정에서 DM 정책과 그룹 정책을 설정할 수 있습니다.

DM 정책 (개인 메시지)

정책	동작
`allow`	누구든 봇에게 DM을 보내면 즉시 응답합니다.
`pairing`	페어링된 계정만 응답합니다. 미페어링 사용자는 페어링 요청을 보낼 수 있습니다.
`deny`	모든 DM을 무시합니다.

그룹 정책 (그룹 채팅)

정책	동작
`allow`	그룹에서 모든 메시지에 응답합니다.
`mention`	봇을 멘션(`@봇이름`)할 때만 응답합니다.
`deny`	그룹 메시지를 무시합니다.

권장 설정: 개인 사용의 경우 DM 정책을 pairing, 그룹 정책을 mention으로 설정하면 보안을 유지하면서 편리하게 사용할 수 있습니다.

봇 사용하기

기본 대화

페어링이 완료되면 일반 채팅처럼 대화합니다.

나: 오늘 날씨 어때?
봇: 서울 현재 날씨는 맑음, 기온 22°C입니다. ...

나: 점심 1만2천원 썼어
봇: 점심 식사 12,000원 기록했습니다. 이번 달 식비 합계: 87,500원

나: 파이썬 튜토리얼 찾아줘
봇: 인터넷에서 파이썬 튜토리얼을 검색했습니다...

이미지 전송

이미지를 전송하면 자동으로 분석합니다.

(영수증 사진 전송)
봇: 영수증을 분석했습니다.
    마트 구매 총액: 35,600원
    항목: 우유 2,800원, 빵 4,500원, ...
    가계부에 자동으로 기록할까요?

음성 메시지

텔레그램의 음성 메시지(보이스 메모)를 전송하면 텍스트로 변환하여 처리합니다.

(음성 메시지: "오늘 저녁에 친구들이랑 삼겹살 먹었어, 1인당 2만원")
봇: 음성 메시지를 인식했습니다.
    저녁 식사(삼겹살) 20,000원 기록했습니다.

문서 파일 전송

PDF, Word, 텍스트 파일 등을 전송하면 내용을 분석하거나 지식 베이스에 저장합니다.

(PDF 파일 전송)
봇: 문서 "계약서_2024.pdf"를 처리했습니다.
    총 15페이지, 주요 내용: 임대차 계약...
    검색 가능하도록 저장했습니다.

여러 기기에서 동시 사용

Starnion은 웹 UI와 텔레그램을 동시에 사용할 수 있습니다. 두 채널은 같은 AI 에이전트에 연결되므로 어느 채널에서 기록한 내용이든 다른 채널에서 조회됩니다.

[웹 UI에서]
나: 독서 목표: 이번 달 책 3권 읽기

[텔레그램에서]
나: 내 독서 목표가 뭐였지?
봇: 이번 달 책 3권 읽기 목표가 있습니다. 현재까지 1권 완료하셨습니다.

그룹 채팅에서 사용

그룹에 봇을 초대하고 멘션하여 사용할 수 있습니다.

그룹 채팅에서 멤버 추가 > 봇 사용자명 검색 후 초대합니다.
그룹 정책이 mention인 경우, @봇이름 메시지 형식으로 멘션합니다.

나: @my_starnion_bot 오늘 점심 회식비 총 15만원인데 5명이 나눠내면?
봇: 1인당 30,000원입니다.

나: @my_starnion_bot 지금 뉴욕 시간은?
봇: 뉴욕(EST) 현재 시간은 오전 2:15입니다.

주의사항

토큰 1개 = 계정 1개: 하나의 봇 토큰은 하나의 Starnion 계정에만 연결됩니다.
봇 토큰 보안: 토큰이 유출되면 BotFather에서 /revoke 명령으로 즉시 재발급하고, Starnion 설정에서도 새 토큰으로 업데이트하세요.
서버 재시작: Starnion 게이트웨이가 재시작되면 활성화된 봇이 자동으로 재개됩니다.

문제 해결

봇이 응답하지 않을 때

설정 > 채널 > 텔레그램에서 상태가 실행 중 인지 확인합니다.
상태가 설정됨(configured) 이면 봇이 비활성화된 것입니다. 봇 활성화 토글을 켜세요.
상태가 실행 중인데도 응답이 없다면:
- DM 정책이 deny로 설정되어 있지 않은지 확인하세요.
- 페어링이 필요한 경우 페어링 절차를 완료하세요.

409 Conflict 오류

같은 봇 토큰으로 두 개의 서버가 동시에 실행되고 있을 때 발생합니다.

Docker와 로컬 개발 환경을 동시에 실행하지 마세요.
이전 서버를 완전히 종료한 후 새 서버를 시작하세요.
Starnion은 PostgreSQL 어드바이저리 락을 사용하여 충돌을 방지합니다.

페어링이 되지 않을 때

봇이 활성화된 상태인지 확인합니다.
DM 정책이 deny이면 페어링 요청 자체가 차단됩니다. pairing 또는 allow로 변경하세요.
웹 UI의 페어링 요청 목록에 표시된 요청을 승인했는지 확인하세요.

FAQ

Q. 텔레그램 봇 없이 Starnion을 사용할 수 있나요? 네, 웹 UI만으로 모든 기능을 사용할 수 있습니다. 텔레그램은 선택적인 추가 채널입니다.

Q. 하나의 텔레그램 봇으로 여러 사람이 사용할 수 있나요? 아니요. 각 사용자는 자신만의 봇을 별도로 만들어야 합니다. 단, 그룹 채팅에서 페어링된 여러 사람이 하나의 봇에 멘션하는 방식으로 공유 사용은 가능합니다.

Q. 봇 토큰을 바꾸면 어떻게 되나요? 기존 봇이 자동으로 중지되고 새 토큰으로 재시작됩니다. 이전에 페어링된 계정 정보는 유지됩니다.

Q. 대화 기록이 텔레그램 서버에 저장되나요? 텔레그램 메시지는 텔레그램 서버를 경유하지만, Starnion의 대화 처리 및 저장은 자체 서버(self-hosted)에서 이루어집니다.