Telegram API
我们为开发者提供三类 API。 Bot API 让你轻松创建以 Telegram 消息为界面的程序。 Telegram API 和 TDLib 让你构建自己的定制 Telegram 客户端。两个 API 均可免费使用。最后, Gateway API 让任何企业、应用或网站都能通过 Telegram 发送验证码,而不必使用传统短信。
你还可以把 Telegram 小组件 添加到你的网站。
欢迎设计师创作 动态贴纸与表情符号 或 自定义主题 等作品,供 Telegram 使用。
Bot API
该 API 让你可以把机器人连接到我们的系统。 Telegram 机器人 是一种特殊账户,创建时无需额外的电话号码。这些账户可作为你服务器上运行代码的接口。
使用它时,你完全不需要了解我们的 MTProto 加密协议如何工作——我们的中转服务器会为你处理所有加密及与 Telegram API 的通信。你只需通过一个简单的 HTTPS 接口与这台服务器通信,该接口提供了简化版的 Telegram API。
机器人开发者还可以使用我们的 Payments API 以接收 付款 ,来自全球各地的 Telegram 用户。
TDLib——打造你自己的 Telegram
即使你追求最大程度的定制,也不必从零开始开发应用。试试我们的 Telegram Database Library (或简称 TDLib),这是一款面向第三方开发者的工具,让你轻松构建快速、安全、功能丰富的 Telegram 应用。
TDLib 会处理好所有 网络实现 细节、 加密 和 本地数据存储等问题,让你能把更多时间投入到设计、响应式界面和精美动画上。
TDLib 支持所有 Telegram 功能,让在任何平台上开发 Telegram 应用都轻而易举。它可用于 Android、iOS、Windows、macOS、Linux 以及几乎所有其他系统。该库开源,并且几乎兼容 任何编程语言.
Gateway API
Telegram Gateway API 让任何企业、应用或网站都能通过 Telegram 发送验证码,而不必使用传统短信——这是一种强大而便捷的方式,可以 降低成本 同时提升 安全性 和 送达速度 ——将验证码送达 Telegram 的 10 亿月活跃用户。用户将 立即收到 Telegram 内一个专属聊天中的验证码消息。
Telegram API
该 API 让你构建自己定制的 Telegram 客户端,对希望在平台上创建 Telegram 应用的所有开发者 100% 开放。欢迎研究现有 Telegram 应用的开放 源代码 ——从中学习各项功能的实现方式。别忘了 注册 你的应用到我们的系统中。
快速上手
创建应用
如何获取应用标识符并创建新的 Telegram 应用。
用户授权
如何注册用户手机号以开始使用 API。
两步验证
当用户启用两步验证后,如何登录其账户,以及如何更改密码。
二维码登录
二维码 登录流程。
通行密钥
Telegram 允许你在设备上创建通行密钥,用 PIN 码或 Face ID、指纹等生物识别数据即可快速登录 Telegram,而无需使用短信验证码。
错误处理
如何正确处理 API 返回的错误。
应对不同的数据中心
如何连接最近的数据中心接入点以更快与 API 交互,以及开发客户端时的注意事项。
处理更新
如何订阅并妥善处理更新。
处理推送通知
如何订阅并妥善处理推送通知。
频道、超级群组、千人群和普通群组
如何处理频道、超级群组、千人群和普通群组,以及它们之间的区别。
论坛
Telegram 允许创建包含多个不同话题的论坛。
机器人也可以使用话题,前提是通过 @botfather.
向频道发送私信
Telegram 支持向频道发送私信,也可用于向频道投稿建议(甚至付费的)帖子。
频道统计
Telegram 为频道和超级群组提供详细统计。
消息浏览量与已读指标
如何上报已读状态、频道帖子浏览量、消息已读指标和音乐播放量。
调用方法
调用方法时的附加选项。
上传和下载文件
如何正确传输大批量数据。
分页
如何从大型对象列表中获取结果。
客户端配置
MTProto API 有多个客户端配置参数,可通过相应方法获取。
通话
Telegram 支持端到端加密的一对一通话。
群组通话
Telegram 支持端到端加密的群组通话。
安全
私密聊天与端到端加密
端到端加密的消息收发。
安全准则
客户端应用中必须执行的重要检查。
完美前向保密
将临时授权密钥绑定到永久密钥。
语音和视频通话中的端到端加密
端到端加密的通话。
群组通话中的端到端加密
端到端加密的群组通话。
私密聊天中的完美前向保密
重新生成私密聊天密钥,以提供完美前向保密。
私密聊天中的序列号
How to assign and interpret seq_no counters in secret chats.
优化
客户端优化
提升 API 交互效率的方法。
API 方法
可用方法列表
可用高层方法的列表。
API TL 架构, JSON 版本
API 中所用类型和方法的文本及 JSON 展示。
Layer 更新日志
可用架构版本的详细更新日志。
其他文章
使用 MTProto API 开发机器人
如何使用 MTProto API 开发机器人。
AI 功能
Telegram 提供许多 AI 功能,由 Cocoon 驱动——这是一个去中心化网络,旨在最大程度保护隐私。
Bot API 对话 ID
Bot API 对话 ID 是由用户、聊天、频道和私密聊天 ID 序列衍生出的单一、唯一 64 位 peer ID 序列,并在所有这些序列中保持唯一。
本页 说明了如何在 MTProto peer ID 与 Bot API 对话 ID 之间相互转换。
托管机器人
用户可以创建 托管 机器人(由特定的管理机器人控制),直接通过 MTProto API 完成,无需经过 @BotFather.
命令
机器人 提供一组命令,用户可以在私聊或聊天中使用。
按钮
用户可以通过 按钮 甚至 内联按钮,直接从内联 消息 在 任意 聊天中操作。
菜单按钮
机器人可以选择文本输入框旁菜单按钮的行为。
内联查询
用户可以通过 内联查询,直接从 文本输入框 在 任意 聊天中操作。
游戏
机器人可以向用户提供 HTML5 游戏,供单人游玩,或在群组和一对一聊天中相互竞技;以及如何在 MTProto API 中使用游戏。
迷你应用
机器人可以向用户提供可交互的 HTML5 迷你应用 ,彻底取代 任何网站。.
联盟计划
开发者可以为自己的 迷你应用 开通联盟计划——让 内容创作者、其他 迷你应用开发者 和 任何 Telegram 用户 来推广它,并从其推荐用户的购买中获得佣金。
附件菜单
机器人可以添加附件菜单项,提供便捷易用、功能多样的迷你应用。
编辑机器人信息
用户可以编辑和本地化自己拥有的机器人的头像、名称、简介和说明;机器人自身也可以完成这些操作。
AI 机器人
Telegram 机器人为 AI 聊天机器人提供多项功能。
访客模式
访客机器人可通过用户名从任何非私密私聊、群组和超级群组中调用,结果会直接发布到聊天中,即使它们并非成员。
机器人与机器人通信 »
如果启用了机器人与机器人通信模式,机器人可以在群组、私聊和聊天中收发其他机器人的消息。
动态
Telegram 用户和频道可以轻松发布和查看 动态 ,这一切都可通过 API 实现。
相似频道和机器人
API 提供一种方法,可获取主题相似的公开频道和机器人列表,依据其 订阅者群体.
强调色
Telegram 用户和频道可以更改个人资料页和消息的强调色与背景图案!
隐私设置
Telegram 允许用户进行细粒度的隐私设置,选择哪些用户能以特定方式与他们互动。
搜索与过滤器
Telegram 允许在聊天中查找消息时应用详细的过滤器。
这使服务器能够根据文本查询乃至消息类型过滤消息;图形客户端常用此功能实现聊天图库、聊天头像等功能。
投票
Telegram 允许发送投票和测验,在聊天和频道中可以有成千上万(甚至数百万)用户参与投票。
清单
Premium 用户现在可以在任意聊天中创建协作清单,用于跟踪任务、协调团队,或是管理购物和待办清单。
回应
Telegram 允许用户用特定表情符号回应任何消息,并触发可爱的 Lottie 动画。
动态消息特效
Telegram 允许为你发送的消息添加炫目的动态特效。
表情符号分类
贴纸、自定义表情符号和 GIF 选择界面应提供分类列表,以便按表情符号(列表)或其他条件快速筛选结果。
表情符号状态
Telegram 允许用户将表情符号或 自定义表情符号 设为状态,显示在聊天和资料中的名字旁。
邀请链接与加入请求
频道、普通群组和超级群组可以有公开用户名或私密邀请链接:私密邀请链接还可以通过按用户审批的加入请求进一步增强。
频道、超级群组和群组的管理员、封禁与默认权限
如何处理频道、群组和超级群组中的管理员权限、细粒度封禁和全局权限。
讨论组
群组 可以与 频道 关联为 讨论组,让用户可以在其中讨论帖子。
频道评论与消息回复串
Telegram 可以让用户评论 频道帖子 或一般 群组消息,这得益于消息回复串。
管理日志
超级群组和频道都提供一种所谓的 管理日志,记录超级群组和频道近期的相关操作,如修改群组/频道设置、以管理员身份发布信息、踢出和封禁用户等。
置顶消息
Telegram 允许在特定聊天顶部置顶多条消息。
群组成员/管理员标签
群聊成员(普通群组和超级群组均可)现在可以添加一个 标签 在名字旁,用于展示他们的工作职位、在校所学内容等。
提及
Telegram 允许用户在紧急的小鸭子事务中提及其他用户,并快速跳转到这些提及处,以便尽可能迅速地阅读。
定时消息
Telegram 允许定时发送消息。
实时地理位置
Telegram 允许在聊天中发送用户的实时地理位置,还可选择设置接近提醒。
Peer 数据库
如何在 API 中处理 peer 信息。
Min 构造函数
有时, 用户 和 频道 构造函数在群聊更新中可能不包含用户的完整信息:本页说明如何处理这类构造函数。
账号删除
如何删除 Telegram 账号。
导入的消息
Telegram 允许从其他聊天应用导入消息和媒体。
Telegram Passport
如何 Telegram Passport 直接使用 MTProto API。
Telegram 支付
如何直接使用 MTProto API 处理 Telegram 支付。
第三方验证
为了进一步提升 Telegram 的透明度, 官方第三方服务 能够分配 额外验证图标 给用户账号和聊天——以 防止诈骗 和 减少错误信息.
使用消息实体创建样式化文本
如何使用消息实体创建样式化文本。
处理 GIF
Telegram 客户端支持显示 GIF。
处理贴纸
Telegram 客户端支持显示动态、静态和视频贴纸。
处理自定义表情符号
Telegram 允许在消息中直接加入自定义的动态、静态和视频表情符号。
处理动态表情符号
图形版 Telegram 客户端应将表情符号转换为相应的动态版本。
处理动态骰子
Telegram 支持发送 动态骰子 表情符号。
消息草稿
如何处理消息草稿。
文件夹
处理文件夹。
热门 peer 评分
如果 已启用,则 热门 peer 的评分会显示某个常用 peer 在特定 分类 中的相关度(经常发消息的用户、常用机器人、内联机器人、经常访问的频道等)。
处理文件引用
如何处理文件引用。
无缝 Telegram 登录
处理无缝 Telegram 登录 URL 授权请求。
壁纸
如何处理聊天背景。
通知铃声
如何处理聊天通知铃声。
消息转写
如何转写语音消息。
消息翻译
Telegram 允许翻译聊天消息, Telegram Premium 用户甚至可以启用聊天实时翻译。
原生反垃圾系统
成员数量达到一定规模的超级群组管理员,可以充分释放 Telegram 自有反垃圾算法的主动防御能力——为自动垃圾信息过滤器开启全新的激进模式。
收藏品
Telegram 用户可以让他人轻松联系自己,或通过 用户名找到自己的公开群组和频道;客户端还可以分配多个 Fragment » 可收藏用户名 给自己的账号、超级群组和频道; Fragment » 还允许购买可用于注册 Telegram 账号的手机号收藏品。
Telegram Premium
Telegram Premium 是一项可选订阅服务,可解锁更多专属的客户端和 API 端功能,同时也为应用开发提供支持。它是 Telegram 可持续变现 的一部分——由用户驱动,而非广告商或股东。这样,Telegram 才能保持独立,并始终将用户放在首位。
Telegram Business
用户可以将自己的 Telegram 账号变为 商业账号,从而获得营业时间、位置、快捷回复、自动消息、自定义起始页、聊天机器人支持等商业功能。
大多数 Telegram Business 功能面向 Telegram Premium » 订阅用户开放; 关联的商业机器人 » 也向非 Premium 用户开放。
Telegram Stars
Telegram Stars 是一种虚拟物品,让用户可以在 Telegram 生态内从机器人和迷你应用购买数字商品与服务、向 Telegram 平台上的内容创作者赠送礼物等。
订阅
机器人和频道可以创建订阅,定期向用户收取一定数量的 Telegram Stars 以换取内容和服务。
受保护的内容
Users and bots who want to keep their messages private, as well as Group and Channel owners who want to keep their content members-only can restrict message forwarding from their chat, which also prevents screenshots, disables message forwards (attempting to forward protected messages will emit a CHAT_FORWARDS_RESTRICTED RPC error) and limits the ability to save media from posts.
礼物
用户可以发送 礼物 给朋友。收到礼物的人可以在个人资料页展示它们,或将它们兑换为 Telegram Stars »。Telegram Stars 用途广泛,包括支持创作者和购买迷你应用中的服务。
收藏品礼物拍卖
为保证 收藏品礼物的公平分配,新礼物的发行将采用 拍卖 形式——让用户可以用 Stars 分多轮竞拍新礼物。
付费媒体
内容创作者可以接收 Stars ,只要在自己的频道上发布 付费照片或视频 即可。订阅者需先向作者付费解锁,才能查看这类帖子。
付费消息
Telegram Stars 可用于向已配置 Star 消息 »的用户、超级群组和频道付费发消息,每条消息都需付费。
推荐帖子
Telegram 为频道管理员提供一项强大的变现功能: 推荐帖子.
频道和超级群组助推
Telegram Premium 用户可以向喜爱的频道授予额外功能,例如发布 动态 ——只需给频道赠送 助推.
抽奖与礼物
Telegram 频道 管理员可以发起抽奖,随机向粉丝发放 Telegram Premium 订阅和其他礼物,以换取 助推.
操作栏
有时,在通过私聊或私密聊天与 Telegram 用户互动时,必须在聊天顶部显示一个操作栏,其中提供便捷的操作按钮或关于该用户的提示。
收藏夹
收藏夹聊天让用户可以收藏消息和媒体:它是个人云存储空间,可存放你想发送或转发到那里的任何消息或媒体。
个人资料
Telegram 为你的个人资料提供丰富的自定义选项!
主题
Telegram 应用支持生成、分享和同步应用主题。
赞助消息
如果你的应用允许访问来自 Telegram 频道的内容,则必须支持 官方赞助消息 在 Telegram 频道中的展示。
频道和机器人广告收入
在社交媒体史上,Telegram 拥有 最慷慨的奖励体系 之一。Telegram 频道和机器人所有者现在可以获得 50% 的广告收入,这些广告展示在他们的频道和机器人中。
本页介绍提取频道和机器人广告收入以及查看详细收入统计的方法。
事实核查
Telegram 客户端支持显示独立事实核查者为消息添加的事实核查。
联系人
在 API 中处理联系人。
屏蔽列表
处理屏蔽列表。
年龄验证
一些法规要求查看受限内容前须进行年龄验证:Telegram 借助一个特殊机器人的 主迷你应用 来实现这一功能。
Web 事件
在与 HTML5 游戏和支付网关网站交互时,Telegram 应用应提供以下 JS API。
深度链接
Telegram clients must handle special tg:// 和 t.me deep links encountered in messages, link entities and in other apps by registering OS handlers.
数据导出
Telegram API 允许用户通过 takeout API 导出自己的全部信息。
服务条款
所有第三方客户端应用都必须遵守的服务条款。