Telegram Bot API

-- 번역 : https://core.telegram.org/bots/api

Telegram Bot Api

봇 API는 텔레그램에서 봇을 만드는 개발자들을 위해 만들어진 HTTP 기반 인터페이스입니다. 만드는 방법과 세팅 방법을 알기 위해서는, Introduction to Bots 페이지와 Bot FAQ 페이지를 참고하세요.

Authorizing your bot (봇 인증)

각각의 봇마다 만들어질 때 특별한 인증키가 주어집니다. 토큰은 마치 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 이런 형식으로 생겼지만, 우리는 이 문서에서 <token> 이라는 단어로 대체할 예정입니다. 당신은 토큰을 소유하고 새로 만드는 방법을 이 페이지에서 배울 수 있습니다.

Making request (요청하기)

모든 텔레그램 봇 API의 쿼리들은 HTTPS 에서 받으며, 다음과 같은 양식을 필요로 합니다: https://api.telegram.org/bot<token>/METHOD_NAME. 어떻게 사용하는지 샘플을 보자면:

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

텔레그램에서는 HTTP 메소드인 GET, POST을 모두 제공합니다. 봇 API 요청시 파라미터를 넘기는 방법은 네 가지를 지원합니다:

1. URL query string
2. application/x-www-form-urlencoded
3. application/json (except for uploading files)
4. multipart/form-data (use to upload files)

응답 (response)으로는 'OK' 필드와 'description'을 가진 JSON Object를 반환할 것입니다. 'OK' 필드(Boolean)의 경우 항상 반환할 것이고, 'description' 필드(String)는 사람이 읽을 수 있는 내용을 포함하여 결과에 따라 반환할 것입니다. 만약 'ok' 필드의 내용이 true와 같다면, 요청 (request)는 성공적이었으며 쿼리의 결과로 'result' 필드를 반환할 것입니다. 성공적이지 못한 요청의 경우, 'ok' 필드의 내용은 false가 될 것이며, 에러는 'description' 필드에 설명될 것입니다. 'error_code' 필드(Integer) 또한 반환되지만, 해당 내용은 미래에 언제든지 변할 수 있습니다. 어떠한 에러는 'parameters' 필드(ResponseParameters 타입)를 반환하며, 자동적으로 에러를 다룰 수 있게끔 도울 것입니다.

1. 모든 봇 API의 메소드는 대소문자를 구별합니다. (case-insensitive)
2. 모든 쿼리는 UTF-8을 사용합니다. (encoding)

Making result when getting updates

만약 당신이 웹훅(webhooks)을 사용한다면, 당신은 웹훅에 답변을 보내면서 봇 API로 요청(request)을 수행할 수 있습니다. 전달 매개 변수에 대해 application/json, application/x-www-form-urlencoded, multipart/form-data 응답 컨텐트 타입을 지정하세요. 요청한 메서드 매개 변수에서 호출된 메소드를 지정하세요. 그러한 요청이 성공적이었는지, 그 결과를 얻었는지 알 수 없습니다.

** Updates (업데이트)
내가 보기엔 이 업데이트는 말풍선 하나를 의미하는 모양.

Getting updates (업데이트 가져오기)

당신의 봇에서 업데이트를 받아오는 두 가지 방법은 다음과 같습니다: getUpdates 메소드 사용하기, Webhooks 사용하기. 봇이 앞서 언급한 방식을 통해 받아올 때까지 업데이트는 서버에 저장되나, 저장은 24시간 이내로 지속됩니다.

어떤 방식을 사용했는지와 관계 없이, 당신은 그 결과로서 JSON Objects인 Update 객체를 받게 될 것입니다.

Update

이 객체는 들어오는 업데이트를 표현합니다.

getUpdates

한 개 이상의 여러 들어오는 업데이트를 받아오기 위해서는 이 메소드를 사용합니다. Update 객체 배열이 리턴됩니다.

참고:

1. 만약 outgoing webhook이 세팅된다면, 이 메소드는 작동하지 않을 것입니다.
2. 중복된 업데이트를 받아오는 것을 피하기 위해서는, 각각의 서버 응답 이후 offset를 재계산하십시오.

setWebhook

url을 명시하고 outgoing webhook를 통해 들어오는 업데이트를 받기 위해서는 해당 메소드를 사용하세요. 봇의 업데이트가 언제 이루어지든 간에, 텔레그램은 HTTPS POST 요청을 특정 url로 전송하며, JSON Object인 Update 객체를 포함하게 될 것입니다. 만약 요청이 성공적이지 않았다면, 우리는 몇차례의 시도 후에 포기할 것입니다. 성공일 경우 True를 리턴합니다.

웹 사이트의 요청이 Telegram에서 전송되는지 확인하려면 https://www.example.com/<token> 와 같은 비밀스러운 경로를 사용하는 것이 좋습니다. 아무도 당신 봇의 토큰을 모르니까, 우리라고 확신할 수 있을 겁니다.

 

---

 

텔레그램 봇을 통해 메세지를 보낼 수 있는 방법은 크게 두 가지 인듯 하다.

1. sendMessage : 단순 메세지 보내기. 단순 알림용으로 사용할 수 있음.

2. webhook 만들기 : 단순 메세지를 보낼 뿐만 아니라, 사용자가 보내는 명령어에 따라 반응을 할 수도 있는 상호작용형 봇 만들 수 있음.