텔레그램 API

텔레그램이 그냥 메신저로만 보이면 좀 아깝습니다. 개발자 입장에선 “이걸로 자동화 좀 해볼까?” 싶은 포인트가 진짜 많거든요. 저도 예전에 개인 블로그 운영하면서, 매일 아침 방문자 통계 확인하는 게 은근히 귀찮더라고요. 그래서 “이거 텔레그램으로 툭 던져주면 편하겠다” 싶어서 봇 개발을 시작했어요.
> 구글 애널리틱스랑 연동해서 매일 아침 9시에 어제 방문자 수랑 인기 글을 텔레그램으로 보내주는 봇을 만들었는데, 그때 그 짜릿함이 아직도 기억납니다.
그때 삽질하면서 배운 것들, 운영하면서 느낀 포인트들을 이 글에 쭉 담아볼게요. 텔레그램 API 기초부터 실전에서 써먹는 방법까지, 쌩초보도 따라올 수 있게 최대한 쉽게 풀어보겠습니다. 지금 바로 시작해 보셔도 좋아요.

텔레그램 API의 기본 이해 및 시작

처음 봇 만들려고 하면 제일 먼저 막히는 게 “API가 뭐지?”부터예요. 그리고 텔레그램이 제공하는 인터페이스가 뭐가 있는지, 제일 중요한 API 키(정확히는 토큰)는 어디서 받는지 이런 것들이요. 여기만 한 번 정리해두면, 뒤에서 기능 붙일 때 훨씬 덜 헤맵니다.

텔레그램 API란

텔레그램 API는, 우리가 만든 프로그램이 텔레그램의 기능(메시지 보내기/받기 같은 거요)을 쓰게 해주는 공식 통로입니다. API(Application Programming Interface)는 프로그램끼리 대화할 때 지켜야 하는 약속, 소통 규칙이라고 보시면 돼요. 너무 어렵게 생각할 필요는 없고요. 예를 들면 회원가입이 발생했을 때 관리자한테 텔레그램으로 알림을 보내거나, 주식 가격이 특정 값에 도달하면 자동으로 메시지를 쏴주는 것도 다 이걸로 구현합니다.

텔레그램은 크게 두 가지 인터페이스를 제공합니다. 하나는 우리가 보통 쓰는 ‘봇 인터페이스’고, 다른 하나는 ‘코어 인터페이스’예요. 실무든 개인 프로젝트든 대부분은 봇 인터페이스만으로도 하고 싶은 거 거의 다 됩니다. 봇 인터페이스는 봇 만들라고 나온 거라 직관적이고 쓰기 편해요. 반대로 코어 인터페이스는 텔레그램 클라이언트 앱 자체를 새로 만들 때 쓰는 쪽이라 훨씬 복잡하고 강력합니다. 이 글에서는 일단 봇 인터페이스 중심으로 가볼게요.

기술적으로는 JSON 형식으로 데이터를 주고받고, 통신은 HTTPS로 합니다. 그리고 중요한 포인트 하나 더요. 개인이든 회사든 무료로 쓸 수 있습니다. 다만 스팸 같은 걸 막으려고 사용량 제한이 좀 있으니, 대량 발송 쪽은 한 번씩 체크해두시는 게 좋아요.

텔레그램 봇 API, 어떻게 작동할까요?

텔레그램 봇은 사람이 직접 쓰는 계정이 아니라, 코드로 움직이는 ‘자동 계정’이라고 보시면 됩니다. 개발자는 봇 API를 통해 이 봇이 사용자랑 메시지를 주고받게 만들 수 있어요. 예를 들어 사용자가 봇한테 /날씨 서울 이렇게 보내면, 봇이 그걸 읽고 외부 날씨 데이터를 가져와서 답장해주는 흐름도 충분히 만들 수 있습니다.

봇이 메시지를 받는 방식은 크게 두 가지가 있어요. 폴링(Polling)과 웹훅(Webhook)입니다. 아래 표로 감 잡아보시면 됩니다.

> 실제 서비스로 굴릴 생각이면, 저는 웹훅으로 시작하는 걸 더 추천드려요. 운영해보면 이게 훨씬 편합니다.

그리고 봇에는 중요한 규칙이 하나 있어요. 기본적으로 사용자가 먼저 말을 걸거나, 그룹에 초대해야 대화가 시작됩니다. 그룹에서는 보통 봇을 직접 부르거나(/명령어@봇이름) 멘션한 메시지만 읽게 되어 있어요. 그룹의 모든 대화를 읽게 하려면 관리자가 봇의 ‘프라이버시 모드’를 꺼줘야 합니다. 이건 개인정보 보호를 위한 장치라서, 왜 있는지 정도는 꼭 기억해두시면 좋습니다.

텔레그램 API 토큰은 어떻게 발급받나요?

이 토큰은 절대 다른 사람에게 보여주거나 공개된 곳에 올리면 안 됩니다. 토큰이 털리면, 누가 내 봇인 척하면서 메시지를 보내고 난리 칠 수도 있거든요. 저도 쌩초보 때 토큰을 소스에 그대로 박아놨다가, GitHub 올리기 직전에 “아차” 하고 식은땀 난 적이 있습니다. 그 뒤로는 무조건 환경 변수로 빼서 관리해요. 혹시 유출된 것 같으면 /revoke로 바로 폐기하고 새로 발급받으셔야 합니다.

토큰 발급은 봇의 신분증 만드는 과정이라고 보시면 돼요. 이걸 발급해주는 공식 봇이 봇파더(BotFather)입니다.

제가 개인 프로젝트로 스터디 노트 정리 봇 MyStudyNoteBot 만들 때도 아래 순서대로 했고, 여러분도 그대로 따라 하시면 됩니다.

1. 텔레그램 검색 텔레그램 앱 검색창에 @BotFather를 검색합니다. 파란색 공식 인증 마크 있는 봇을 고르고 ‘시작’을 누르세요.
2. 새 봇 생성 대화창에 /newbot을 입력해 전송합니다. 봇파더가 이름(별명)을 물어보면 ‘오늘의 명언 봇’ 같은 식으로 편하게 지으시면 돼요.
3. 사용자명 설정 이제 사용자명(ID)을 정합니다. 영어로만 가능하고, 마지막은 bot으로 끝나야 합니다. 예를 들면 wise_saying_bot 이런 식이요. 이미 누가 쓰는 이름이면 안 되니까 고유하게 잡아야 합니다.
4. 토큰 발급 완료 끝나면 봇파더가 1234567890:ABCDEFGHIJKLMN_OPQRSTUVWXYZ123456Copy 같은 긴 문자열을 줍니다. 이게 여러분의 API 토큰이에요.

텔레그램 API 활용 및 실제 적용

토큰까지 받으셨으면, 이제 봇을 움직일 수 있는 열쇠는 손에 쥔 겁니다. 여기서부터는 “그래서 이걸 어디에 써먹지?”가 재밌는 구간이에요. 먼저 실생활/업무에서 자주 나오는 활용 예시를 보고, 그 다음에 실제로 API를 어떻게 호출하는지로 넘어가겠습니다.

텔레그램 API 사용법

API를 쓸 때 제가 제일 강조하는 건 에러 처리입니다. 안정적인 봇은 결국 “실패했을 때 어떻게 버티냐”에서 갈리더라고요. 텔레그램은 요청이 실패하면 이유를 응답으로 꽤 친절하게 줍니다. 그 응답을 확인해서, 문제가 생겼을 때 적절히 대처하는 코드를 꼭 넣어두셔야 해요.

토큰을 써서 API를 호출하는 방식은 생각보다 단순합니다. 기본적으로 URL을 호출하는 구조예요. 형태는 이렇게 갑니다.

https://api.telegram.org/bot<토큰>/<메서드이름>Copy

<토큰>에는 봇파더가 준 토큰을 그대로 넣으면 되고요.
<메서드이름>에는 봇에게 시킬 동작 이름을 적습니다.

예를 들어 봇 설정이 제대로 됐는지 확인할 때는 getMe를 씁니다. 메시지 보내기는 sendMessage고요. 이때 누구에게 보낼지(chat_id), 뭘 보낼지(text) 같은 파라미터를 같이 넘겨야 합니다.

자주 쓰는 메서드는 아래 정도가 대표적이에요.

근데 이걸 매번 URL로 직접 때리려면 좀 귀찮죠. 그래서 언어별 라이브러리를 많이 씁니다. 파이썬이면 python-telegram-botCopy이 진짜 무난해요. 문서랑 예제가 잘 되어 있어서 입문자도 덜 삽질합니다. 이런 걸 쓰면 bot.send_message(chat_id, "안녕하세요!")Copy처럼 훨씬 편하게 제어할 수 있어요.

텔레그램 API 연동

텔레그램 API는 다른 서비스랑 붙일 때 진짜 맛이 납니다. 쇼핑몰, DB, 사내 시스템, 심지어 집에 있는 IoT까지요. 주문 들어오면 관리자에게 알림 보내기, 봇으로 재고 조회하기 같은 건 거의 단골 예시죠.

요즘은 AWS Lambda나 Google Cloud Functions 같은 서버리스로 봇 운영하는 경우도 많습니다. 24시간 서버 켜두는 대신, 메시지 들어올 때만 잠깐 실행하고 쓴 만큼만 내는 구조라 개인 프로젝트에 특히 좋아요. 트래픽 적은 봇이면 비용이 거의 안 나오는 경우도 많고요.

그리고 봇이 “대화가 이어지는 느낌”을 내려면 DB 연동이 자주 필요합니다. 예를 들어 사용자가 “내 지역은 서울”이라고 한 번 설정해두면, 다음부터는 지역을 안 물어보고 바로 서울 날씨를 주는 거죠. 이런 작은 저장 하나가 봇을 확 살아나게 합니다.

실시간 처리가 중요하면 웹훅이 거의 필수고요. 하루에 한 번 요약해서 보내는 리포트 봇 같은 건 폴링으로도 충분히 굴러갑니다.

텔레그램 API 활용 예시

이제 “아 그래서 이런 데 쓰는구나” 감이 오게, 실제로 많이 쓰는 활용 예시를 몇 개만 더 볼게요.

콘텐츠 배포 자동화 블로그에 새 글 올리면 텔레그램 채널에 자동 공유하거나, 여러 SNS에 동시에 올리는 데도 잘 씁니다. 반복 작업 줄이는 데 꽤 좋아요.

개인 비서 및 정보 수집 뉴스 구독 봇, 주식/코인 알림 봇, 매일 할 일 정리 봇 같은 것들이요. 만들다 보면 “아 이거 진짜 편한데?” 하는 순간이 옵니다.
스마트 홈(IoT) 연동 라즈베리파이 같은 거랑 붙이면 메시지로 조명 켜고 끄고, 보일러 미리 켜두는 것도 됩니다. 퇴근길에 “/집 따뜻하게” 이런 상상, 은근 현실이에요.

서버 및 서비스 모니터링 서버 장애나 에러 터졌을 때 텔레그램으로 바로 알림 오게 해두면, 새벽에 덜 불안합니다. 저도 이거 해두고 마음이 좀 편해졌어요.
비즈니스 자동화 주문/결제/배송 알림을 봇으로 보내거나, FAQ 자동응답 챗봇으로 상담 부담 줄이는 데도 많이 씁니다.

처음부터 거창한 거 만들 필요는 없어요. 저도 처음엔 “아침에 통계만 보내주면 된다” 수준으로 시작했거든요. 작은 알림 봇 하나 만들어보면, 그 다음부터 아이디어가 계속 붙습니다. 막히는 구간이 나오면 그게 정상이에요. 삽질하면서 배우는 게 제일 빨라요. 편하게 봇파더부터 한 번 두드려보시죠.

FAQ