Automazione delle trasmissioni

PanoPaper può avvisare un sito web, un sistema domotico come Home Assistant, un servizio di chat come Slack o Discord, o un comando rapido quando una trasmissione inizia e quando finisce, con il link per guardarla - per esempio per mostrare un pulsante “Guarda in diretta” sul tuo sito web, o per scrivere nel canale del tuo team.

Configuralo in Quando vai in diretta: il pulsante con l’antenna alla fine delle schede dei servizi in Impostazioni ▸ Trasmissione. Quando qualcosa è impostato, l’antenna appare a colori, e puntando il pulsante vedi cosa è attivo.

Webhook e comando rapido

“Chiama un webhook” - PanoPaper invia un messaggio a un indirizzo web: il tuo server, un sistema domotico come Home Assistant o un servizio che accetta webhook. Fai clic su “Imposta…” per digitare o incollare l’indirizzo e su “Modifica…” per cambiarlo; resta nel tuo portachiavi, perché un indirizzo così contiene spesso un segreto. “Prova” invia subito un messaggio di esempio e mostra la risposta del server. Se il server risponde con una pagina web, probabilmente l’indirizzo è un sito e non un webhook.
“Esegui un comando rapido” (Edizione web) - esegue il comando rapido che scegli sotto, con lo stesso messaggio come input: un piccolo file JSON che il comando rapido può leggere come dizionario.

Quando partono i messaggi

Un messaggio “live” parte non appena il servizio ha accettato il tuo stream, e di nuovo ogni volta che un servizio si aggiunge o si ferma mentre un altro resta attivo; “stopped” parte quando si ferma l’ultimo. Fare clic su Termina streaming in YouTube Studio non ferma lo stream di PanoPaper, quindi non viene inviato nulla finché non fermi la trasmissione in PanoPaper.

Con il tuo account YouTube collegato, un messaggio “live” per YouTube contiene anche i link della trasmissione stessa; PanoPaper aspetta fino a mezzo minuto che YouTube segnali il video prima di inviarlo. Mentre sei in diretta, parte anche un messaggio “viewers” ogni volta che cambia il numero di persone che guardano su YouTube; PanoPaper controlla ogni cinque minuti.

Il messaggio

PanoPaper invia il messaggio come HTTP POST con il tipo di contenuto application/json, in UTF-8, e lo user agent PanoPaper/ seguito dalla sua versione. Qualsiasi risposta 2xx vale come ricevuta, e il corpo della risposta non viene letto. Ogni tentativo aspetta una risposta fino a 15 secondi. Se la rete non funziona, o il server risponde 408, 429 o 5xx, PanoPaper riprova dopo 5 secondi e un’ultima volta 30 secondi dopo; con altre risposte non riprova, e “Prova” tenta una volta sola. I messaggi partono uno dopo l’altro, nell’ordine in cui sono successe le cose, quindi uno “stopped” non arriva mai prima del suo “live”.

Un messaggio “live” per YouTube e Facebook, con il tuo account YouTube collegato:

{
  "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 è in diretta su YouTube e Facebook: https://www.youtube.com/watch?v=AbCdEfGhIjK",
  "content" : "Port Dome è in diretta su YouTube e Facebook: https://www.youtube.com/watch?v=AbCdEfGhIjK"
}

Campo	Tipo	Contenuto
`event`	stringa	`live`, `stopped`, `viewers` o `test`. Usa questo campo, non `text`, per capire cosa è successo.
`services`	array di stringhe	I servizi: `YouTube`, `Facebook` e, per un altro servizio, il nome del suo server, come `live.twitch.tv` (un nome più lungo di 20 caratteri viene inviato come “Server personalizzato”, nella lingua di PanoPaper). In “live” e “viewers”, ogni servizio in onda in quel momento; in “stopped”, quelli che erano in onda; in “test”, quelli pronti ad andare in diretta.
`watch`	stringa (URL)	Il link per guardare: la pagina della diretta del tuo canale, `https://www.youtube.com/@<channel>/live` - oppure, con il tuo account collegato e “Rendi pubblica la trasmissione” disattivato, la pagina della trasmissione stessa, perché una trasmissione non in elenco non compare nella pagina della diretta del tuo canale. Solo quando YouTube è tra i servizi e il tuo Canale è indicato, e in “test” ogni volta che il Canale è indicato.
`videoId`	stringa	L’ID video della trasmissione su YouTube. Solo con il tuo account YouTube collegato, una volta che YouTube ha segnalato il video: in “live”, “viewers” e “test”, mai in “stopped”.
`video`	stringa (URL)	La pagina della trasmissione stessa, `https://www.youtube.com/watch?v=<videoId>`. Inviato insieme a `videoId`.
`embed`	stringa (URL)	La trasmissione da mostrare in una pagina web, `https://www.youtube.com/embed/<videoId>`, come indirizzo di un `<iframe>`. Inviato insieme a `videoId`.
`viewers`	intero	Quante persone guardano su YouTube, secondo il conteggio di YouTube. Solo con il tuo account YouTube collegato e dopo che PanoPaper ha controllato, circa un minuto dopo l’inizio della trasmissione: in “viewers”, e in “live” e “test” finché è noto; mai in “stopped”.
`camera`	stringa	Il nome della videocamera come lo mostra PanoPaper: la videocamera in onda e, in “stopped”, l’ultima che lo era. Con le videocamere a turno, quella in onda quando è stato inviato il messaggio - il passaggio alla videocamera successiva non invia alcun messaggio.
`time`	stringa	Quando è stato creato il messaggio, in ISO 8601 e UTC, al secondo: `2026-10-20T14:03:12Z`.
`text`, `content`	stringa	La stessa frase due volte, nella lingua di PanoPaper - in “live” con il link della trasmissione stessa se è noto, altrimenti con la pagina della diretta del tuo canale: `text` è ciò che Slack mostra come messaggio, `content` ciò che mostra Discord. È pensata per le persone e la sua formulazione può cambiare, quindi non ricavarne dati.

Un campo senza valore viene omesso, mai inviato vuoto o come null. I campi possono arrivare in qualsiasi ordine, e le versioni future di PanoPaper potrebbero aggiungerne altri: ignora quelli che non conosci.

Mantenere segreto l’indirizzo

PanoPaper non firma il messaggio né aggiunge una password propria. Per fare in modo che solo PanoPaper possa inviare messaggi al tuo server, metti un segreto nell’indirizzo stesso, come un lungo percorso casuale o un token nella query string - gli indirizzi webhook di Home Assistant, per esempio, funzionano già così. Per questo l’indirizzo resta nel tuo portachiavi.

In un comando rapido

Un comando rapido riceve lo stesso JSON come file con il nome dell’evento, come “PanoPaper live.json”.

Anche Comandi Rapidi e Siri possono avviare e interrompere una trasmissione.