Broadcast Automation

PanoPaper can tell a website, a home automation such as Home Assistant, a chat service such as Slack or Discord, or a shortcut when a broadcast starts and when it ends, with the link to watch it - to show a “Watch live” button on your own website, for example, or to post in your team's channel.

Set it up in When You Go Live: the button with the antenna at the end of the service tabs in Settings ▸ Broadcast. While something is set up, the antenna is shown in color, and pointing at the button says what is on.

Webhook and shortcut

'Call a webhook' - PanoPaper sends a message to a web address: your own server, a home automation such as Home Assistant, or a service that takes webhooks. Click 'Set…' to type or paste the address and 'Edit…' to change it; it stays in your keychain, as such an address often holds a secret. 'Test' sends a sample message at once and shows the server's answer. If the server answers with a web page, the address is most likely a website rather than a webhook.
'Run a shortcut' (Web Edition) - runs the shortcut you choose under it, with the same message as its input: a small JSON file, which the shortcut can read as a dictionary.

When messages go out

A “live” message goes out once the service has taken your stream, and again whenever a service joins or leaves while another one stays on; “stopped” goes out when the last one stops. Clicking End stream in YouTube Studio doesn't stop PanoPaper's stream, so nothing is sent until you stop the broadcast in PanoPaper.

With your YouTube account connected, a “live” message for YouTube also holds the broadcast's own links; PanoPaper waits up to half a minute for YouTube to report the video before sending it. While you're live, a “viewers” message also goes out whenever the number of people watching on YouTube changes; PanoPaper looks every five minutes.

The message

PanoPaper sends the message as an HTTP POST with the content type application/json, in UTF-8, and the user agent PanoPaper/ followed by its version. Any 2xx answer counts as received, and the body of the answer isn't read. Each try waits up to 15 seconds for an answer. When the network fails, or the server answers 408, 429 or 5xx, PanoPaper tries again after 5 seconds and once more 30 seconds after that; other answers aren't tried again, and 'Test' tries only once. Messages go out one after another, in the order things happened, so a “stopped” never arrives before its “live”.

A “live” message for YouTube and Facebook, with your YouTube account connected:

{
  "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 is live on YouTube and Facebook: https://www.youtube.com/watch?v=AbCdEfGhIjK",
  "content" : "Port Dome is live on YouTube and Facebook: https://www.youtube.com/watch?v=AbCdEfGhIjK"
}

Field	Type	What it holds
`event`	string	`live`, `stopped`, `viewers` or `test`. Use it, not `text`, to tell what happened.
`services`	array of strings	The services: `YouTube`, `Facebook`, and for another service its server's name, such as `live.twitch.tv` (a name longer than 20 characters is sent as “Custom Server”, in PanoPaper's language). In “live” and “viewers”, every service on air at that moment; in “stopped”, the ones that were on air; in “test”, the ones ready to go live.
`watch`	string (URL)	The link to watch: your channel's live page, `https://www.youtube.com/@<channel>/live` - or, with your account connected and 'Make broadcast public' off, the broadcast's own page, since an unlisted broadcast isn't on your live page. Only while YouTube is among the services and your Channel is given, and in “test” whenever your Channel is given.
`videoId`	string	The YouTube broadcast's video ID. Only with your YouTube account connected, once YouTube has reported the video: in “live”, “viewers” and “test”, never in “stopped”.
`video`	string (URL)	The broadcast's own page, `https://www.youtube.com/watch?v=<videoId>`. Sent with `videoId`.
`embed`	string (URL)	The broadcast for showing in a web page, `https://www.youtube.com/embed/<videoId>`, as the address of an `<iframe>`. Sent with `videoId`.
`viewers`	integer	How many are watching on YouTube, as YouTube counts them. Only with your YouTube account connected and once PanoPaper has looked, about a minute after the broadcast starts: in “viewers”, and in “live” and “test” while it's known; never in “stopped”.
`camera`	string	The camera's name as PanoPaper shows it: the camera on air, in “stopped” the last one that was. With cameras taking turns, the one on air when the message was sent - switching to the next camera sends no message.
`time`	string	When the message was made, in ISO 8601 and UTC, to the second: `2026-10-20T14:03:12Z`.
`text`, `content`	string	The same sentence twice, in PanoPaper's language - in “live” with the broadcast's own link if it's known, else your channel's live page: `text` is what Slack shows as the message, `content` what Discord shows. It's meant for people and its wording may change, so don't read anything out of it.

A field without a value is left out, never sent empty or as null. The fields can come in any order, and later versions of PanoPaper may add fields: skip the ones you don't know.

Keeping the address secret

PanoPaper doesn't sign the message or add a password of its own. To make sure only PanoPaper can post to your server, put a secret into the address itself, such as a long random path or a token in the query string - Home Assistant's webhook addresses, for one, already work that way. That's why the address stays in your keychain.

In a shortcut

A shortcut gets the same JSON as a file named after the event, such as “PanoPaper live.json”.

Shortcuts and Siri can also go live and stop a broadcast.