直播自动化

直播开始和结束时，PanoPaper 可以通知网站、Home Assistant 等智能家居自动化、Slack 或 Discord 等聊天服务，或快捷指令，并附上观看链接，例如在你自己的网站上显示“观看直播”按钮，或在你团队的频道中发帖。

在开始直播时中进行设置：它是“设置”▸“直播”中服务标签页末尾带天线的按钮。设置了任何项目时，天线会以彩色显示，将指针移到按钮上即可看到开启了哪些项目。

Webhook 和快捷指令

“调用 Webhook” - PanoPaper 会发送消息到一个网址：你自己的服务器、Home Assistant 等智能家居自动化，或接受 Webhook 的服务。点按“设置…”来输入或粘贴地址，点按“编辑…”来更改；地址会保存在你的钥匙串中，因为这类地址通常含有密钥。“测试”会立即发送一条示例消息，并显示服务器的响应。如果服务器以网页响应，该地址很可能是网站而不是 Webhook。
“运行快捷指令”（网页版） - 以同一条消息作为输入，运行你在下方选择的快捷指令：一个小型 JSON 文件，快捷指令可将其读取为词典。

消息何时发送

服务接受你的视频流后，就会发送“live”消息；之后每当有服务加入，或在其他服务仍在直播时有服务离开，都会再发送一次；最后一个服务停止时会发送“stopped”。在 YouTube Studio 中点按结束直播并不会停止 PanoPaper 的视频流，因此在你于 PanoPaper 中停止直播之前，不会发送任何消息。

连接 YouTube 账户后，YouTube 的“live”消息还会包含直播本身的链接；PanoPaper 最多会等待半分钟，让 YouTube 报告视频，然后再发送消息。直播期间，每当在 YouTube 上观看的人数变化时，也会发送“viewers”消息；PanoPaper 每五分钟查看一次。

消息内容

PanoPaper 以 HTTP POST 发送消息，内容类型为 application/json，使用 UTF-8 编码，用户代理为 PanoPaper/ 加上其版本号。任何 2xx 响应都视为已收到，不会读取响应的正文。每次尝试最多等待 15 秒的响应。网络连接出错，或服务器以 408、429 或 5xx 响应时，PanoPaper 会在 5 秒后重试，30 秒后再重试最后一次；其他响应不会重试，“测试”只尝试一次。消息会按事情发生的顺序逐一发送，因此“stopped”绝不会比它的“live”先到达。

连接 YouTube 账户后，YouTube 和 Facebook 的“live”消息示例：

{
  "event" : "live",
  "services" : [
    "YouTube",
    "Facebook"
  ],
  "watch" : "https://www.youtube.com/@yourchannel/live",
  "videoId" : "AbCdEfGhIjK",
  "video" : "https://www.youtube.com/watch?v=AbCdEfGhIjK",
  "embed" : "https://www.youtube.com/embed/AbCdEfGhIjK",
  "camera" : "Port Dome",
  "time" : "2026-10-20T14:03:12Z",
  "text" : "Port Dome 正在 YouTube和Facebook 上直播：https://www.youtube.com/watch?v=AbCdEfGhIjK",
  "content" : "Port Dome 正在 YouTube和Facebook 上直播：https://www.youtube.com/watch?v=AbCdEfGhIjK"
}

字段	类型	内容
`event`	字符串	`live`、`stopped`、`viewers` 或 `test`。要判断发生了什么，请使用此字段，而不是 `text`。
`services`	字符串数组	服务：`YouTube`、`Facebook`，其他服务则是其服务器的名称，例如 `live.twitch.tv`（超过 20 个字符的名称会以 PanoPaper 的语言发送为“自定服务器”）。在“live”和“viewers”中，是当时所有正在直播的服务；在“stopped”中，是之前正在直播的服务；在“test”中，是已准备好开始直播的服务。
`watch`	字符串（URL）	观看用的链接：你频道的直播页面，`https://www.youtube.com/@<channel>/live`；若已连接账户且关闭“将直播设为公开”，则为这次直播自己的页面，因为不公开列出的直播不会出现在你的直播页面上。仅在 YouTube 属于这些服务且已填写你的频道时包含；在“test”中，只要已填写频道就会包含。
`videoId`	字符串	YouTube 直播的视频 ID。仅在连接 YouTube 账户、且 YouTube 已报告视频后包含：出现在“live”、“viewers”和“test”中，绝不会出现在“stopped”中。
`video`	字符串（URL）	直播本身的页面，`https://www.youtube.com/watch?v=<videoId>`。与 `videoId` 一起发送。
`embed`	字符串（URL）	用于在网页中显示的直播，`https://www.youtube.com/embed/<videoId>`，作为 `<iframe>` 的地址。与 `videoId` 一起发送。
`viewers`	整数	在 YouTube 上观看的人数，按 YouTube 的统计方式。仅在连接 YouTube 账户、且 PanoPaper 已查看过（直播开始约一分钟后）时包含：出现在“viewers”中，以及已知人数时的“live”和“test”中；绝不会出现在“stopped”中。
`camera`	字符串	PanoPaper 所显示的摄像头名称：正在直播的摄像头；在“stopped”中则是最后直播的那个。摄像头轮流直播时，是发送消息当时正在直播的那个 - 切换到下一个摄像头不会发送消息。
`time`	字符串	消息生成的时间，采用 ISO 8601 和 UTC，精确到秒：`2026-10-20T14:03:12Z`。
`text`, `content`	字符串	同一句话出现两次，使用 PanoPaper 的语言 - 在“live”中，如果已知直播本身的链接就附上它，否则附上你频道的直播页面：`text` 是 Slack 显示为消息的内容，`content` 是 Discord 显示的内容。这句话是给人看的，措辞也可能改变，因此请勿从中解读任何信息。

没有值的字段会被省略，绝不会以空值或 null 发送。字段可能以任何顺序出现，PanoPaper 以后的版本也可能添加字段：请跳过你不认识的字段。

对地址保密

PanoPaper 不会对消息签名，也不会另外添加自己的密码。若要确保只有 PanoPaper 能向你的服务器发送消息，请将密钥放在地址本身中，例如一段很长的随机路径，或查询字符串中的令牌 - 比如 Home Assistant 的 Webhook 地址本来就是这样工作的。这也是地址会保存在你的钥匙串中的原因。

在快捷指令中

快捷指令会以文件的形式收到相同的 JSON，文件以事件命名，例如“PanoPaper live.json”。

快捷指令与 Siri 也可以开始和停止直播。