Ir para o conteúdo principal

Plugins de chat

Se você deseja criar um plugin que converse no chat, reaja aos espectadores ou modere mensagens, esta é a página para começar. Os exemplos de código são mostrados em ambas as linguagens suportadas. Configure seu ambiente de ferramentas na página do SDK de JavaScript ou Python primeiro.

O Owncast expõe a funcionalidade de chat em três camadas:

  1. Manipuladores de eventos de chat para que seu plugin possa reagir quando as pessoas falam, entram, saem ou mudam de nome.
  2. APIs de chat e usuário para que seu plugin possa enviar mensagens, inspecionar o estado do chat e moderar usuários.
  3. Filtros de chat para que seu plugin possa reescrever ou descartar mensagens antes que os espectadores as vejam.

O que você pode construir​

  • Bots de chat que respondem a comandos ou palavras-chave.
  • Bots de boas-vindas que cumprimentam as pessoas quando elas entram.
  • Bots de lembrete que enviam mensagens quando a transmissão começa.
  • Bots de contagem e temporizadores alimentados por owncast.timer ou o manipulador de tique.
  • Ajuda de moderação que oculta mensagens, desconecta clientes ou desabilita usuários abusivos.
  • Filtros que reescrevem, traduzem ou descartam mensagens antes de serem transmitidas.

Um bot de resposta é apenas um manipulador:

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}`);
  },
});

Reagindo ao chat​

Defina onChatMessage (@plugin.on_chat_message em Python) para ver cada mensagem após os filtros serem executados, pouco antes de ser transmitida aos espectadores:

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

Os campos que você mais usa são msg.body (o texto bruto), msg.user (a identidade do remetente, com user.id para estado por usuário e user.scopes para checagens de moderador), e msg.timestamp (determinístico, então prefira-o ao relógio ao comparar o tempo decorrido ou fazer afirmações em testes). Não baseie estado ou permissões em nomes de exibição.

Para a carga completa da mensagem e cada outro evento para o qual um plugin de chat pode se inscrever (entrada e saída de usuários, renomeação, moderação e mais), consulte a Referência de Eventos.

Enviando mensagens de chat​

owncast.chat.send​

Envie uma mensagem de chat. Enviado como a identidade do bot do seu plugin. Aceita texto simples, não markup: a interface do usuário de chat faz escape de HTML ao exibi-lo, portanto caracteres como \<, &, e " são renderizados como texto em vez de HTML.

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

Requer chat.send.

owncast.chat.sendAction​

Envie uma mensagem do tipo ação (/me): sendAction em JavaScript, send_action em Python. Como send, aceita texto simples e é HTML-escapado pela interface de chat ao exibir.

Requer chat.send.

owncast.chat.system​

Envie uma mensagem de anúncio do servidor. Nenhuma identidade de bot está anexada. O corpo é renderizado inline como HTML. Use isso para avisos curtos atribuídos ao servidor, como "Transmissão começando em 5 minutos". Trate o corpo como saída HTML não confiável: não interpolar entrada controlada pelo espectador sem escapá-la.

Requer chat.send.

Identidade do chat​

Cada plugin tem exatamente uma identidade de chat: o bot que o Owncast provisiona quando seu plugin está instalado. Seu nome de exibição é o bot.displayName do seu manifesto se estiver configurado, caso contrário name.

Tanto send quanto sendAction postam como esta identidade através do fluxo normal de chat do Owncast, incluindo filtros, limites de taxa e moderação. Plugins não podem postar sob nomes arbitrários ou se passar por usuários reais.

O usuário bot é indexado pelo slug do plugin, portanto a identidade sobrevive a edições do manifesto para name ou bot.displayName. Se você precisar de várias personas de chat, envie vários plugins.

Lendo o estado do chat​

owncast.chat.history​

Retorna as mensagens de chat mais recentes (um limite opcional tem valor padrão de 50). Cada entrada tem a forma { id, user?, clientId?, body, timestamp }.

Requer chat.history.

owncast.chat.clients​

Return the list of currently connected chat clients: { id, userId?, displayName?, connectedAt?, userAgent?, ipAddress?, messageCount? }. O id é o ID de cliente por conexão usado por owncast.chat.kick.

Requer chat.history.

owncast.server.emotes​

Leia os emotes de chat personalizados do servidor ({ name, url }) quando seu bot quiser referenciar ou espelhar o catálogo de emotes.

Requer server.read.

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

Leia a lista de usuários do chat ou um único registro de usuário por id.

Requer users.read.

APIs de Moderação​

Essas são deleteMessage / kick / sendTo / replyTo em JavaScript e delete_message / kick / send_to / reply_to em Python.

owncast.chat.deleteMessage​

Oculte uma mensagem de chat dos espectadores, pelo ID da mensagem.

Requer chat.moderate.

owncast.chat.kick​

Desconecte um cliente de chat, pelo ID do cliente.

Requer chat.moderate.

owncast.chat.sendTo​

Envie uma mensagem privada a um único cliente conectado, pelo ID do cliente.

Requer chat.send.

owncast.chat.replyTo​

Sussurre uma resposta de volta para quem enviou uma mensagem de chat. Você pode passar tanto o objeto de mensagem completo do manipulador de mensagem de chat / filtro, ou um ID de cliente se é tudo o que você tem. Retorna um valor falsy quando a conexão do remetente não é mais conhecida, o que lhe dá uma queda limpa para uma mensagem pública.

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

Requer chat.send.

Comandos​

Para comandos de chat, declare uma tabela de comandos com aliases, cooldowns, controle de moderadores e listagens automáticas de !help. Veja Comandos de Chat.

Moderando usuários​

owncast.users.setEnabled​

Habilite ou desabilite um usuário de chat, por ID, com uma razão opcional: setEnabled em JavaScript, set_enabled em Python.

Requer users.moderate.

owncast.users.banIP​

Proíba um IP de entrar no chat: banIP em JavaScript, ban_ip em Python.

Requer users.moderate.

Filtros de chat​

Filtros veem mensagens do chat antes de serem transmitidas, com a capacidade de reescrevê-las ou descartá-las. Filtros executam na prioridade mais baixa primeiro. Um drop encerra a cadeia e a mensagem nunca chega aos filtros ou notificações posteriores. Um modify passa a nova carga para o próximo filtro.

filterChatMessage​

Recebe a mesma forma de ChatMessage que o manipulador de mensagens de chat e retorna um dos três resultados, construídos com o helper filter:

  • pass: deixa a mensagem passar sem alterações.
  • modify: substitui por uma nova carga.
  • drop: descarta (com uma razão). A cadeia para aqui.
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();
  },
});

Requer a permissão chat.filter. O servidor rejeita o carregamento se um plugin define o manipulador de filtro sem declarar essa permissão.

Prioridade do filtro (opcional)​

Números mais baixos são executados primeiro. Padrão 100. Set it with filterPriority (JavaScript) on the plugin definition, or by calling plugin.set_filter_priority(priority) (Python).

Use isso quando o comportamento do seu plugin depende de se outros filtros já foram executados. Por exemplo, um filtro de profanidade geralmente deve ser executado antes de um tradutor.

Segurança do filtro​

  • Erros são tratados como um passar. Um filtro que gera exceção nunca bloqueia o chat.
  • Filtros têm limite de tempo de 50 ms. Um filtro lento é cancelado e tratado como passar.
  • Após 5 falhas consecutivas (erros ou timeouts) o plugin é desabilitado automaticamente pelo resto da sessão. Uma chamada de filtro bem-sucedida reinicia o contador.

Limites impostos pelo host que importam para plugins de chat​

Alguns limites do host são importantes para planejar:

  • tempo de execução do filtro: 50 ms por mensagem
  • tempo de execução do manipulador de evento (mensagem de chat, usuário entrou, etc.): 500 ms por chamada
  • teto rígido por chamada: 10 s
  • tamanho da saída do filtro: 1 MiB
  • temporizadores pendentes: 64 ao mesmo tempo
  • intervalo de atraso do temporizador: 100 ms a 24 h

Isso significa que bots de chat e filtros devem ser leves, evitar idas lentas pela rede no caminho e manter as cargas reescritas pequenas.

Permissões que você comumente precisará​

  • chat.send: enviar mensagens de chat e respostas privadas.
  • chat.history: ler mensagens de chat recentes e clientes conectados.
  • chat.moderate: ocultar mensagens e desconectar clientes.
  • chat.filter: reescrever ou descartar mensagens antes da transmissão.
  • users.read: inspecionar registros de usuários.
  • users.moderate: desabilitar usuários de chat ou proibir IPs.

Veja Permissões para o modelo de segurança completo.

Exemplos de plugins de chat​

O SDK de plugins fornece pequenos exemplos focados em chat que mapeiam de perto os padrões nesta página (cada um tem uma versão em JavaScript e outra em Python):

  • echo-bot: o menor bot de resposta possível usando o manipulador de mensagem de chat + owncast.chat.send.
  • chat-logger: registra todas as mensagens do chat sem responder.
  • stream-tracker: combina comandos de chat, manipuladores de ciclo de vida do usuário de chat e anúncios de ação.
  • profanity-filter: reescreve mensagens sem descartá-las.
  • slow-mode: descarta mensagens usando msg.timestamp para limitação de taxa.
  • engagement-bot: modera deletando uma mensagem.
  • timer-bot: bots de lembrete/contagem regressiva acionados a partir do chat, usando temporizadores e o manipulador de tick.

Navegue por eles em examples/js · examples/python.

Onde isso se encaixa com os outros documentos de plugin​

  • Escolhendo um SDK e as páginas JavaScript / Python cobrem a configuração específica da linguagem, CLI e sintaxe.
  • Comandos de chat cobre tabelas de comando, o !help automático e mistura de comandos com seus próprios manipuladores de chat.
  • Manipuladores de eventos é a referência completa dos manipuladores para todos os eventos de plugin.
  • APIs Owncast é a referência completa da API para todos os métodos owncast.*.
  • Referência do manifesto cobre permissões, campos de identidade de bot e cada propriedade do manifesto.
  • Contribuindo UI cobre a UI do lado do espectador, sobreposições, botões, scripts e estilos se o seu plugin de chat também incluir peças de frontend.

Se você está começando do zero, leia Introdução Rápida primeiro e depois volte aqui.

Improve this page

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

Contributors to this documentation
Gabe KangasGabe Kangas