Telegram
자격 증명 검증과 자동 웹훅 등록으로 Telegram 봇을 연결합니다.
자격 증명 검증과 자동 웹훅 등록으로 Telegram 봇을 연결합니다.
빠른 설정#
QR로 만들기가 표시되면 선택한 후 QR을 스캔하거나 Telegram 열기를 누르고 설정 봇에서 봇 만들기를 누르세요. Make Agent Fast로 돌아와 봇 사용자 이름을 확인하고 이 봇 연결을 선택합니다. 토큰 복사는 필요 없습니다. 설정은 15분 후 만료되며 취소하고 다시 시작할 수 있습니다.
빠른 설정이 없으면 봇 토큰으로 연결을 사용하세요. 두 방법 모두 같은 연결 검증과 교체 확인을 거칩니다.
생성 화면에는 에이전트 이름과 maf_<agent>_<random>_bot 형식의 사용자 이름이 제안됩니다. 둘 다 수정할 수 있습니다. 무작위 문자열은 이름 중복을 줄이지만 최종 사용 가능 여부는 Telegram이 확인합니다. 기존 봇의 이름은 바꾸지 않습니다.
생성 후 설정 봇의 이 봇 연결 버튼을 누르면 해당 에이전트의 로그인된 연결 확인 화면이 열립니다. 봇 생성만으로 연결되지는 않습니다. 연결 확인이 성공하면 봇 열기 버튼으로 대화를 테스트하세요. /start 또는 /help는 진행 중인 설정을 다시 열거나 대시보드와 가이드 버튼을 표시합니다.
수동으로 봇 만들고 준비하기#
Telegram 공식 봇 소개와 BotFather 가이드를 따르세요.
- Telegram에서 인증된 @BotFather 계정을 엽니다.
/newbot을 실행하고 표시 이름과bot으로 끝나는 고유 사용자 이름을 선택합니다.- 봇 토큰을 복사합니다. 이 토큰을 가진 사람은 누구나 봇을 제어할 수 있습니다.
- 출시 전 BotFather에서 사진, 설명, 소개 문구, 현지화된 명령 도움말을 선택적으로 설정합니다.
이 토큰은 Telegram Bot API용이며 Telegram 로그인 코드, API ID, API hash가 아닙니다.
Make Agent Fast에 연결하기#
에이전트의 채널 페이지에서 Telegram을 선택하고 봇 토큰을 붙여 넣은 뒤 지원되는 답변에 음성을 함께 보낼지 선택하고 연결을 누릅니다.
Make Agent Fast는 Telegram getMe로 토큰을 검증하고 봇 사용자 이름을 표시합니다. 이후 공개 HTTPS URL, 비밀 검증 토큰, 업데이트 유형 message, callback_query, my_chat_member로 setWebhook을 호출합니다. 대기 업데이트는 삭제하지 않습니다.
일반적으로 수동 웹훅 설정은 필요 없습니다. 다른 폴링 서비스는 먼저 중지하세요. 다른 웹훅 수신자가 있으면 교체를 명시적으로 확인해야 합니다. 에이전트 하나가 최대 다섯 개의 Telegram 봇에서 동시에 답할 수 있으며, 봇마다 별도의 연결입니다. 다른 봇을 저장하면 현재 연결을 교체하지 않고 새 연결이 추가됩니다. 다른 에이전트에 연결된 봇은 먼저 해당 연결을 해제해야 합니다.
대화 테스트하기#
- 소유자가 아닌 Telegram 계정에서 봇의
t.me링크를 엽니다. - Start를 선택합니다. 봇은 사용자와 먼저 대화를 시작할 수 없습니다.
- 지식 기반 텍스트 질문을 보냅니다.
- 음성을 사용한다면 음성 메시지를 보냅니다.
- 답변, 마지막 메시지 변경, 대화 스레드를 확인합니다.
개인 메시지는 기본적으로 누구나 보낼 수 있으며 소유자 승인이 필요 없습니다. 그룹 답변은 소유자가 그룹에서 멘션이나 답글에 응답을 켜야 활성화됩니다. Telegram Privacy Mode와 그룹 권한도 적용됩니다. 개인 메시지를 먼저 테스트하세요.
음성 동작#
이 커넥터는 Telegram 음성 수신과 발신을 지원합니다. 수신 음성은 에이전트 실행 전에 내려받아 전사합니다. 음성으로 답하기가 켜지고 음성 제공자가 준비되면 Make Agent Fast가 텍스트와 함께 음성/오디오 응답을 보냅니다. 전사나 음성 합성이 실패하면 사용자에게 텍스트 재시도를 요청하고 커넥터 오류를 확인하세요.
교체, 비활성화 또는 삭제#
토큰이 노출되면 BotFather에서 즉시 폐기하고 새 토큰으로 업데이트한 뒤 테스트하세요. 같은 봇의 토큰을 업데이트하면 설정과 일시 중지 상태가 유지됩니다. 다른 봇으로 교체하려면 확인이 필요하며 이전 대화 기록은 별도로 보존됩니다.
끄기는 답변을 중지하고 연결 해제는 기록을 보존하면서 연결을 보관합니다. Telegram 봇을 삭제하거나 deleteWebhook을 호출하지 않으므로 새 수신자를 방해하지 않습니다. 보관된 연결은 수신 메시지를 무시합니다. 빠르게 만든 봇의 토큰은 관리 이벤트로 갱신될 수 있지만 일시 중지 상태는 유지되며 소유자가 바뀌면 확인을 위해 연결이 비활성화됩니다.
문제 해결#
| 증상 | 해결 방법 |
|---|---|
| 저장 시 토큰 거부 | 현재 BotFather 토큰을 복사하고 공백을 제거하며 이 봇의 토큰인지 확인 |
| 메시지가 이전 서비스로 전달됨 | 기존 폴링을 중지하고 다시 연결한 후 수신자 교체를 명시적으로 확인 |
| 개인 메시지는 되지만 그룹은 실패 | 그룹 답변을 켜고 봇을 멘션하거나 답글을 보내며 Telegram Privacy Mode와 그룹 권한 확인 |
| 봇이 새 사용자에게 먼저 메시지하지 않음 | 정상 Telegram 동작이며 사용자가 봇을 열고 Start를 눌러야 함 |
| 텍스트는 되지만 음성 실패 | 모델/전사/음성 키를 확인하고 지원 Telegram 음성 메시지로 재시도 |
실제 토큰을 문서, 소스 코드, 분석 도구, 지원 스크린샷에 붙여 넣지 마세요.