Telegram
자격 증명 검증과 자동 웹훅 등록으로 Telegram 봇을 연결합니다.
자격 증명 검증과 자동 웹훅 등록으로 Telegram 봇을 연결합니다.
봇 만들고 준비하기#
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로 setWebhook을 호출합니다. 기존 대기 업데이트는 삭제하지 않습니다.
일반적으로 수동 웹훅 단계는 필요 없습니다. 커넥터를 저장하거나 다시 켜면 같은 웹훅이 안전하게 다시 등록됩니다.
대화 테스트하기#
- 소유자가 아닌 Telegram 계정에서 봇의
t.me링크를 엽니다. - Start를 선택합니다. 봇은 사용자와 먼저 대화를 시작할 수 없습니다.
- 지식 기반 텍스트 질문을 보냅니다.
- 음성을 사용한다면 음성 메시지를 보냅니다.
- 답변, 마지막 메시지 변경, 대화 스레드를 확인합니다.
그룹 동작은 Telegram Privacy Mode와 봇의 그룹 추가 여부에 따라 달라집니다. 그룹 가시성 규칙이 업데이트를 숨기지 않도록 먼저 개인 메시지에서 테스트하세요.
음성 동작#
이 커넥터는 Telegram 음성 수신과 발신을 지원합니다. 수신 음성은 에이전트 실행 전에 내려받아 전사합니다. 음성으로 답하기가 켜지고 음성 제공자가 준비되면 Make Agent Fast가 텍스트와 함께 음성/오디오 응답을 보냅니다. 전사나 음성 합성이 실패하면 사용자에게 텍스트 재시도를 요청하고 커넥터 오류를 확인하세요.
교체, 비활성화 또는 삭제#
토큰이 노출되면 즉시 BotFather에서 새로 생성/폐기하고 커넥터를 교체 값으로 업데이트한 뒤 다시 테스트합니다. 커넥터를 끄거나 삭제하면 대기 업데이트를 버리지 않고 Telegram deleteWebhook을 호출합니다. Make Agent Fast 커넥터를 삭제해도 Telegram 봇 자체는 삭제되지 않습니다.
문제 해결#
| 증상 | 해결 방법 |
|---|---|
| 저장 시 토큰 거부 | 현재 BotFather 토큰을 복사하고 공백을 제거하며 이 봇의 토큰인지 확인 |
| 메시지가 이전 서비스로 전달됨 | 커넥터를 다시 저장해 Telegram 웹훅을 Make Agent Fast로 교체 |
| 개인 메시지는 되지만 그룹은 실패 | BotFather Privacy Mode와 그룹 권한 확인 |
| 봇이 새 사용자에게 먼저 메시지하지 않음 | 정상 Telegram 동작이며 사용자가 봇을 열고 Start를 눌러야 함 |
| 텍스트는 되지만 음성 실패 | 모델/전사/음성 키를 확인하고 지원 Telegram 음성 메시지로 재시도 |
실제 토큰을 문서, 소스 코드, 분석 도구, 지원 스크린샷에 붙여 넣지 마세요.