Telegram 연결: 단계별 안내
직접 만든 봇을 통해 실패 알림 (NEXUS_TELEGRAM_NOTIFY=true이면 테스트당 하나)과 공유하기로 선택한 보고서 및 파일을 보냅니다. 공용 봇은 없습니다. 이 안내에서는 처음부터 연결 확인까지의 과정을 설명하고, 발생할 수 있는 오류와 그 원인 및 해결 방법을 정리합니다.
최종 업데이트:
자격 증명은 비공개로 유지하세요. 토큰, 키, 비밀번호, 웹후크 URL을 채팅에 붙여넣지 마세요. Studio → 설정 → 연동에만 입력하세요. 입력한 정보는 작업 공간의 .env 파일에 저장되며 점으로 표시됩니다. AI 도우미도 마찬가지입니다: 이 안내를 따라 진행하도록 도와줄 수는 있지만, 토큰을 알려줄 필요는 없습니다.
준비 사항
- Telegram 계정.
- @BotFather로 한 번 생성한 본인 소유의 봇과 해당 토큰.
- 연결용 QR 코드를 스캔할 휴대전화 또는 Telegram 앱.
- 켜기 전에 확인하세요: Telegram은 보고서 및 PDF와 같은 파일을 수신할 수 있으며, 이 파일은 Telegram 서버로 전송됩니다. 규제가 적용되는 환경에서는 먼저 규정 준수 담당팀에 문의하세요.
자격 증명 발급
- Telegram에서 https://t.me/BotFather 를 열고 /newbot 을 보내세요. 봇의 이름과 사용자 이름을 지정하세요.
- BotFather가 봇 토큰으로 응답합니다 (예: 123456:ABC…). 이를 복사하세요.
- 클립보드에 보관하세요. Studio(다음 단계) 외에는 어디에도 붙여넣지 마세요.
Studio에서 연결
- Studio에서 설정 → 연동 → Telegram 연결을 여세요.
- 봇 토큰을 붙여넣고 저장하세요. 연결용 QR 코드가 나타납니다.
- 휴대전화로 QR 코드를 스캔하고 Telegram에서 시작을 누르세요. 몇 초 안에 Studio에 "알림을 받을 채팅 …"이 표시되고 봇이 "Nexus StudioQA에 연결되었습니다."라고 응답합니다.
TELEGRAM_ENABLED를 켜세요. 실패한 테스트마다 알림을 하나씩 보내려면NEXUS_TELEGRAM_NOTIFY도 켜세요.
작동 확인
- 스캔 후 봇이 채팅으로 "Nexus StudioQA에 연결되었습니다. 실패한 테스트는 여기에 보고됩니다."라는 메시지를 보냅니다.
- Studio에 "알림을 받을 채팅"이 표시되며 채팅 정보는 가려집니다.
자주 발생하는 오류
| 관찰되는 결과 | 원인 | 해결 방법 |
|---|---|---|
| "Telegram이 꺼져 있습니다" | TELEGRAM_ENABLED가 false입니다. 연결하려면 켜야 합니다. | TELEGRAM_ENABLED를 켜고 Telegram 연결을 다시 누르세요. |
| "봇 토큰이 없습니다" | TELEGRAM_TOKEN이 비어 있습니다. | 설정 → 연동에 BotFather에서 받은 토큰을 붙여넣고 저장하세요. |
| "Telegram: 인증되지 않음" (또는 "찾을 수 없음") | 봇 토큰이 잘못되었거나, BotFather에서 취소되었거나, 복사할 때 일부가 잘렸습니다. | BotFather에 /token을 보내 토큰을 다시 받거나 새 봇을 만든 후 저장하세요. |
| "스캔하기 전에 QR 코드가 만료되었습니다" | QR 코드는 몇 분 동안만 유효합니다. | Telegram 연결을 눌러 새 QR 코드를 만들고 바로 스캔하세요. |
| QR 코드를 스캔했지만 Studio가 계속 대기 중임 | 스캔하여 채팅을 열었지만 시작을 누르지 않았거나, Studio 창이 닫혔습니다. | 봇 채팅에서 시작을 누르세요. 계속 대기 중이면 새 QR 코드를 만드세요. |
| "Telegram에 연결할 수 없음 (ENOTFOUND)" 또는 "20초 이내에 응답하지 않음" | 이 PC에서 api.telegram.org에 연결할 수 없습니다: VPN, 방화벽, 프록시 또는 네트워크 연결 부재가 원인입니다. | 동일한 PC에서 네트워크를 확인하고 다시 시도하세요. |
| 실패 후 알림이 오지 않음 | TELEGRAM_ENABLED가 false이거나, 연결된 채팅이 없거나, 테스트별 알림이 꺼져 있습니다 (NEXUS_TELEGRAM_NOTIFY). | 채팅을 연결하고 두 스위치를 모두 켜세요. |
설정 키
| 키 | 주요 기능 | 유효한 값 | 확인 방법 |
|---|---|---|---|
TELEGRAM_ENABLED | Telegram으로 알림 보내기 | true 또는 false | 연결용 QR 코드를 사용하려면 켜야 합니다. |
TELEGRAM_TOKEN | Telegram 봇 접근 코드 (비밀 정보, 이 컴퓨터에만 저장됨) | BotFather에서 받은 봇 토큰, 예: 123456:ABC…, 한 줄로 입력 | Telegram이 토큰을 승인해야 QR 코드가 표시됩니다. |
TELEGRAM_CHAT_ID | 알림을 받을 Telegram 채팅 | QR 코드로 연결하면 자동 입력됩니다; 직접 입력하지 마세요 | Studio에 "채팅 …에 알림을 보냅니다"가 표시됩니다. |
NEXUS_TELEGRAM_NOTIFY | 실패할 때마다 Telegram 알림 보내기 | true 또는 false | 실패한 테스트마다 알림이 하나씩 전송됩니다. |
더 보기: 모든 연동, 설정 안내, 문제 해결. 다른 안내: Jira Cloud, Azure Boards, Slack, Microsoft Teams, GitHub Issues.
아직 해결되지 않았나요? Studio에 표시되는 오류 문구를 그대로 적어 [email protected]으로 보내 주세요. 토큰은 포함하지 마세요.