Vai al contenuto principale

Plugin di chat

Se desideri creare un plugin che parli in chat, reagisca agli spettatori o moderare i messaggi, questa è la pagina da cui iniziare. Esempi di codice sono mostrati in entrambe le lingue supportate. Configura il tuo toolchain sulla pagina JavaScript o Python SDK prima.

Owncast espone la funzionalità chat in tre livelli:

  1. Gestori di eventi della chat affinché il tuo plugin possa reagire quando le persone parlano, si uniscono, escono o si rinominano.
  2. API di chat e utenti affinché il tuo plugin possa inviare messaggi, ispezionare lo stato della chat e moderare gli utenti.
  3. Filtri di chat affinché il tuo plugin possa riscrivere o eliminare i messaggi prima che gli spettatori li vedano.

Cosa puoi costruire​

  • Bot di chat che rispondono a comandi o parole chiave.
  • Bot di benvenuto che salutano le persone quando si uniscono.
  • Bot promemoria che inviano messaggi quando il stream inizia.
  • Bot di countdown e timer alimentati da owncast.timer o il gestore del tick.
  • Assistenti alla moderazione che nascondono messaggi, disconnettono client o disabilitano utenti abusivi.
  • Filtri che riscrivono, traducono o eliminano messaggi prima che vengano trasmessi.

Un bot di risposta è solo un gestore:

const { definePlugin, owncast } = require("@owncast/plugin-sdk");

module.exports = definePlugin({
  onChatMessage(msg) {
    const name = msg.user?.displayName ?? "someone";
    owncast.chat.send(`${name} said: ${msg.body}`);
  },
});

Reagire alla chat​

Definisci onChatMessage (@plugin.on_chat_message in Python) per vedere ogni messaggio dopo l'esecuzione dei filtri, subito prima che venga trasmesso agli spettatori:

module.exports = definePlugin({
  onChatMessage(msg) {
    owncast.chat.send(`echo: ${msg.body}`);
  },
});

I campi a cui accedi di più sono msg.body (il testo originale), msg.user (l'identità del mittente, con user.id per lo stato per utente e user.scopes per i controlli di moderatore), e msg.timestamp (deterministico, quindi preferiscilo rispetto all'orologio quando confronti il tempo trascorso o affermi nei test). Non impostare stato o permessi sui nomi display.

Per il payload completo del messaggio e ogni altro evento a cui un plugin chat può iscriversi (unione e uscita utente, rinominare, moderazione e altro), vedere il Riferimento eventi.

Invio di messaggi in chat​

owncast.chat.send​

Invia un messaggio in chat. Inviato come identità del bot del tuo plugin. Prende testo normale, non markup: l'interfaccia utente della chat HTML-escape lo visualizza, così caratteri come \<, &, e " vengono visualizzati come testo piuttosto che come HTML.

owncast.chat.send("hello chat");
owncast.chat.sendAction("waves");        // /me-style action message
owncast.chat.system("Stream starting in 5 minutes");

Richiede chat.send.

owncast.chat.sendAction​

Invia un messaggio in stile azione (/me): sendAction in JavaScript, send_action in Python. Simile a send, prende testo normale e viene HTML-escapato dall'interfaccia utente della chat durante la visualizzazione.

Richiede chat.send.

owncast.chat.system​

Invia un messaggio di annuncio del server. Nessuna identità del bot è allegata. Il corpo viene visualizzato in linea come HTML. Usa questo per avvisi brevi attribuiti al server come "Stream inizio tra 5 minuti". Tratta il corpo come output HTML non fidato: non interpolare input controllati dagli spettatori senza eseguire l'escape.

Richiede chat.send.

Identità chat​

Ogni plugin ha esattamente un'identità chat: il bot che Owncast fornisce quando il tuo plugin è installato. Il suo nome visualizzato è bot.displayName del tuo manifesto se impostato, altrimenti name.

Sia send che sendAction postano come questa identità attraverso il normale pipeline chat di Owncast, inclusi filtri, limiti di frequenza e moderazione. I plugin non possono postare sotto nomi arbitrari o impersonare utenti reali.

L'utente bot è determinato dallo slug del plugin, quindi l'identità sopravvive a modifiche del manifesto a name o bot.displayName. Se hai bisogno di più personalità chat, pubblica più plugin.

Lettura dello stato della chat​

owncast.chat.history​

Restituisci i messaggi chat più recenti (un limite opzionale predefinito di 50). Ogni voce ha la forma { id, user?, clientId?, body, timestamp }.

Richiede chat.history.

owncast.chat.clients​

Return the list of currently connected chat clients: { id, userId?, displayName?, connectedAt?, userAgent?, ipAddress?, messageCount? }. L'id è l'ID client per connessione utilizzato da owncast.chat.kick.

Richiede chat.history.

owncast.server.emotes​

Leggi le emote chat personalizzate del server ({ name, url }) quando il tuo bot desidera fare riferimento o rispecchiare il catalogo delle emote.

Richiede server.read.

owncast.users.list e owncast.users.get​

Leggi l'elenco degli utenti chat o un singolo record utente per id.

Richiede users.read.

API di moderazione​

Queste sono deleteMessage / kick / sendTo / replyTo in JavaScript e delete_message / kick / send_to / reply_to in Python.

owncast.chat.deleteMessage​

Nascondi un messaggio della chat dagli spettatori, per ID messaggio.

Richiede chat.moderate.

owncast.chat.kick​

Disconnetti un client chat, per ID client.

Richiede chat.moderate.

owncast.chat.sendTo​

Invia un messaggio privato a un singolo client connesso, per ID client.

Richiede chat.send.

owncast.chat.replyTo​

Sussurra una risposta a chiunque abbia inviato un messaggio in chat. Puoi passare sia l'oggetto messaggio completo dal gestore del messaggio della chat / filtro, sia un ID client nudo se è tutto ciò che hai. Restituisce un valore falso quando la connessione del mittente non è più nota, il che ti offre una pulita alternativa a un messaggio pubblico.

module.exports = definePlugin({
  onChatMessage(msg) {
    if (!owncast.chat.replyTo(msg, "psst: got your message")) {
      owncast.chat.send("got your message"); // sender already disconnected
    }
  },
});

Richiede chat.send.

Comandi​

Per i comandi in chat, dichiara una tabella dei comandi con alias, cooldown, gating per moderatori e elenchi automatici di !help. Vedi Comandi di chat.

Moderazione utenti​

owncast.users.setEnabled​

Abilita o disabilita un utente chat, per id, con una ragione opzionale: setEnabled in JavaScript, set_enabled in Python.

Richiede users.moderate.

owncast.users.banIP​

Banna un'IP dall'unirsi alla chat: banIP in JavaScript, ban_ip in Python.

Richiede users.moderate.

Filtri chat​

I filtri vedono i messaggi chat prima che vengano trasmessi, con la possibilità di riscriverli o eliminarli. I filtri vengono eseguiti partendo dalla priorità più bassa. Un drop termina la catena e il messaggio non raggiunge filtri o notifiche successive. Un modify passa il nuovo payload al filtro successivo.

filterChatMessage​

Riceve la stessa forma ChatMessage del gestore del messaggio della chat e restituisce uno dei tre risultati, costruiti con l'aiuto di filter:

  • pass: lascia passare il messaggio così com'è.
  • modify: sostituiscilo con un nuovo payload.
  • drop: elimina (con una ragione). La catena si ferma qui.
const { definePlugin, filter } = require("@owncast/plugin-sdk");

module.exports = definePlugin({
  filterChatMessage(msg) {
    if (msg.body.includes("spam")) return filter.drop("spam keyword");
    if (msg.body.includes("damn")) {
      return filter.modify({ ...msg, body: msg.body.replace("damn", "****") });
    }
    return filter.pass();
  },
});

Richiede il permesso chat.filter. L'host rifiuta il caricamento se un plugin definisce il gestore del filtro senza dichiarare quel permesso.

Priorità del filtro (opzionale)​

Numeri più bassi vengono eseguiti prima. Valore predefinito 100. Set it with filterPriority (JavaScript) on the plugin definition, or by calling plugin.set_filter_priority(priority) (Python).

Usa questo quando il comportamento del tuo plugin dipende dal fatto che altri filtri siano già stati eseguiti. Ad esempio, un filtro per le parolacce dovrebbe solitamente essere eseguito prima di un traduttore.

Sicurezza del filtro​

  • Gli errori sono trattati come un pass. Un filtro che lancia eccezioni non blocca mai la chat.
  • I filtri hanno un limite di tempo di 50 ms. Un filtro lento viene annullato e trattato come pass.
  • Dopo 5 fallimenti consecutivi (errori o timeout) il plugin viene disabilitato automatico per il resto della sessione. Una chiamata di filtro di successo ripristina il contatore.

Limiti imposti dall'host che sono importanti per i plugin chat​

Alcuni limiti dell'host sono degni di progettazione:

  • runtime del filtro: 50 ms per messaggio
  • runtime dell'handler eventi (messaggio chat, utente unito, ecc.): 500 ms per chiamata
  • limite rigido per chiamata: 10 s
  • dimensione output del filtro: 1 MiB
  • timers in attesa: 64 alla volta
  • intervallo di ritardo del timer: 100 ms a 24 h

Ciò significa che i bot di chat e i filtri dovrebbero rimanere leggeri, evitare ritardi di rete lenti nel percorso caldo e mantenere i payload riscritti piccoli.

Permessi di cui avrai comunemente bisogno​

  • chat.send: invia messaggi di chat e risposte private.
  • chat.history: leggi messaggi chat recenti e client connessi.
  • chat.moderate: nascondi i messaggi e disconnetti i client.
  • chat.filter: riscrivi o elimina i messaggi prima della trasmissione.
  • users.read: ispeziona i record degli utenti.
  • users.moderate: disabilita gli utenti di chat o banna IP.

Vedi Permessi per il modello di sicurezza completo.

Esempi di plugin di chat​

Il SDK dei plugin include piccoli esempi focalizzati sulla chat che mappano da vicino i modelli su questa pagina (ognuno ha sia una versione in JavaScript che in Python):

  • echo-bot: il bot di risposta più piccolo possibile che utilizza il gestore di chat-message + owncast.chat.send.
  • chat-logger: registra ogni messaggio di chat senza rispondere.
  • stream-tracker: unisce comandi di chat, gestori del ciclo di vita dell'utente e annunci di azione.
  • profanity-filter: riscrive i messaggi senza eliminarli.
  • slow-mode: elimina i messaggi utilizzando msg.timestamp per limitare la velocità.
  • engagement-bot: modera eliminando un messaggio.
  • timer-bot: bot di promemoria/countdown attivati dalla chat, utilizzando timer e il gestore tick.

Sfoglia questi esempi su examples/js · examples/python.

Dove si inserisce con gli altri documenti del plugin​

  • Scegliere un SDK e le pagine di JavaScript / Python coprono la configurazione specifica per lingua, la CLI e la sintassi.
  • Comandi chat copre le tabelle dei comandi, il !help automatico e la combinazione di comandi con i tuoi gestori di chat.
  • Gestori di eventi è il riferimento completo dei gestori per tutti gli eventi del plugin.
  • API di Owncast è il riferimento completo delle API per tutti i metodi owncast.*.
  • Riferimento al manifesto copre le autorizzazioni, i campi di identità del bot e ogni proprietà del manifesto.
  • Contribuire all'interfaccia utente copre l'interfaccia utente lato visualizzatore, sovrapposizioni, pulsanti, script e stili se il tuo plugin di chat include anche pezzi frontend.

Se stai partendo da zero, leggi prima Quickstart e poi torna qui.

Improve this page

See something missing or incorrect? Edit this page and improve the documentation for everyone.

Contributors to this documentation
Gabe KangasGabe Kangas