telegram bots 开发者文档简介

╰半橙微兮° 2021-09-07 06:09 406阅读 0赞

**目录**

写给开发者的telegram-bots介绍文档

我能用bots做什么？

bots是如何工作的?

我怎么创建一个bot?

bot和普通账号有什么不同?

与众不同的Bot

BotFather

--------------------

## 写给开发者的telegram-bots介绍文档 ##

bots是运行在telegram内部的第三方应用。用户可以通过发送消息，命令或者[内联请求][Link 1]和bots进行交互。开发者可以通过向[bot API][]发送HTTPS请求来控制自己的bot。

> 因为最近对telegram bot产生了兴趣，想创建一个bot试一试，因为网上没有找到相关的中文文档，所以就自己跟着自己的理解和Google Translate翻译了部分的介绍文档(只有bot的基本功能，付款和游戏平台部分没有翻译)，文中一定有表述不对的地方，我会在之后编写bot的时候进行修改，建议大家阅读的时候参照[原文档][Link 2]一起阅读。你也可以在下面的评论中提出建议和我一起修改。

如果你已经熟悉bot的操作模式，那还等什么看快来看这篇 [基于aiotg的telegram机器人][aiotg_telegram]创建你自己的机器人吧！

## 我能用bots做什么？ ##

下面举几个例子，你可以用bot来：

*  获得自定义的新闻和通知。一个机器人可以扮演一个智能新闻的角色，发送你需要的新闻。 如：[TechCrunch Bot][]
 *  和其他服务集成。一个机器人可以通过绑定其他的服务来丰富聊天 如:[Gmail Bot][]
 *  接受来自telegram用户的付款
 *  创建自定义工具 一个机器人可以为你提供预警，天气预报，格式化文本，翻译，或者其他服务.如: [Markdown][]
 *  创建单人多人游戏 一个机器人可以提供丰富的HTML5体验，从简单的街机和解谜游戏到3D射击和实时策略游戏。如: [GameBot][]
 *  建立社交服务 一个机器人能够将一些寻找共同兴趣爱好的人联系在一起。如:[HotOrBot][]
 *  或者做一些其他的事情 除了做菜--机器人做的菜非常糟糕(官方吐槽)

## bots是如何工作的? ##

Telegram Bots是一个特别的账号并不需要另外的手机号码去创建，用户可以通过下面两种方式和机器人交互。

1.  创建和bots的聊天并发送消息和命令或者将机器人加入聊天群。这一特性对聊天机器人和官方新闻机器人很有用。
2.  直接在输入框中键入`@username query`来发送请求。这样可以通过[inline bots][]直接发送内容到任何聊天，群或者频道。

用户发送的消息，命令，和请求被转发给运行在你服务上的应用。我们的中介服务器帮你处理消息的加密和telegram api的通讯。你可以通过简单的HTTPS接口(Telegram API的简化版本)和服务通讯,我们把这个接口称为Bot API。

> 有关Bot API的详细说明，请参阅 [bots api][bot API]

## 我怎么创建一个bot? ##

我们提供一个bot来帮助你创建bot，你可以直接和[BotFather][]交谈，并按照几个简单的步骤就可以创建一个属于自己的bot。一旦你创建了一个bot并获取到你的authorization token，那就直接去查看[Bot API][bot API]手册看看你能操作机器人做什么事情。

> 你也可以查看一些 **[示例代码][Link 3]**

## bot和普通账号有什么不同? ##

*  Bots没有在线状态和last seen时间戳，界面只显示bot标签
 *  Bots有云存储限制，所以较旧的消息可能在服务器处理后不久被删除
 *  Bots无法主动与用户交流。用户必须将bot添加到群组中或者先给bot发送消息。其他人可以使用`telegram.me/<bot_username>`链接或者username来找到你的bot。
 *  Bot的username总是以'bot'结尾。
 *  当bot被加入群中，它默认不会接受所有消息。
 *  机器人不需要吃饭，睡觉或者抱怨(除非程序中有设定) \*\* 又是官方吐槽 \*\*

## 与众不同的Bot ##

Telegram bots在很多方面都与众不同 -- 我们提供两种样式的键盘以及提供对默认指令、深层链接以及文本格式等的额外接口。

内联请求模式

用户可以在任意聊天的输入框中通过输入内联请求和你的bot进行交互。只需在输入框中以你的bot命开头并输入请求即可。  
收到查询后，您的机器人可以返回一些结果。一旦用户点击其中一个，它就发送到用户当前打开的聊天。通过这种方式，人们可以通过任何聊天，小组或频道和您的bot进行互动。你可以使用[@sticker][sticker]来体验一下。

> 关于[内联模式][inline bots]的更多信息

[付款平台][Link 4]

[游戏平台][Link 5]

键盘

传统的机器人当然可以被教会理解人类的语言。但是有时候你想从用户那里获得更加规范化的输入，为此我们提供了自定义键盘。

每当你的机器人发送一条消息，它会传递一个特定的键盘与预定义的答复选项(请参阅[ReplyKeyboardMarkup][])，telegram会接收到消息并将你设定的键盘展示给用户。点击任何按钮将立即发送相应的命令。这样你可以大大简化用户与你的机器人交互。

> 有关自定义键盘的更多信息，请查阅[Bot API][bot API]的[sendMessage][]部分。

内联键盘和消息更新

有时候用户更喜欢可以不发送消息也能做一些事情。比如，当你的用户正在改变设置或翻阅搜索结果，在这种情况，你可以直接将内联键盘附加到所属的消息中。与自定义回复键盘不同，点击内联键盘上的按钮不会发送消息到当前聊天中。内联键盘支持按钮在后台工作，比如：callback buttons, URL buttons 和switch to inline buttons。

当使用回调按钮时，你的bot可以更新已经存在的消息(或者只是这些消息附加的键盘)所以这样能够保持聊天界面的整洁。你可以查看这些机器人的内联键盘的功能:[@music][music]、[@vote][vote]。

> [了解更多关于内联键盘和即时编辑的信息 >>][Link 6]

命令

命令提供了一个更灵活的方式与您的机器人进行通信。可以使用下面的语法：

/command [optional] [argument]

每个命令必须以‘/’开头且不能超过32个字符，命令可以使用拉丁字母，数字和下划线。下面是几个示例:

/get_messages_stats
    /set_timer 10min Alarm!
    /get_timezone London, UK

以斜线开头的消息总是被发送给机器人。telegram 将会这样处理:

*  当用户输入‘/’时，将会出现带有相应描述的命令提示(开发者提供给botFather相应的命令列表)。点击列表中的命令会立即发送命令。
 *  在和机器人的所有聊天的输入字段中显示一个额外的（/）按钮。点击它键入一个“/”并显示命令列表。
 *  在消息中将命令高亮显示，当用户点击突出显示的命令时，立即发送该命令。

如果多个机器人在一个组中，可以将bot用户名添加到命令中以避免混淆:

/start@TriviaBot
    /start@ApocalypseBot

这是通过建议列表选择命令时自动完成的，请记住你的bot需要能够处理跟在username后的指令。

全局命令

为了使所有的用户能够轻松应对各种bots的使用，我们要求开发者必须实现几个基础命令。telegram将会在界面中为这几个基础指令提供相应的快捷键。

*  / start - bots开始和用户交互，例如发送一个欢迎的消息。这个指令同样可以传递几个额外的参数给bot。
 *  / help - 返回一个帮助消息。
 *  / setting - 将会返回给用户一些机器人的功能设定，显示可以编辑设置的指令。

用户在第一次打开与您的机器人的对话时将看到一个start按钮。在机器人的配置菜单中有help和setting的链接。

隐私模式

bots经常被加入到组中来加强人与人之间的沟通。例如通过提供新闻，来自外部服务的通知或其他搜索功能。特别是那些工作聊天组。现在当你与bot共享一个组时，你会问问自己，我怎么能够保证这个小流氓(bot)不会将我的历史记录泄露给竞争对手呢？答案就是-隐私模式。运行在隐私模式下的bot不会收到所有发送给该组的消息。相反，它只会收到：

*  命令
 *  回复机器人自己的消息
 *  服务消息(人员的添加和删减)
 *  来自频道的消息

一方面，这有助于我们一些人在晚上更好地睡觉; 另一方面，它允许机器人开发人员节省大量的资源，因为他们每天不需要处理数以万计的不相关的消息。

所有的bots默认启用隐私模式，除了被加入组中当做管理员的bot(bot admin)总是收到所有的消息)它可以被禁用，以便机器人像普通用户一样接收所有消息。如果不必要，我们建议你不要这样做。用户可以随时在组成员列表中查看机器人的当前隐私设置。在大多数情况下，使用机器人消息的[强制回复][Link 7]选项应该是绰绰有余的。

[那么我的bot究竟会收到什么样的信息呢？>>][bot]

[深层链接][Link 8]

百度百科中对deeplink有下面这样的描述

> 移动端深度链接 是指在移动端网页或应用内输入搜索结果，可以链接到手机内安装的其他应用。

telegram bots有深层链接机制，允许在启动时将其他参数传递给机器人，这可能是一个启动机器人的命令，或者是一个身份验证令牌将用户的telegram帐户连接到某个外部服务上的帐户。

每个bot都有一个在telegram打开一个对话的链接。`https://telegram.me/<bot username>`您可以将参数start或startgroup添加到此链接，参数值最多为64个字符。例如：

https://telegram.me/triviabot?startgroup=test

`A-Z`,`a-z`,`0-9`,`_`和`-`都可以使用。我们建议使用base64url编码参数与二进制和其他类型的内容。

点击带有启动参数的链接将打开与bot的一对一对话，在输入栏位显示一个START按钮。如果使用startgroup参数，则会提示用户选择要添加机器人的组。一旦用户进行了确认(点击START按钮或者选择了一个组加入bot)，你的机器人将以这种格式接收一个来自该用户的消息：

/start PAYLOAD

`PAYLOAD`表示链接中传递的start或startgroup参数的值。

深层链接示例

假设网站example.com希望通过bot向用户发送通知。以下是他们为ID`123`用户开启通知进行的操作。

1.  创建一个有合适名字的bot，例如 @ExampleComBot
2.  为传入的消息设置[webhook][]
3.  生成足够长度的随机字符串。比如`$memcache_key = "vCH1vGWJxfSeofSAs0K5PA"`
4.  将值123和`$memcache_key`放在内存里缓存一小时。
5.  向用户显示按钮`https://telegram.me/ExampleComBot?start=vCH1vGWJxfSeofSAs0K5PA`(START按钮会附带参数)
6.  webhook使用来自start传来的参数(key)去查询内存，如果key存在，将传递给webhook的chat\_id记录为用户123的telegram\_chat\_id。从内存中移除key。
7.  现在，当我们想发送通知给用户123时，检查他们是否具有telegram\_chat\_id字段。如果有，那么就使用Bot API中的sendMessage发送消息。

位置和电话号码

一些bot需要获得用户额外的数据才能工作的更好。例如，知道用户的位置有助于提供更相关的地理位置特定的结果。用户的电话号码对于与银行等其他服务的集成非常有用。

bot可以使用特殊按钮询问用户的位置和电话号码。请注意，电话号码和位置请求按钮只能用于私人聊天。

当按钮被按下后，telegram将显示一个确认提醒，告诉用户即将发生的事情。

## BotFather ##

BotFather是管理所有bot的机器人。它将帮助您创建新的机器人和更改现有机器人的设置。

创建一个新的bot

使用 **/ newbot** 命令来创建一个新的机器人。 BotFather会要求你提供一个名字和用户名，然后为你的新机器人生成一个授权令牌。

您的机器人的名称显示在联系方式和其他地方。

**Uername** 是一个简称。用户名长度为532个字符，不区分大小写，但只能包含拉丁字符，数字和下划线。你的机器人的用户名必须以“bot”结尾。

**token** 是一串了类似 `110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw` 的字符串。  
用于授权bot并向Bot API发送请求。

生成授权令牌

如果您的现有令牌受到威胁，或者由于某种原因而丢失了该令牌，请使用/ token命令生成一个新的令牌。

BotFather Commands

> 命令很简单，此处略过，请读者自己尝试。

状态警报

百万个用户因为telegram的快速响应选择我们，为了能够保证开发者的bot能时刻处在正常状态。所以当你的bot出现问题时，botfather会给你发送一个状态警报。

我们将会检查热门bot的回复数目以及 请求/响应 转换率。如果我们得到异常低的读数，您将收到Botfather的通知。

响应警报

默认情况下，每个机器人每小时只能获得一个警报。每个警报都有以下按钮：

*  **Fixed** 如果你发现你的机器人有问题并修复它，请使用它。如果按下修复按钮，我们将继续以常规方式继续发送警报，以便您能够在5-10分钟内查看您的修复是否工作，而不必等待一个小时。
 *  **Support** 如果您没有看到您的机器人有任何问题，或者如果您认为问题在我们这边，可以使用它来打开与[@botsupport][botsupport]的聊天。
 *  **Mute for 8h/1w** 如果您目前无法修复您的机器人，请使用此功能。这将在指定的时间段内禁用问题机器人的所有警报。我们不建议使用此选项，因为您的用户可能会迁移到更稳定的机器人。您可以通过Botfather取消您的机器人设置中的警报静音。

Monitored issues(监控)

1.  `Too few **private messages** are sent compared to previous weeks: **{value}**`  
    你的机器人发送的信息要少于前几周,这对通讯类型的机器人很有用。
2.  `Too few replies to incoming **private messages**. Conversion rate: **{value}**`  
    您的机器人不会回复发送给它的所有消息(您的机器人的请求/响应转换率在过去的三个5分钟内至少有两次是太低)。为了提供良好的用户体验，请回复发送给您的机器人的所有消息。
3.  `Too few answers to **inline queries**. Conversion rate: **{value}**`  
    您的机器人不会回复正在发送给它的所有内嵌查询，其计算方式与上述相同。
4.  `Too few answers to callback queries. Conversion rate: {value}`  
    `Too few answers to callback game queries. Conversion rate: {value}`

你的机器人没有回复正在发送给它的所有回调查询,其计算方式与上述相同。

> 请注意，状态提醒功能仍在测试中，将来会有所改进。

以上就是介绍。阅读完此部分说明您现在已经准备好进入[BOT API][bot API]手册。

[Link 1]: https://github.com/yangsoon/yangsoon.github.io/issues/21#inline-mode
[bot API]: https://core.telegram.org/bots/api
[Link 2]: https://core.telegram.org/bots
[aiotg_telegram]: https://github.com/yangsoon/yangsoon.github.io/issues/23
[TechCrunch Bot]: https://t.me/TechCrunchBot
[Gmail Bot]: https://t.me/gmailbot
[Markdown]: https://t.me/Bold
[GameBot]: https://t.me/gamebot
[HotOrBot]: https://t.me/hotorbot
[inline bots]: https://core.telegram.org/bots/inline
[BotFather]: https://telegram.me/botfather
[Link 3]: https://core.telegram.org/bots/samples
[sticker]: https://telegram.me/sticker
[Link 4]: https://core.telegram.org/bots#payments-platform
[Link 5]: https://core.telegram.org/bots#gaming-platform
[ReplyKeyboardMarkup]: https://core.telegram.org/bots/api/#replykeyboardmarkup
[sendMessage]: https://core.telegram.org/bots/api#sendmessage
[music]: https://telegram.me/music
[vote]: https://telegram.me/vote
[Link 6]: https://core.telegram.org/bots/2-0-intro#new-inline-keyboards
[Link 7]: https://core.telegram.org/bots/api#forcereply
[bot]: https://core.telegram.org/bots/faq#what-messages-will-my-bot-get
[Link 8]: https://en.wikipedia.org/wiki/Deep_linking
[webhook]: https://core.telegram.org/bots/api#setwebhook
[botsupport]: https://github.com/botsupport