텔레그램 봇 API 첫 요청 — getMe 와 sendMessage

준비물은 토큰 하나

봇 API 는 정해진 주소에 HTTPS 요청을 보내는 방식입니다. 라이브러리나 서버 없이도 브라우저 주소창이나 curl 한 줄로 바로 시험할 수 있습니다. 필요한 것은 @BotFather 에게 받은 토큰뿐입니다(봇 만들기).

요청 주소는 늘 같은 모양입니다.

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

이 글의 토큰 123456:ABC-EXAMPLE 과 숫자 ID 는 모두 예시 값입니다. 내 토큰으로 바꿔 넣습니다.

getMe — 토큰이 맞는지 확인

가장 먼저 부르는 메서드입니다. 토큰이 맞으면 봇 자신의 정보가 돌아옵니다.

curl https://api.telegram.org/bot123456:ABC-EXAMPLE/getMe

돌려받는 응답(실제 응답의 모양 그대로, 값은 예시):

{
  "ok": true,
  "result": {
    "id": 123456,
    "is_bot": true,
    "first_name": "예시 도우미",
    "username": "sample_help_bot",
    "can_join_groups": true,
    "can_read_all_group_messages": false,
    "supports_inline_queries": false
  }
}

칸	읽는 법
ok	true 면 성공. 모든 응답에 붙는다
result	메서드가 돌려준 값 — getMe 는 봇 계정 정보
can_join_groups	그룹에 넣을 수 있는지(@BotFather 설정)
can_read_all_group_messages	false 면 그룹에서 명령·답장만 본다(개인정보 모드)

실제 응답에는 이 밖에도 봇 설정에 따른 칸이 여러 개 더 붙습니다. 새 기능이 생길 때마다 칸이 늘어나므로, 프로그램은 모르는 칸을 무시하게 짭니다.

sendMessage — 메시지 보내기

보낼 곳(chat_id)과 내용(text)을 넘깁니다.

curl https://api.telegram.org/bot123456:ABC-EXAMPLE/sendMessage \
  -d chat_id=987654321 \
  -d text="안녕하세요"

성공하면 result 에 방금 보낸 메시지가 돌아옵니다 — 메시지 번호(message_id), 보낸 봇(from), 대화(chat), 보낸 시각(date, 유닉스 시간), 내용(text)이 들어 있습니다.

chat_id 는 어디서 얻나

봇은 먼저 말을 걸 수 없습니다. 그래서 chat_id 는 사용자가 봇에게 먼저 보낸 메시지에서 얻습니다. 사용자가 봇 대화에서 시작을 누르거나 메시지를 보내면, 봇이 받는 업데이트에 그 대화의 chat_id 가 들어 있습니다. 업데이트를 받는 두 방법은 롱 폴링과 웹훅에 있습니다. 봇을 관리자로 넣은 공개 채널이라면 @채널아이디 를 chat_id 자리에 바로 쓸 수 있습니다.

실패 응답 읽기

실패하면 ok 가 false 이고, 숫자 error_code 와 사람이 읽는 description 이 옵니다. 아래는 봇이 들어가 있지 않은 공개 채널로 보내 본 실제 응답입니다.

{
  "ok": false,
  "error_code": 403,
  "description": "Forbidden: bot is not a member of the channel chat"
}

error_code	흔한 원인
401	토큰이 틀렸거나 새로 발급해 옛 토큰이 무효
400	chat_id 가 없는 대화거나 칸 형식이 틀림 — description 에 이유가 적힌다
403	보낼 권한이 없다 — 봇이 채널·그룹에 없거나, 사용자가 봇을 시작하지 않았거나 차단했다
429	너무 빨리 많이 보냈다 — 응답이 알려 주는 초만큼 기다렸다 다시

원인 판단은 숫자보다 description 문장을 먼저 봅니다. 같은 403 이라도 문장이 다릅니다.

다음 단계

하려는 것	글
사용자 메시지 받기	롱 폴링과 웹훅
봇이 아닌 길도 보기	API 4가지 고르기