什么是推送通知 API?什么时候需要它?

推送通知 API 是一种 Web 服务:当你的代码发出请求时,它会把一条消息显示在手机锁屏上。你发送一个包含标题和正文的 HTTP 请求,服务把它交给 Apple 或 Google,手机在几秒内显示出来,无论有没有应用处于打开状态。
核心思路就是这样。区别在于:通知面向谁,以及你想自己掌控多少投递环节。
同名的两类产品
搜索“push notification API”,你会看到两类几乎没有交集的产品。
面向你的用户推送的平台。 例如 Firebase Cloud Messaging、Apple Push Notification service、OneSignal 等。你需要开发一个移动应用,发布到 App Store 和 Google Play,从每次安装中收集设备令牌,然后向成千上万的人发送产品或营销通知。这个 API 只是一个漫长项目的最后一步。
向你自己推送的服务。 例如 Pocket Alert、Pushover、ntfy 等。应用已经存在:你在自己的手机上安装它,获取 API 密钥,然后从脚本、服务器和其他服务中发送提醒。无需发布应用,也无需收集令牌。部署完成、备份失败、收到付款,都可以即时通知你。
本指南讨论的是第二类。如果你在开发消费级应用,需要触达它的用户,那你需要的是第一类,下面的大部分内容都不适用于你。
发送一条通知时会发生什么
四个环节,大部分都是看不见的:
- 你的代码向服务发送一个 HTTPS 请求,包含标题、消息和你的 API 密钥。
- 服务验证密钥、保存消息,并决定它该发往哪里:发给你的哪些设备,以什么优先级发送。
- 服务把通知交给平台自己的推送网络:iPhone 使用 APNs,Android 使用 Firebase Cloud Messaging。
- Apple 或 Google 通过每部手机本来就保持的连接把通知送达,手机随即显示。
后两个环节解释了为什么应用关闭时推送依然有效,而且不会耗尽电池:手机从不主动轮询任何服务。完整路径请参阅推送通知的工作原理:APNs 与 FCM。
为什么不直接对接 Apple 和 Google?
你当然可以,前提是你在两大应用商店都有自己的应用。要在中间不借助任何服务、直接推送到自己的手机,你需要:
- 一个 Apple Developer Program 会员资格,以及带有推送权限的 iOS 应用;另一半则需要一个 Firebase 项目和一个 Android 应用。
- 一个 APNs 签名密钥和一个 Firebase 服务账号,以及为每种请求签名的代码。
- 一套从应用中收集设备令牌、并在令牌变化时保持更新的机制。
- 两种请求格式、两套优先级模型和两组错误码。
如果应用本身就是你的产品,这是一个合理的项目。但如果只是为了“cron 任务失败时通知我”,这套机制就太重了。推送通知服务已经替所有人做过一次这些工作。
请求长什么样
使用 Pocket Alert 发送通知,只需一个带认证的 POST 请求:
curl -X POST https://api.pocketalert.app/v1/messages \
-H 'Token: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"title": "Deploy finished", "message": "api v2.4.1 is live"}'
响应为 201 Created,附带已保存的消息以及它发出时所用的优先级。任何带 HTTP 客户端的语言都可以发送同样的请求,更多终端示例请参阅使用 curl 发送推送通知。
只有 title 和 message 是必填项。对提醒最有用的可选字段包括:
level设置通知的提醒强度:silent、low、default、high或critical。actions为通知添加最多三个操作按钮:打开一个 URL、触发一个 HTTP 请求,或复制一个值。send_at或delay可以延迟发送,而不是立即发送(付费套餐)。application_id和device_id用于指定它属于哪个项目,以及发给哪部手机。
不只是 API 的三种接入方式
当你不必为每个来源编写代码时,推送通知 API 才最有用。
- HTTP API,适用于你自己的脚本、任务和应用。
- Webhook URL,适用于已经能发送 Webhook 的服务。GitHub、Stripe、Grafana 或 Sentry 可以直接把它们自己的 JSON 发送到 Pocket Alert 的 Webhook,而
%repository.name%这类占位符会把字段提取到通知中,中间无需任何代码。创建你的第一个 Webhook URL 有详细步骤。 - CLI 和 MCP 服务器,适用于终端和 AI 智能体:在 shell 中执行
pocketalert send "Build done" "All tests passed"(CLI),或者让 Claude 或 Cursor 在长任务结束时调用create_message工具(MCP)。
哪些场景会用到它
大多数提醒可以归为以下几类:
- 出问题了。 服务器停止响应、cron 任务以非零状态退出、备份没有运行。参见 cron 任务告警和服务器监控。
- 任务完成了。 部署、长时间构建、12 小时的 3D 打印、AI 智能体的任务。参见部署告警。
- 发生了你关心的事。 一笔付款、一次注册、一份表单提交。参见付款告警和注册告警。
- 即将发生某事。 一张 14 天后过期的证书。参见 SSL 证书过期告警。
它们的共同点是:有一件事需要有人立刻知道,而不是等到下一次打开控制台或收件箱时才发现。
选择前需要检查什么
这个领域的每项服务都是通过 HTTP 请求发送推送的,真正的差别在于周边的一切:
- 平台。 有些只支持 iPhone(Bark、The Notification App),Gotify 唯一的官方应用只支持 Android。如果需要接收提醒的人使用另一种手机,这一点就决定了选择。
- 优先级。 备份失败的提醒能否与新用户注册的提示音不同?紧急提醒能否穿透勿扰模式?
- 入站 Webhook。 服务能否直接发送它自己的 JSON,还是每个来源都需要脚本来重新整理数据?
- 历史与日志。 当提醒没有送达时,是否有调用记录以及它的处理结果?
- 限额与定价。 按天、按月还是终身计算,达到上限后会怎样?
- 运营方式。 是托管服务,还是你自己维护的服务器。
我们在替代方案页面中,就这些要点将 Pocket Alert 与 Pushover、ntfy、Pushbullet、Bark、Gotify 等服务进行了比较,并说明了每个服务在哪些方面更合适。
常见问题
推送通知 API 和 Firebase Cloud Messaging 是一回事吗?
FCM 是一种推送通知 API:由 Google 提供,供你开发并发布的应用使用。Pocket Alert 这类服务构建在 FCM 和 APNs 之上,替你处理应用、密钥和设备令牌,你只需要发送 HTTP 请求。
我需要开发移动应用吗?
如果只是向你自己或团队发送提醒,则不需要。你只需安装现成的应用,例如适用于 iPhone 或 Android 的 Pocket Alert,然后向它发送即可。只有当你需要向自己的用户推送时,才需要开发自己的应用。
是免费的吗?
许多服务都提供免费套餐。Pocket Alert 的免费套餐每天可发送 50 条消息,无需绑定信用卡,足以满足大多数个人提醒需求;付费套餐每月 6 美元起,每天可发送 1,000 条。详情请见定价页面。
投递有多快?
通常从发出请求到显示在锁屏上只需几秒钟。不过 Apple 和 Google 并不保证时效:如果手机没有信号,或处于严格的省电模式,通知会在重新连接后才送达。
推送、短信还是邮件?
需要立即关注的事情用推送,摘要和记录用邮件,而对方完全没有智能手机应用时则用短信。相关权衡请参阅推送通知与短信对比以及推送通知与邮件告警对比。
免费注册账号,复制你的 API 密钥,然后上面那条 curl 命令就是你的第一条推送。