写给开发者的telegram-bot手册(翻译)
juejin.imbots是运行在telegram内部的第三方应用。用户可以通过发送消息,命令或者内联请求和bots进行交互。开发者可以通过向bot API发送HTTPS请求来控制自己的bot。
因为最近对telegram bot产生了兴趣,想创建一个bot试一试,因为网上没有找到相关的中文文档,所以就自己跟着自己的理解和Google Translate翻译了介绍文档,文中一定有表述不对的地方,我会在之后编写bot的时候进行修改,建议大家阅读的时候参照原文档一起阅读。
我能用bots做什么?
下面举几个例子,你可以用bot来:
bots是如何工作的?
Telegram Bots是一个特别的账号并不需要另外的手机号码去创建,用户可以通过下面两种方式和机器人交互。
- 创建和bots的聊天并发送消息和命令或者将机器人加入聊天群。这对聊天机器人和官方新闻机器人很有用。
- 直接在输入框中键入
@username query
来发送请求。这样可以通过内联机器人直接发送内容到任何的聊天,群或者频道。
用户发送的消息,命令,和请求被转发给运行在你服务上的应用。我们的中介服务器帮你处理消息的加密和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命开头并输入请求即可。
收到查询后,您的机器人可以返回一些结果。一旦用户点击其中一个,它就发送到用户当前打开的聊天。通过这种方式,人们可以通过任何聊天,小组或频道向您的机器人请求内容。
你可以使用@sticker来体验一下。
关于内联模式的更多信息
键盘
传统的机器人当然可以被教会理解人类的语言。但是有时候你想从用户那里获得更加正式的输入–因此我们提供了自定义键盘。
每当你的机器人发送一条消息,它会传递一个特定的键盘与预定义的答复选项(请参阅ReplyKeyboardMarkup),telegram会接收到消息并将你设定的键盘展示给用户。点击任何按钮将立即发送相应的命令。这样你可以大大简化用户与你的机器人交互。
内联键盘和即时更新
有时候用户更喜欢可以不发送消息也能做一些事情。比如,当你的用户正在改变设置或翻阅搜索结果,在这种情况,你可以直接将内联键盘附加到所属的消息中。与自定义回复键盘不同,点击内联键盘上的按钮不会发送消息到当前聊天中。内联键盘支持按钮在后台工作,比如: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)总是收到所有的消息)它可以被禁用,以便机器人像普通用户一样接收所有消息。如果不必要,我们建议你不要这样做。用户可以随时在组成员列表中查看机器人的当前隐私设置。在大多数情况下,使用机器人消息的强制回复选项应该是绰绰有余的。
百度百科中对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
用户开启通知进行的操作。
- 创建一个有合适名字的bot,例如 @ExampleComBot
- 为传入消息设置webhook
- 生成足够长度的随机字符串。比如
$memcache_key = "vCH1vGWJxfSeofSAs0K5PA"
- 将值123和
$memcache_key
放在内存缓存一小时。 - 向用户显示按钮
https://telegram.me/ExampleComBot?start=vCH1vGWJxfSeofSAs0K5PA
(START按钮会附带参数) - webhook使用来自start传来的参数(key)去查询内存,如果key存在,将传递给webhook的chat_id记录为用户123的telegram_chat_id。从内存中移除key。
- 现在,当我们想发送通知给用户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(监控)
Too few **private messages** are sent compared to previous weeks: **{value}**
你的机器人发送的信息要少于前几周,这对通讯类型的机器人很有用。Too few replies to incoming **private messages**. Conversion rate: **{value}**
您的机器人不会回复发送给它的所有消息(您的机器人的请求/响应转换率在过去的三个5分钟内至少有两次是太低)。为了提供良好的用户体验,请回复发送给您的机器人的所有消息。Too few answers to **inline queries**. Conversion rate: **{value}**
您的机器人不会回复正在发送给它的所有内嵌查询,其计算方式与上述相同。Too few answers to **callback queries**. Conversion rate: **{value}**
Too few answers to **callback game queries**. Conversion rate: **{value}**
你的机器人没有回复正在发送给它的所有回调查询,其计算方式与上述相同。
请注意,状态提醒功能仍在测试中,将来会有所改进。
以上就是介绍。阅读完此部分说明您现在已经准备好进入BOT API手册。
如果您有任何问题,请查看我们的Bot FAQ »
Source juejin.im