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

[yangsoon]

封面地址：炎炎消防队

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

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

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

如果你已经熟悉bot的操作模式，那还等什么看快来看这篇 基于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?

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

你也可以查看一些 示例代码

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来体验一下。

关于内联模式的更多信息

付款平台

游戏平台

键盘

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

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

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

内联键盘和消息更新

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

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

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

命令

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

/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)总是收到所有的消息)它可以被禁用，以便机器人像普通用户一样接收所有消息。如果不必要，我们建议你不要这样做。用户可以随时在组成员列表中查看机器人的当前隐私设置。在大多数情况下，使用机器人消息的强制回复选项应该是绰绰有余的。

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

深层链接

百度百科中对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向用户发送通知。以下是他们为ID123用户开启通知进行的操作。

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的聊天。
• 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 FAQ »