텔레그램 API 가이드: 봇 만들기부터 메시지 전송까지

작성자:


텔레그램은 강력한 API를 제공하여 자동화, 알림 시스템, 챗봇 등 다양한 서비스를 구축할 수 있습니다. 이 글에서는 텔레그램 API의 종류와 사용 방법을 단계별로 정리합니다.

텔레그램 API의 두 가지 종류

텔레그램은 목적에 따라 두 가지 API를 제공합니다.

구분Bot APITelegram API (MTProto)
용도봇 개발사용자 클라이언트 개발
인증Bot Tokenapi_id + api_hash
난이도쉬움어려움
권한봇 기능만전체 기능
추천 대상대부분의 자동화 작업커스텀 클라이언트 개발

대부분의 자동화 작업(알림 전송, 챗봇, 채널 관리 등)은 Bot API만으로 충분합니다.

1. Bot API 시작하기

1.1 봇 생성 및 토큰 발급

  1. 텔레그램에서 @BotFather 검색 후 대화 시작
  2. /newbot 명령어 입력
  3. 봇 이름 입력 (예: “My Notification Bot”)
  4. 봇 username 입력 (반드시 bot으로 끝나야 함)
    • 예: my_notification_bot, jackerlab_alert_bot
  5. 발급된 API 토큰 저장
Use this token to access the HTTP API:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz

⚠️ 주의: 토큰은 절대 외부에 노출하지 마세요. 노출된 경우 BotFather에서 /revoke로 재발급 받으세요.

1.2 봇 설정 (선택사항)

BotFather에서 추가 설정이 가능합니다:

  • /setdescription – 봇 설명 설정
  • /setabouttext – 봇 소개 설정
  • /setuserpic – 봇 프로필 사진 설정
  • /setcommands – 명령어 목록 설정

2. Bot API 기본 사용법

2.1 API 엔드포인트 구조

모든 Bot API 요청은 다음 형식을 따릅니다:

https://api.telegram.org/bot<TOKEN>/<METHOD>

예시:

https://api.telegram.org/bot123456789:ABCdef.../sendMessage

2.2 Chat ID 확인하기

메시지를 보내려면 대상의 Chat ID가 필요합니다.

방법 1: getUpdates 사용

봇에게 아무 메시지나 보낸 후:

curl "https://api.telegram.org/bot<TOKEN>/getUpdates"

응답에서 chat.id 값을 확인합니다:

{
  "result": [{
    "message": {
      "chat": {
        "id": 123456789,
        "type": "private"
      }
    }
  }]
}

방법 2: 채널/그룹의 경우

  • 채널: @채널username 또는 -100으로 시작하는 숫자 ID
  • 그룹: 봇을 그룹에 추가 후 getUpdates로 확인

2.3 메시지 전송하기

기본 텍스트 메시지

curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "안녕하세요! 첫 번째 메시지입니다."
  }'

마크다운 포맷 사용

curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "*굵게* _기울임_ `코드` [링크](https://example.com)",
    "parse_mode": "Markdown"
  }'

HTML 포맷 사용

curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "<b>굵게</b> <i>기울임</i> <code>코드</code>",
    "parse_mode": "HTML"
  }'

3. 주요 Bot API 메서드

3.1 메시지 관련

메서드설명
sendMessage텍스트 메시지 전송
sendPhoto사진 전송
sendDocument파일 전송
sendLocation위치 전송
editMessageText메시지 수정
deleteMessage메시지 삭제

3.2 봇 정보

메서드설명
getMe봇 정보 조회
getUpdates새 메시지/이벤트 조회
setWebhook웹훅 설정
getWebhookInfo웹훅 정보 조회

3.3 사진 전송 예시

curl -X POST "https://api.telegram.org/bot<TOKEN>/sendPhoto" \
  -F "chat_id=123456789" \
  -F "photo=@/path/to/image.jpg" \
  -F "caption=이미지 설명"

3.4 파일 전송 예시

curl -X POST "https://api.telegram.org/bot<TOKEN>/sendDocument" \
  -F "chat_id=123456789" \
  -F "document=@/path/to/file.pdf"

4. 프로그래밍 언어별 예제

4.1 Python

import requests

TOKEN = "YOUR_BOT_TOKEN"
CHAT_ID = "YOUR_CHAT_ID"

def send_message(text):
    url = f"https://api.telegram.org/bot{TOKEN}/sendMessage"
    payload = {
        "chat_id": CHAT_ID,
        "text": text,
        "parse_mode": "HTML"
    }
    response = requests.post(url, json=payload)
    return response.json()

# 사용
send_message("<b>알림</b>: 작업이 완료되었습니다!")

4.2 JavaScript (Node.js)

const TOKEN = "YOUR_BOT_TOKEN";
const CHAT_ID = "YOUR_CHAT_ID";

async function sendMessage(text) {
  const url = `https://api.telegram.org/bot${TOKEN}/sendMessage`;
  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      chat_id: CHAT_ID,
      text: text,
      parse_mode: "HTML"
    })
  });
  return response.json();
}

// 사용
sendMessage("<b>알림</b>: 작업이 완료되었습니다!");

4.3 n8n 워크플로우

n8n에서 Telegram 노드 설정:

  1. Credentials 설정
    • Telegram API 선택
    • Bot Token 입력
  2. 노드 설정
    • Resource: Message
    • Operation: Send Message
    • Chat ID: 대상 Chat ID 입력
    • Text: 보낼 메시지

5. 웹훅(Webhook) 설정

실시간으로 메시지를 수신하려면 웹훅을 설정합니다.

5.1 웹훅 등록

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://your-domain.com/webhook"

5.2 웹훅 정보 확인

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

5.3 웹훅 삭제

curl "https://api.telegram.org/bot<TOKEN>/deleteWebhook"

5.4 웹훅 수신 서버 예제 (Python Flask)

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.json
    
    if 'message' in data:
        chat_id = data['message']['chat']['id']
        text = data['message'].get('text', '')
        print(f"받은 메시지: {text} (from: {chat_id})")
    
    return 'OK', 200

if __name__ == '__main__':
    app.run(port=5000)

6. Telegram API (MTProto)

Bot API로 충분하지 않은 경우(사용자 계정 기능 필요 시) MTProto API를 사용합니다.

6.1 API 자격 증명 발급

  1. https://my.telegram.org 접속
  2. 전화번호로 로그인
  3. “API development tools” 클릭
  4. 앱 정보 입력 후 생성
  5. api_id와 api_hash 저장

6.2 Python 라이브러리 사용 (Telethon)

from telethon import TelegramClient

api_id = 12345
api_hash = 'your_api_hash'

client = TelegramClient('session_name', api_id, api_hash)

async def main():
    await client.start()
    
    # 메시지 전송
    await client.send_message('username', '안녕하세요!')
    
    # 채널 메시지 읽기
    async for message in client.iter_messages('channel_name', limit=10):
        print(message.text)

with client:
    client.loop.run_until_complete(main())

7. 실전 활용 예시

7.1 서버 모니터링 알림

import requests
import psutil

def send_alert(message):
    url = f"https://api.telegram.org/bot{TOKEN}/sendMessage"
    requests.post(url, json={
        "chat_id": CHAT_ID,
        "text": f"🚨 서버 알림\n{message}",
        "parse_mode": "HTML"
    })

# CPU 사용량 체크
cpu_percent = psutil.cpu_percent()
if cpu_percent > 80:
    send_alert(f"CPU 사용량 경고: {cpu_percent}%")

7.2 트레이딩 알림 시스템

def send_trading_signal(signal_type, symbol, price, reason):
    emoji = "🟢" if signal_type == "BUY" else "🔴"
    message = f"""
{emoji} <b>{signal_type} 신호</b>

코인: {symbol}
가격: ${price:,.2f}
근거: {reason}
시간: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
"""
    send_message(message)

8. API 제한 및 주의사항

8.1 요청 제한

  • 같은 채팅: 초당 1개 메시지
  • 전체: 초당 30개 메시지
  • 그룹: 분당 20개 메시지

8.2 메시지 제한

  • 텍스트: 최대 4096자
  • 캡션: 최대 1024자
  • 파일: 최대 50MB (봇), 2GB (MTProto)

8.3 보안 권장사항

  1. 토큰을 코드에 직접 넣지 말고 환경 변수 사용
  2. HTTPS 웹훅만 사용
  3. 주기적으로 토큰 재발급 고려
  4. 불필요한 권한은 부여하지 않기

마무리

텔레그램 Bot API는 간단하면서도 강력한 기능을 제공합니다. 알림 시스템, 자동화 봇, 모니터링 도구 등 다양한 용도로 활용할 수 있으니 필요에 맞게 적용해 보세요.

참고 자료



댓글 남기기