Telegram 广告 API 和集成：自动化您的工作流程

Telegram 没有发布面向广告主的 API：它的开发者网站列出了 Bot API、客户端 API、TDLib、Gateway API 和 Payments API，其中没有一个能创建广告系列或提供广告报告。ADSLY 通过已授权的会话连接您的广告账户，并在其上提供三个集成入口：读取您的统计数据、经您允许还能管理广告系列的 REST API，带签名的 webhook，以及接收追踪器转化的端点。

Telegram Ads 的「API」是怎么回事

Telegram 的广告平台位于 ads.telegram.org ，通过网页界面操作。我们在 2026 年 10 月核对了 Telegram 的开发者文档：core.telegram.org 介绍了 Bot API（含面向机器人的 Payments API）、TDLib、Gateway API，以及用于开发客户端应用的 Telegram API。与广告相关的文章有两篇：Sponsored Messages 讲的是客户端应用如何展示广告，另一篇讲的是频道和机器人所有者的广告收入；两篇都不是写给管理广告系列的广告主的。平台自己的 入门指南 也没有提到任何 API。

因此，ADSLY 通过拥有该广告账户的 Telegram 账号的会话来工作。连接账户有三种方式：输入手机号并在 Telegram 里确认请求；在已登录 ads.telegram.org 的情况下使用我们的浏览器扩展；或者自己粘贴会话令牌。这个请求只连接广告账户，不涉及您的个人 Telegram。来自 Adstat 的账户用您的 Adstat 登录信息连接。连接之后，Euro、TON 和 Stars 账户的处理方式完全相同。

账户连接后 ADSLY 能做什么

在网页界面里要一下一下点的操作，在面板里都变成一个动作：

创建广告系列 ——单个广告系列的完整设置，或批量生成：多条文案 × 多个链接 × 一份频道列表，还可以选择按国家、主题或设备各拆成一个广告系列。

调整 CPM 和预算 ——为所有选中的广告系列设定、提高或降低出价，按金额或按百分比；增加预算、减少预算，或把剩余预算取回。

暂停、恢复和删除 ——针对选中项、某个分组，或符合当前筛选条件的全部广告系列。

统计同步 ——每个广告系列的展示、点击、行动、花费、CTR 和 CPM 每小时保存一次。

修改文案、标题和素材 ——批量修改，无需重新创建广告系列。

余额监控 ——首页列出每个账户的余额，以及投放中、审核中、被拒和已停止的广告系列数量，每次同步时更新。

数据导出与报告

面板保存的历史比单个统计页显示的更多，而且可以带走：

导出为 Excel、CSV 和 PDF ——包含所选列的数据文件，或一份 PDF 报告，范围可以是整个账户、一个分组或选中的广告系列。Pro 和 Agency 套餐可用。

小时级表现数据 ——每个广告系列每小时一份快照，保留 30 天；更长的周期使用每日合计。我们没有跨账户的分时段基准数据，所以请用您自己广告系列的小时图表来找出适合您的时段。

全账户分析 ——分析页面把您有权访问的每个账户的展示、点击和行动加在一起。花费仍按货币分开：欧元、TON 和 Stars 永远不会相加。

变更历史 ——广告系列的每一次状态、出价和预算变更都会记录下来，并注明是谁或什么做的，包括规则和 Auto CPM。

自动化钩子

规则和自动动作在每次每小时同步之后运行，不需要有人盯着面板：

IF/THEN 规则 ——条件可以基于展示、点击、行动、CTR、CVR、花费、CPC、CPA、CPM 和预算，每个条件按全部时间或最近 1–168 小时衡量。动作包括：暂停、启用、设定 CPM、按金额或百分比提高或降低 CPM、增加或减少预算，或只发通知。例如：如果最近 6 小时的 CPM 高于 €2.50，就把出价降低 15%。规则可以挂在单个广告系列、一个分组、一批选中项或整个账户上。

基于您自己转化的规则 ——追踪器开始回传 postback 之后，同一个引擎可以依据线索、转化、购买、收入、ROAS、单个线索成本和单笔销售成本来执行动作。不发送 postback 的账户绝不会被这类规则暂停：没有数据被视为未知，而不是零。

跨账户的规则草稿 ——保存的草稿存放在您的 ADSLY 登录下， 应用到账户 （Apply to cabinets）会把它复制到您勾选的每个账户。

Auto CPM ——面板每小时检查一次广告是否真的出现在它定向的频道和机器人里。在大多数地方能看到：出价降低 10%。在大多数地方看不到：出价提高 10%。需要连续两次检查得出相同结论，两次调整之间间隔三小时，每个广告系列每天最多调整六次。

Recreate 与 AI Recreate ——被拒的广告会自动重新提交；使用 AI Recreate 时，每次尝试都会改写文案。我们不公布它的挽回比例。

代理商的集成场景

这些组件可以搭出四种做法：

客户报告 ——按客户账户或分组导出 PDF 或 Excel 文件，或把 /v1/stats 拉进您已经在用的报告工具。

提醒 ——动作为「通知」的规则会进入每小时摘要，摘要通过 Telegram、邮件或应用内送达。对于您自己的系统，status_change webhook 会在广告系列变为 Declined、Active 或其他任何状态时触发。

自建看板 —— /v1/stats/total 返回每个账户的合计和图表数据点；一次典型的同步只需三四个请求，远低于每个密钥每分钟 60 次请求的限制。

与追踪器形成闭环 ——把线索和销售发到 postback 端点，广告系列表格就会在 Telegram 自己的列旁边显示单个线索成本和单笔销售成本。面板里有 Keitaro、RedTrack、Binom 和 Voluum 的现成 postback 模板，可直接粘贴。

ADSLY REST API 与 webhook

API 已对 Pro 和 Agency 账户开放。在菜单里打开 API ，点击 新建密钥 （+ New key），然后选择这个密钥能访问哪些账户（一个、几个或全部），以及是否允许它管理广告系列。同时最多可以有五个有效密钥。

基础 URL： https://app.adsly.pro/api/v1 · 认证： 请求头 X-API-Key · 速率限制： 每个密钥每分钟 60 次请求

每个密钥都可以读取：

• GET /v1/account/info ——此密钥能看到的账户

• GET /v1/campaigns ——广告系列及其指标；可按状态、标题、机器人或频道用户名、落地页域名和广告类型筛选；游标分页

• GET /v1/stats ——某一周期内每个广告系列的统计，按账户分组

• GET /v1/stats/total ——每个账户的合计和图表数据点

• GET /v1/stats/analytics ——周期分析，含热门广告系列

• GET /v1/campaigns/:adId/history ——单个广告系列在一段周期内的数据

• GET /v1/conversions ——通过 postback 收到的转化，按广告系列汇总

管理广告系列 （Manage campaigns）。只要您没有为密钥打开这个开关，它就只能读取。打开之后，密钥还可以创建广告系列（每次调用最多 100 个），修改文案、链接、CPM 和每日上限，暂停和恢复，追加预算或取回剩余预算，复制，一次对最多 1,000 个广告系列执行批量操作，删除，以及上传素材。任何密钥都无法把钱从账户里转走：预算只在账户余额和它的广告系列之间流动。通过 API 做的每一项改动都会显示在面板里该广告系列的历史中；创建、预算、复制和批量操作的调用支持 Idempotency-Key，超时后重试不会重复执行。

完整文档见 adsly.pro/docs/api（英文），每一页都有 Markdown 版本，另有供 AI 助手使用的 llms.txt 索引。

初次集成最容易在两件事上出错。金额字段（spent、budget、cpm、cpc、cpa、ctr）以字符串返回，为的是保留精度，做运算前请先解析成数字。另外，ad_id 只在单个账户内唯一——Telegram 会重复使用编号——所以务必把它和 account_id 一起保存。

Webhook。 给密钥设置一个 Postback URL，ADSLY 就会向它发送带签名的 JSON：同步时广告系列状态变化会发 status_change；每个整点过后五分钟发 hourly_digest，内容是刚结束的那一小时里每个广告系列的展示、点击、花费和行动。每个请求都在 X-Adsly-Signature 里带有 HMAC-SHA256 签名，并附时间戳和唯一的投递编号。端点必须是公开的 HTTPS 地址；投递失败会重试一次。

接收转化。 在密钥上打开 接收 postback （Receive postbacks），然后要么从您的后端调用 POST /v1/postback 并在请求头里带上密钥，要么把 生成追踪器 URL （Generate tracker URL）给出的只写 URL 填进追踪器。事件类型为 lead、conversion 和 purchase，金额和货币可选；一个请求最多可带 1,000 个事件，每个密钥每秒接受 20 个事件。事件通过广告链接里携带的值匹配到广告系列：机器人广告用 ?start= 参数，网站广告用您追踪器自己的参数。

安全与访问

这些账户里放的是真实预算，所以每个入口都有意做得很窄：

用会话，不用密码 ——Telegram Ads 账户通过在 Telegram 里确认请求、浏览器扩展或会话令牌来连接。连接只覆盖广告账户，不涉及您的个人 Telegram。

默认只读，以哈希存储 ——在所有者打开“管理广告系列”之前，密钥只能读取；即使打开了，也无法把钱从账户里转走。密钥以 SHA-256 哈希保存，所以丢失的密钥无法找回，只能吊销后换新。

带签名的 webhook ——请校验 HMAC 签名，并拒绝时间戳超过五分钟的请求。ADSLY 拒绝向非 HTTPS、回环或内网地址投递。

按账户分配团队权限 ——在 Agency 套餐里，每位成员对每个账户的权限是 Viewer、Manager 或无权限。成员可以自己创建 API 密钥，密钥只能访问共享给该成员的账户：他是 Viewer 的账户只读，是 Manager 的账户可以修改。

让您的 Telegram Ads 工作流程自动化。 ADSLY 管理着 500,000+ 个广告系列——Euro 账户可以为任何国家开通。三种账户类型全部支持（TON、Euro、Stars）。IF/THEN 规则、批量操作、用于统计和广告系列管理的 API、webhook 和导出。免费开始 — 3 天 Pro 试用 →

常见问题

Telegram Ads 有公开的 API 吗？

面向广告主的没有。Telegram 的开发者网站列出了 Bot API、客户端 API、TDLib、Gateway API 和 Payments API（2026 年 10 月核对）；它们都不能管理广告系列，Sponsored Messages 章节是写给展示广告的应用的。ads.telegram.org 上的广告平台通过网页界面操作。ADSLY 通过已授权的会话在它之上工作。

ADSLY 如何连接我的 Telegram Ads 账户？

通过拥有该广告账户的 Telegram 账号的会话。您输入手机号后在 Telegram 里确认请求，或使用浏览器扩展，或粘贴会话令牌。这个请求只连接广告账户。Euro、TON 和 Stars 账户都这样连接；来自 Adstat 的账户用 Adstat 登录信息连接。

我的 Telegram Ads 数据在 ADSLY 安全吗？

各个集成入口在设计上就很窄。API 密钥在您打开“管理广告系列”之前只能读取，永远无法把钱从账户里转走，并以哈希存储；通过 API 做的每项改动都会记入广告系列历史；webhook 用每个密钥专属的 secret 签名，只发往公开的 HTTPS 端点；给追踪器的只写 URL 能提交转化，但读不到任何数据；在 Agency 套餐里，权限按账户、按人授予。

可以把 Telegram Ads 数据导出到 Google Sheets 吗？

没有直接的 Google Sheets 连接器。请从面板导出 CSV 或 Excel 文件后导入，或用脚本读取 API——/v1/stats 可以返回任意周期内每个广告系列的数字。

ADSLY 支持 Telegram Ads 的 webhook 吗？

支持。设置了 Postback URL 的密钥会在广告系列状态每次变化时收到 status_change，并每小时收到一次 hourly_digest，内含每个广告系列的展示、点击、花费和行动。两者都用 HMAC-SHA256 签名，密钥上的 Test 按钮会发送一次 ping，方便您检查接收端。

ADSLY REST API 现在可以用了吗？

可以，Pro 和 Agency 套餐都支持，密钥由您自己在面板里创建。每个密钥都能读取账户列表、广告系列、统计、分析、单个广告系列的历史和已收到的转化，每个密钥每分钟 60 次请求。打开“管理广告系列”的密钥还可以创建、编辑、暂停、恢复、充值、复制和删除广告系列，并上传素材。文档：adsly.pro/docs/api。