telegram-api

Telegram Bot API

Telegram Bot API는 개발자가 Telegram용 봇(bot)을 만들 수 있게 해주는 HTTP 기반 인터페이스예요. 봇을 처음 만들고 설정하는 방법은 Introduction to Bots와 Bot FAQ에서 자세히 알려줘요. 인증 토큰만 있으면 HTTPS 요청 하나로 메시지를 보내고, 사용자 입력을 받고, 인라인 쿼리에 응답하는 것까지 전부 직접 구현할 수 있어요. 업데이트 소식은 @BotNews를 구독하면 가장 먼저 받을 수 있고, 토론은 @BotTalk에서 이어져요.

출처: 문서

본문

봇 인증 (Authorizing your bot)

봇을 만들면 봇마다 고유한 인증 토큰(auth token)이 하나씩 부여돼요. 토큰은 대략 이런 형태예요.

123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

이 문서에서는 간단히 <token>이라고 표현할게요. 토큰을 얻는 방법과 새로 생성하는 방법은 별도 문서에서 확인할 수 있어요.

요청 만들기 (Making requests)

모든 요청은 HTTPS 위에서 보내야 하고, 다음과 같은 형태를 가져요.

https://api.telegram.org/bot<token>/METHOD_NAME

예를 들어 봇 자신의 정보를 확인하는 getMe는 이렇게 호출해요.

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/getMe

HTTP 메서드는 GET과 POST를 지원해요. 파라미터를 넘기는 방법은 네 가지가 있어요.

URL query string - URL에 직접 붙여 넘겨요.
application/x-www-form-urlencoded - 폼 형식으로 넘겨요.
application/json - 파일 업로드가 아닐 때 JSON으로 넘겨요.
multipart/form-data - 파일을 업로드할 때 써요.

응답은 항상 boolean 필드 ok를 포함하는 JSON 객체예요. ok가 True면 요청이 성공한 것이고, 결과는 result 필드에 담겨요. 실패하면 ok가 False가 되고, 어떤 문제인지는 description(사람이 읽을 수 있는 문자열)에 설명돼요. 상황에 따라 자동 오류 처리를 도와주는 parameters(ResponseParameters 타입)가 같이 오기도 해요. Bot API의 모든 메서드 이름은 대소문자를 구분하지 않고, 모든 요청은 UTF-8로 보내야 해요.

업데이트 받기 (Getting updates)

봇이 사용자 메시지를 받는 방법은 **getUpdates(long polling)**와 webhook 두 가지가 있어요. 이 둘은 서로 배타적(동시에 쓸 수 없음)이고, 받지 않은 업데이트는 서버에 최대 24시간 동안만 보관돼요. 어떤 방법을 쓰든 결과로는 JSON 직렬화된 Update 객체를 받게 돼요.

Update 객체에는 update_id라는 고유 식별자가 있어요. 업데이트 ID는 증가하는 순서이고, webhook을 쓸 때 중복 업데이트를 무시하거나 순서가 어긋난 업데이트를 복원하는 데 특히 유용해요.

getUpdates (Long polling)

getUpdates 메서드로 롱 폴링(long polling) 방식으로 업데이트를 받아요. 성공하면 Update 객체의 배열을 반환해요. 핵심 파라미터로는 offset(받을 첫 업데이트의 ID, 이전에 받은 업데이트 중 가장 큰 ID보다 1 커야 해요)과 limit이 있어요.

Webhook

setWebhook 메서드로 URL을 지정하면, 봇에게 업데이트가 생길 때마다 그 URL로 HTTPS POST 요청을 보내줘요. 본문에는 JSON 직렬화된 Update가 담겨요. 요청이 실패하면(HTTP 상태 코드가 2XY가 아니면) 재시도하고, 일정 횟수 뒤에 포기해요. 성공하면 True를 반환해요.

요청이 정말 당신이 설정한 webhook에서 왔는지 확인하려면 secret_token 파라미터를 지정할 수 있어요. 그러면 모든 요청에 X-Telegram-Bot-Api-Secret-Token 헤더가 실려 와요. webhook이 설정되어 있는 동안에는 getUpdates를 쓸 수 없어요. webhook을 제거하고 getUpdates로 되돌아가려면 deleteWebhook을 쓰고, 현재 상태 확인은 getWebhookInfo로 해요.

포트는 443, 80, 88, 8443을 지원하고, webhook 설정이 잘 안 되면 공식 webhook 가이드를 참고하세요.

로컬 Bot API 서버 (Local Bot API Server)

Bot API 서버의 소스코드는 telegram-bot-api 리포지토리에서 공개돼요. 로컬에서 직접 실행하면 https://api.telegram.org 대신 자신의 서버로 요청을 보낼 수 있어요. 이때 이런 기능을 쓸 수 있어요.

파일 다운로드에 크기 제한이 없어요.
2000MB까지 파일을 업로드할 수 있어요.
파일을 로컬 경로와 file:// URI 체계로 업로드할 수 있어요.
webhook에 HTTP URL을 쓸 수 있어요.
webhook에 로컬 IP 주소와 임의의 포트를 쓸 수 있어요.
max_webhook_connections를 최대 100000까지 설정할 수 있어요.
getFile 요청 후 파일을 다운로드하지 않고도 file_path 필드에 절대 로컬 경로를 바로 받을 수 있어요.

대부분의 봇은 기본 설정(텔레그램 서버 사용)으로 충분하지만, 위 기능이 필요하다면 언제든 로컬 서버로 전환할 수 있어요.

메시지 보내기 (sendMessage)

sendMessage 메서드로 일반 텍스트 메시지를 보내요. 핵심 파라미터는 chat_id(대상 채팅의 고유 ID 또는 @username 형식)와 text예요. 성공하면 보낸 Message 객체를 반환해요. 메시지에 인라인 키보드(InlineKeyboardMarkup)를 붙이면 메시지 바로 옆에 버튼이 나타나고, 사용자가 버튼을 누르면 CallbackQuery 업데이트가 봇에게 와요.

{
  "chat_id": "@my_channel",
  "text": "안녕하세요 😊",
  "reply_markup": {
    "inline_keyboard": [[
      {"text": "자세히 보기", "url": "https://example.com"}
    ]]
  }
}

Poll (설문)

sendPoll 메서드로 네이티브 설문을 보낼 수 있어요. 성공하면 보낸 Message를 반환해요. 기본 파라미터는 chat_id와 question, options(선택지 배열)예요. 설문은 채널로 직접 보낼 수 없어요. Poll 객체에는 설문 ID, 질문(1~300자), 선택지, 그리고 투표 결과가 담겨요. 봇은 자신이 보낸 설문에 대해서만 새 투표 업데이트(poll_answer)를 받아요.

인라인 모드 (Inline mode)

인라인 모드 객체(Inline mode objects)를 통해, 사용자가 채팅창에 봇의 @username을 입력하고 쿼리를 날리면 봇이 그 자리에서 결과를 제안할 수 있어요. 인라인 쿼리는 InlineQuery 업데이트로 도착하고, answerInlineQuery로 결과를 돌려줘요.

더 알아보기 (Learn more)

공식 문서