创建机器人

在telegram中我们可以通过和一个名为BotFather的机器人交互来申请我们自己的机器人，具体步骤如下

1. 添加BotFather为好友

   点击这里添加botfather

2. 打开和botfather的对话框发送 /newbot

   这一步过后botfather会提示你输入你要创建的机器人的名字，这个名字可以随意，是我们称呼它的名字

3. 设置自定义机器人的名字（这个名字不同于上一步的名字，这个名字是唯一的）结尾必须是_bot或者Bot，不能包含中文, 标点符号

4. 如果上一步执行成功那么botfather会返回该机器人的token，大概长这样

   Copy123456789:ABCDEfghiJK4314daDSadSa7

   记住这个token,到这里机器人就创建好了

将机器人添加到群组里#

进入机器人信息页面，点击更多，点击添加到群组，选择一个群组即可

获取群组chat_id

通常来说我们都需要让机器人在一个群组里工作，所以首先我们需要将机器人添加到我们指定的群组，在群组里发送随意消息并@这个机器人，比如

Copyhello @your_bot

然后浏览器打开这个链接，注意替换为你的token

Copyhttps://api.telegram.org/bot<token>/getUpdates

你看到的是一个json，格式如下

Copy{
  "ok": true,
  "result": [
    {
      "update_id": 414941268,
      "message": {
        ...        },
        "chat": {
          "id": -465512321,
          ...        },
        ...     }
  ]}

从中找到chat.id这就是当前群组的id,以后发消息都是发到这个id.

机器人发送请求

请求接口

telegram发送消息的方式类似与钉钉机器人，都是向一个api发送http请求，而且对于同一个APItelegram支持GET和POST两种请求方式.请求的api格式如下

Copyhttps://api.telegram.org/bot<token>/<method>

其中token为你的机器人token，method为telegram给定的方法，在获取群组chat_id那一步就使用了telegram的其中一个方法(getUpdates),其他方法后面会介绍

携带参数

请求api时有些方法需要携带参数，telegram支持的传参方式/类型如下

• URL查询参数
• application/x-www-form-urlencoded
• application/json
• multipart/form-data(上传文件使用这个content-type)

获取响应

对于每次请求telegram都会有一个响应，响应的内容是一个json，格式如下

Copy{
  "ok": true,
  "result": ...}

其中返回的result可以是telegram定义的对象或者是对象的列表

telegram对象

telegram机器人的几乎所有操作都是一个一个对象的操作。

telegram定义了许多场景下的对象，详见，这里举例一些常见的

Update

该对象表示传入的更新，比如接收到用户发来的新消息，就会获得新的更新

任何给定的更新中最多只能存在一个可选参数。

User

该对象表示telegram的一个用户或者机器人

Chat

该对象表示一个聊天信息

Message

该对象代表一个消息

MessageEntity

该对象表示文本消息中的一个特殊实体。例如，标签，用户名，URL等。

BotCommand

这个对象代表值一条机器人指令

WebhookInfo

这个对象表示当前webhook的状态

ReplyKeyboardMarkup

该对象表示带有回复选项的自定义键盘

KeyboardButton

该对象表示回复键盘的一个按钮。对于简单的文本按钮，可以使用String代替此对象来指定按钮的文本。可选字段request_contact，request_location和request_poll是互斥的。

注意：request_contact和request_location选项仅适用于2016年4月9日之后发布的电报版本。较旧的客户端将显示不受支持的消息。

注意：request_poll选项仅在2020年1月23日之后发布的电报版本中有效。旧客户端将显示不支持的消息。

KeyboardButtonPollType

该对象表示民意调查的类型，可以在按下相应按钮时创建并发送该民意调查

ReplyKeyboardRemove

收到带有此对象的消息后，Telegram客户端将删除当前的自定义键盘并显示默认的字母键盘。默认情况下，将显示自定义键盘，直到机器人发送新键盘为止。一次性键盘的例外情况是用户按下按钮后立即隐藏的一次性键盘

InlineKeyboardMarkup

该对象表示一个嵌入式键盘，出现在其所属消息的旁边。

注意：这仅适用于2016年4月9日之后发布的电报版本。较旧的客户端将显示不受支持的消息。

InlineKeyboardButton

此对象表示嵌入式键盘的一个按钮。您必须完全使用可选字段之一。

ForceReply

收到带有该对象的消息后，Telegram客户端将向用户显示一个答复界面（就像用户选择了机器人的消息并点按“答复”一样）。如果您要创建用户友好的逐步界面而不必牺牲隐私模式，这将非常有用。

telegram方法

telegram方法就是拼接在api后面的那串字符串，不区分大小写。详见，这里只列举一些常用的，下面我所指的返回是指返回json中的result部分，其他章节提到的所有方法均可以在这一章节查阅

getUpdates

• 描述

  获取更新，还有另外一种获取更新的方法(webhook)，两种方式不能共存

• 参数

  无参数

• 返回

  update对象列表

setWebhook

• 描述

  使用此方法可以指定URL并通过传出的Webhook接收传入的更新。只要机器人有更新，telegram就会向指定的URL发送HTTPS POST请求，请求数据为json序列化后的update对象

• 参数

  Parameter	Type	Required	Description
  url	String	Yes	发送更新的https url。使用空字符串删除webhook集成
  certificate	InputFile	Optional	上传您的公共密钥证书，以便可以检查正在使用的根证书。有关详细信息，请参见我们的自签名指南。
  max_connections	Integer	Optional	与Webhook进行更新交付的同时HTTPS连接的最大允许数量为1-100。默认值为40。使用较低的值可以限制bot服务器的负载，使用较高的值可以增加bot的吞吐量。
  allowed_updates	Array of String	Optional	您希望机器人接收的更新类型的JSON序列化列表。 例如，指定[“ message”，“ edited_channel_post”，“ callback_query”]仅接收这些类型的更新。 请参阅更新以获取可用更新类型的完整列表。 指定一个空列表以接收所有更新，无论类型如何（默认）。 如果未指定，将使用以前的设置。 请注意，此参数不会影响调用setWebhook之前创建的更新，因此可能会在短时间内收到不需要的更新。

• 返回

  成功返回True

deleteWebhook

• 描述

  删除设置的webhook

• 参数

  无参数

• 返回

  成功返回True

getWebhookInfo

• 描述

  获取当前webhook的状态

• 参数

  无参数

• 返回

  WebhookInfo对象

  （如果没有设置webhook，则返回的对象中url为空）

getMe

• 描述

  获取机器人自身信息

• 参数

  无参数

• 返回

  user对象

getChat

• 描述

  使用此方法可获取有关聊天的最新信息（一对一对话的用户的当前名称，用户的当前用户名，组或频道等）

• 参数

  Parameter	Type	Required	Description
  chat_id	Integer or String	Yes	目标聊天或目标超级组或频道的用户名的唯一标识符（格式为@channelusername）

• 返回

  chat对象

sendMessage

• 描述

  发送消息

• 参数

  Parameter	Type	Required	Description
  chat_id	Integer or String	Yes	目标聊天（chat_id）或目标频道的用户名的唯一标识符（格式为@channelusername）
  text	String	Yes	待发送消息的文本，实体解析后为1-4096个字符
  parse_mode	String	Optional	消息文本中的实体解析模式。有关更多详细信息，请参见格式化选项。
  disable_web_page_preview	Boolean	Optional	禁用此消息中链接的链接预览
  disable_notification	Boolean	Optional	静默发送消息。用户将收到没有声音的通知。
  reply_to_message_id	Integer	Optional	如果消息是答复，则为原始消息的ID
  reply_markup	InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply	Optional	其他界面选项。内联键盘，自定义回复键盘，删除回复键盘或强制用户回复的说明的JSON序列化对象。

• 返回

  刚刚发送的message对象

setMyCommands

• 描述

  使用此方法可以更改机器人的命令列表

• 参数

  Parameter	Type	Required	Description
  commands	Array of BotCommand	Yes	将bot命令的JSON序列化列表设置为bot命令列表。最多可以指定100个命令。

• 返回

  成功返回True

getMyCommands

• 描述

  使用此方法获取机器人命令的当前列表

• 参数

  无参数

• 返回

  BotCommand对象列表

格式化选项

格式化选项就是让我们的机器人以某种格式发送消息（比如markdown，或者html）

Bot API支持消息的基本格式。您可以在机器人的消息中使用粗体，斜体，下划线和删除线文本，以及内联链接和预格式化的代码。电报客户端将相应地呈现它们。您可以使用markdown样式或HTML样式格式。

请注意，Telegram客户端将在打开内联链接（“打开此链接？”以及完整的URL）之前向用户显示警报。

如果满足以下限制，则可以嵌套消息实体：

• 如果两个实体具有公共字符，则其中一个完全包含在另一个内部。
• 粗体，斜体，下划线和删除线实体可以包含并且要包含在任何其他实体中，但pre和code除外。
• 所有其他实体不能互相包含。

链接tg://user?id=<user_id>可以用于通过用户ID提及用户，而无需使用用户名。请注意：

• 这些链接仅在内联链接中使用时才有效。例如，当用于嵌入式键盘按钮或消息文本中时，它们将不起作用。
• 仅当用户过去联系过该机器人，通过内联按钮向该机器人发送了回调查询或成为提及该用户的组的成员时，才能保证这些提及有效。

MarkdownV2 style

要使用此模式，请在parse_mode字段中传递MarkdownV2。在您的消息中使用以下语法：

Copy*bold \*text*
_italic \*text___underline__~strikethrough~
*bold _italic bold ~italic bold strikethrough~ __underline italic bold___ bold*
[inline URL](http://www.example.com/)
[inline mention of a user](tg://user?id=123456789)
`inline fixed-width code`
```
pre-formatted fixed-width code block
```
```python
pre-formatted fixed-width code block written in the Python programming language
```

请注意：

• 任何代码在1到126之间（含1和126）的字符都可以在任何带有''字符的位置转义，在这种情况下，它将被视为普通字符，而不是标记的一部分。
• 在pre和code实体内部，所有'`'和'\'字符必须以前面的'\'字符转义。
• 内联链接定义的内部(...)部分，所有')'和'\'必须以前面的'\'字符转义
• 在其他所有地方这些字符 '_', '*', '[', ']', '(', ')', '~', '`', '>', '#', '+', '-', '=', '|', '{', '}', '.', '!' 必须用前置'\'转义
• 如果斜体和下划线之间存在歧义，__始终从左到右被视为下划线实体的开始或结尾，所以使用___italic underline_\r__代替___italic underline___

HTML style

要使用此模式，请在parse_mode字段中传递HTML。当前支持以下标签：

Copy<b>bold</b>, <strong>bold</strong><i>italic</i>, <em>italic</em><u>underline</u>, <ins>underline</ins><s>strikethrough</s>, <strike>strikethrough</strike>, <del>strikethrough</del><b>bold <i>italic bold <s>italic bold strikethrough</s> <u>underline italic bold</u></i> bold</b><a href="http://www.example.com/">inline URL</a><a href="tg://user?id=123456789">inline mention of a user</a><code>inline fixed-width code</code><pre>pre-formatted fixed-width code block</pre><pre><code class="language-python">pre-formatted fixed-width code block written in the Python programming language</code></pre>

请注意：

• 当前仅支持上述标签。
• 所有不属于标记或HTML实体的<，>和&符号必须替换为相应的HTML实体(< 用 &lt;， > 用 &gt;， & 用 &amp;)。
• 支持所有数字HTML实体。
• 该API当前仅支持以下命名的HTML实体： &lt;, &gt;, &amp; and &quot;。
• 使用嵌套的pre和code标签，为pre实体定义编程语言。
• 不能为独立code标签指定编程语言。

Markdown style

这是旧版模式，保留下来是为了向后兼容。要使用此模式，请在parse_mode字段中传递Markdown。在您的消息中使用以下语法：

Copy*bold text*_italic text_[inline URL](http://www.example.com/)
[inline mention of a user](tg://user?id=123456789)`inline fixed-width code````
pre-formatted fixed-width code block
``````python
pre-formatted fixed-width code block written in the Python programming language
```

请注意：

• 实体不得嵌套，而应使用解析模式MarkdownV2。
• 无法指定下划线和删除线实体，请改用解析模式MarkdownV2。
• 要在实体外部转义字符_，*，`，[，请在字符之前加上\。
• 不允许在实体内部转义，因此必须先关闭实体再重新打开：对于斜体使用_snake_\__case_，对于粗体2*2=4使用 snake_case 和 *2*\**2=4*。

telegram更新

telegram中更新指的是机器人是否有收到新的消息，具体有哪些消息可以查看telegram对象部分中的Update，获取更新的方式有两种1. 轮询，2.webhook

轮询

这是一种主动询问的方式，这种方式比较简单但是效率欠佳，具体操作是，开发者每个一段时间请求一次getUpdates方法，从获取结果中判断update有无更新，有关update对象的描述可看telegram对象章节

webhook

webhook可以理解为客户端给服务端的api,只要服务端一有更新就会主动将内容发送到客户端设置的一个api中，然后客户端收到消息后可做相应处理。

给我们的机器人设置webhook

通过setWebhook方法设置（前面有介绍），需要注意的是，telegram只支持https协议，所以我们的api服务器必须要有TLS证书，必须注意一但我们设置了webhook那么通过getUpdates方法将不起作用！

telegram中的命令

通过命令来和机器人交互是电报机器人的一大特色，在telegram中命令由实体BotCommand表示（telegram对象那节已经介绍过）。

其实任何以/开头的连续英文消息都被视作命令(可以理解为这是一种具有格式的普通消息)，私聊或者在群里@机器人时发送/开头的信息可以查看实体类型为bot_command。要想让机器人收到某条命令后执行响应动作只需要判断发送的消息是否匹配我们约定的内容即刻，（从某种意义上讲无论发送的消息是否是命令格式我们都可以将其视为命令只要我们愿意），开发具有命令响应的过程总结如下：

1. 起一个死循环监听update的message消息，可以是轮询或者webhook方式
2. 拿到update.id检查其是否更新，如有更新则取message.Text匹配已经定义好的路由（这是我定义的叫法，也就是我们约定的命令，事实上他的确和路由很像）
3. 如果匹配成功，执行我们定义的方法，如果匹配失败则当做普通信息无视，或者返回对应信息

从上面过程可以看出命令是否是/开头其实已经不那么重要了，那么为什么官方要定义BotCommand类呢，理由（优点）如下

1. 用以和普通消息区分
2. 在聊天消息中命令会高亮显示
3. 已经注册的命令在对话框中只需要输入/就会有提示列表

给机器人注册指令

手动注册

1. 和botFather对话，输入/mybot

2. 选择要注册指令的机器人

3. 选择Edit Bot选项

4. 选择Edit Commands

5. 输入你想定义的命令，格式为

   Copycommand1 - 描述
   command2 - Description

   注意：注册时命令开头没有斜杠，使用命令时需要带上斜杠，中间用 - 分割；每一次的命令编辑都会覆盖之前的命令而不是追加，所以必须一次发送全部命令（在对话框中按shift + enter换行）

通过setMyCommands方法注册

• 详见（telegram方法 setMyCommands）

查看已注册的指令

• 详见（telegram方法 getMyCommands）

基本指令

telegram建议我们的机器人都带上三条基本指令分别是

• /start
• /help
• /settings

当设置了上面三个命令，用户首次打开与你的机器人的对话时，将看到Start按钮。机器人的个人资料页面上的菜单中将提供Help和Settings链接。

键盘

telegram中键盘也是机器人的一大特色，开发者可以自定义自己的键盘，一个键盘相当于机器人的菜单可以理解为一个答复界面，可以更加方便的和机器人交互。

telegram中的键盘有四种ReplyKeyboardMarkup，InlineKeyboardMarkup，ReplyKeyboardRemove和ForceReply，这四个对象可参考前面的介绍

创建键盘

只需要在sendMessage时指定reply_markup即可，详见sendMessage方法