PINGOBELL / DOCUMENTATION

连接你的 Agent。

获取配对码，把提示词交给 Agent。
在手表上确认，等第一条提醒到来。

由 PingoBell 统一提供连接服务

你只需要 PingoBell 手表 App 和具备 HTTP 请求能力的 Agent，无需部署后端或填写服务地址。官网已上线；手表推送服务和 App Store 下载尚未开放，目前不能配对或发送通知。

手表 App 内置官方服务地址。下面的提示词会自动带上相同的接口地址，Agent 按文档申请连接即可。

推送服务尚未开放

推送服务开放后，即可在此生成连接提示词；目前仅展示接入流程，配对与发送暂不可用。

01 / 获取连接提示词

打开手表 App。服务由 PingoBell 提供，无需填写地址。
点击“连接我的 Agent”，按系统提示允许通知。
把手表显示的六位配对码填在下面。代码有效 5 分钟，只能使用一次。

提示词生成需要 JavaScript

服务开放后，你可以按照下方 HTTP API 参考手动接入；当前配对和发送接口尚未开放。

02 / 在手表上确认

Agent 提交配对申请后，手表会显示它的名称。核对名称，点击“确认连接”。申请同样在 5 分钟后过期。

此时 Agent 才有发送权限。等待期间，Agent 可以每 5 秒查询一次 GET /v1/agent/status，看到 connected 再继续。过期后请在手表上重新获取配对码。

授权操作留在手表上

Agent 不应替你调用设备确认接口，也不需要设备凭证。当前原型一台手表连接一个 Agent；更换 Agent 时，请先在手表设置里解除连接。

03 / 发送第一条提醒

生成的提示词已包含测试步骤。你也可以在连接确认后，对 Agent 说：

测试提示词

请用已连接的 PingoBell 发送一条测试提醒。
标题：连接成功，来打个招呼
正文：以后有需要你关注的事，我会在这里提醒你。

使用已安全保存的 Agent 凭证，不要在聊天中展示凭证。
根据接口响应说明真实状态，不要把排队提交说成已送达。

之后，在任务开始时约定需要提醒的时机，例如：

任务提示词

请继续执行这个任务。任务完成、执行失败，或者需要我提供信息时，
通过 PingoBell 提醒我。标题写清发生了什么，正文简要说明结果或需要我做什么。
不要为每一个中间步骤发送通知。

正式服务通过苹果推送发送提醒。请确保手表联网，并已允许 PingoBell 通知。开发预览的本地模式仅在 App 前台刷新。

HTTP API 参考

以下为模板，SERVICE_URL 是提示词自动带入的 PingoBell 官方 API 地址，无需用户配置。AGENT_TOKEN 由 Agent 从配对响应中安全保存。示例不包含真实凭证。

1. 提交配对码

POST /v1/pairings/claim

HTTP · 无需认证

POST {SERVICE_URL}/v1/pairings/claim
Content-Type: application/json

{"code":"123456","agent_name":"My Agent"}

201 · 响应字段（凭证已隐藏）

{
  "agent_token": "<安全保存，不要公开>",
  "status": "pending_watch_confirmation",
  "agent_name": "My Agent"
}

名称最多 40 个 Unicode 字符，不能为空。配对码提交后即失效；不要反复申请。返回的凭证在手表确认前不能发送消息。

2. 等待手表确认

GET /v1/agent/status

HTTP · Bearer 凭证

GET {SERVICE_URL}/v1/agent/status
Authorization: Bearer {AGENT_TOKEN}

响应中的 status 为 pending_watch_confirmation、connected 或 expired。连接状态不代表实时在线。

3. 发送标题与正文

POST /v1/notifications

HTTP · 每条新消息使用唯一幂等键

POST {SERVICE_URL}/v1/notifications
Authorization: Bearer {AGENT_TOKEN}
Content-Type: application/json
Idempotency-Key: {UNIQUE_MESSAGE_ID}

{
  "title": "报告已经准备好了",
  "body": "分析已完成，方便时请查看结果。"
}

202 · APNs 模式的排队响应示例

{
  "notification_id": "<message-id>",
  "status": "queued",
  "mode": "normal",
  "transport": "apns"
}

消息只支持 title 和 body，均不能为空。标题最多 80 个 Unicode 字符，正文最多 1000 个；最终推送载荷不超过 4 KiB。
幂等键为 1–128 位英文字母、数字、下划线或连字符。重试同一消息时保留相同键和内容；新消息换一个键。
每连接每分钟最多 5 条、每天最多 100 条。待推送消息默认 15 分钟有效。
通知模式由用户在手表上选择，Agent 不能通过消息参数打开关键警报。

理解返回状态

状态	真实含义
`available_in_app`	本地模式，消息可在前台 App 读取；没有远程推送。
`queued` / `sending`	等待或正在提交给苹果推送服务。
`submitted_to_apns`	苹果已接受推送请求，不代表手表已收到、响铃或用户已读。
`failed` / `expired`	提交失败或排队超过有效期，不能宣称已送达。

重复请求可能返回消息的最新状态。当前 Agent API 不提供消息状态查询或送达回执订阅；手表 App 会显示其已知状态。用户打开消息不等于同意 Agent 执行其他操作。

问题与排查

错误	处理方式
`PAIRING_NOT_FOUND` 404	配对码无效、已使用或过期。在手表上换一个新代码，并确认服务地址一致。
`PAIRING_NOT_APPROVED` 403	在手表上确认连接，再发送；不要让 Agent 代为确认。
`UNAUTHORIZED` 401	检查凭证。若已在手表解除连接，旧凭证已撤销，请重新配对。
`PUSH_NOT_READY` 409	确认 APNs 配置、签名、手表推送注册和普通通知授权。
`CRITICAL_ALERTS_UNAVAILABLE` 409	关键警报前置条件不足。提示用户检查权限，不要静默降级后声称强提醒成功。
`IDEMPOTENCY_CONFLICT` 409	相同幂等键对应了不同内容；新消息使用新键。
`RATE_LIMITED` 429	遵守响应的 Retry-After，停止密集重试。日额度用尽时等待额度恢复。

接口成功，但手表没有消息？

先看响应的 transport 和 status。请检查手表网络和系统通知设置。若仍无法收到，请联系 PingoBell 支持；开发者还可检查推送注册和服务端记录。HTTP 202 不是送达证明。

通知与权限

普通通知遵循手表当前的系统设置。Critical Alerts 通过 UserNotifications 与 APNs 实现，需要苹果批准特殊权限、包含该权限的有效签名，以及用户单独授权。当前原型不承诺关键警报可用，也不使用 AlarmKit 实现它。

在手表设置中解除连接会撤销 Agent 凭证，并清除该连接的消息记录。请把凭证保存在 Agent 可安全访问的位置，不要放进公开提示词、URL、日志或 Git 仓库。

第一条提醒之后，继续专注你的事。
返回 PingoBell 首页 ↗