Comandos e API - Social Stream Ninja

Comandos de bot

Comandos integrados de bot

O Social Stream Ninja inclui vários comandos integrados que seus espectadores podem usar no chat ou que você pode acionar pela API.

Comando	Descrição	Como ativar
`!joke`	Responde com uma piada nerd aleatória no estilo tiozão	Ative pela opção no menu da extensão
`hi`	Dá boas-vindas automaticamente a quem disser "hi" no chat	Ative pela opção no menu da extensão
`!cycle`	Quando ativado, permite que espectadores alterem cenas do OBS	Ative pela opção no menu da extensão

Nota: Comandos de bot só funcionam quando a resposta automática está configurada corretamente e você tem permissão para publicar mensagens nas respectivas plataformas.

Configuração de respostas automáticas

Para que as respostas automáticas funcionem corretamente:

Verifique se está conectado à plataforma (YouTube, Twitch etc.)
Verifique se a janela de chat está visível (não minimizada)
Tente enviar manualmente uma mensagem de teste primeiro para confirmar as permissões
Ative as opções dos comandos específicos no menu da extensão

Se você vir uma barra azul de depuração quando as respostas automáticas forem acionadas, poderá ocultá-la iniciando o Chrome com o parâmetro --silent-debugger-extension-api .

API do servidor

Visão geral

O Social Stream Ninja oferece uma API avançada que permite controlar programaticamente todos os aspectos da sua configuração de transmissão. O servidor de API pode enviar comandos à sua configuração e ouvir mensagens recebidas dos serviços de chat unificados.

Gerenciamento de sobreposições

Controle mensagens em destaque, limpe sobreposições e ajuste a aparência do conteúdo na transmissão.

Integração por webhook

Receba eventos de serviços de terceiros, como Stripe, Ko-Fi e Buy Me A Coffee.

Exportação de mensagens

Exporte mensagens de chat para um arquivo ou encaminhe-as por webhook (POST) para integrações personalizadas.

Configurações necessárias (Configurações globais → Mecânica):

🎮 Controle remoto (StreamDeck/Bitfocus): Ative "Ativar controle remoto da extensão por API" (Opção 1) — Conecte a canal 1
📡 Ouvinte de chat (aplicativos Python/Node): Ative a Opção 1 + "Enviar mensagens de chat ao servidor de API" (Opção 3) — Conecte a canal 4

Veja: documentação completa da API para guias detalhados de configuração e exemplos de código.

Endpoints de API e métodos de conexão

HTTP GET/POST

https://io.socialstream.ninja/{sessionID}/{action}/{target}/{value}

Ideal para comandos simples do Stream Deck ou scripts personalizados.

WebSocket

wss://io.socialstream.ninja:443

Para comunicação bidirecional em tempo real com reconexão automática.

Se preferir manter conexões ponto a ponto sem ativar o modo WebSocket, você pode usar o SDK WebRTC do Social Stream Ninja. Ele inclui exemplos para Node e navegador, como o ouvinte do Social Stream Ninja.

Eventos enviados pelo servidor

https://io.socialstream.ninja/sse/{sessionID}

Para atualizações unidirecionais do servidor em tempo real.

Sistema de canais

A API usa um sistema de canais para encaminhar mensagens:

	- Channel 1: Remote control commands (default for StreamDeck/Bitfocus)
	- Channel 2: Dock page output
	- Channel 3: Extension receives commands from Dock
	- Channel 4: Chat messages from Extension (use this to receive Twitch/YouTube chat!)
	- Channel 5: Waitlist/giveaway communication
	- Channels 6-9: Reserved for future use

Conecte com o canal desejado:

// To receive chat messages (listen on channel 4):
wss://io.socialstream.ninja/join/SESSION_ID/4

// To send commands (channel 1 default):
wss://io.socialstream.ninja/join/SESSION_ID

Comandos comuns da API

Ação	Descrição	Exemplo
`sendChat`	Envia uma mensagem a todas as plataformas de chat conectadas	`https://io.socialstream.ninja/SESSIONID/sendChat/null/Hello everyone!`
`sendEncodedChat`	Envia uma mensagem codificada para URL a todas as plataformas	`https://io.socialstream.ninja/SESSIONID/sendEncodedChat/null/Hello%20everyone%21`
`clearOverlay`	Limpa a mensagem em destaque da sobreposição	`https://io.socialstream.ninja/SESSIONID/clearOverlay`
`nextInQueue`	Exibe a próxima mensagem da fila	`https://io.socialstream.ninja/SESSIONID/nextInQueue`
`autoShow`	Alterna o destaque automático de mensagens	`https://io.socialstream.ninja/SESSIONID/autoShow/toggle`
`blockUser`	Bloqueia um usuário de uma plataforma específica	`https://io.socialstream.ninja/SESSIONID/blockUser/null/{"chatname":"username","type":"twitch"}`
`extContent`	Envia conteúdo externo como mensagem de chat	`https://io.socialstream.ninja/SESSIONID/extContent/null/{"chatname":"User","chatmessage":"Hello"}`
`pin`	Fixa uma mensagem existente do dock pelo ID ou um objeto completo de mensagem. Exige `dock.html` aberto na mesma sessão.	`https://io.socialstream.ninja/SESSIONID/pin/null/MESSAGE_MID`
`unpin`	Desafixa uma mensagem existente do dock pelo ID. Use o campo/segmento de caminho target para um dock com rótulo.	`https://io.socialstream.ninja/SESSIONID/unpin/null/MESSAGE_MID`
`nextPinned`	Destaca a primeira mensagem fixada do dock.	`https://io.socialstream.ninja/SESSIONID/nextPinned`
`removefromwaitlist`	Remove a primeira entrada ativa da lista de espera ou a entrada ativa numerada em `value`	`https://io.socialstream.ninja/SESSIONID/removefromwaitlist/null/1`
`highlightwaitlist`	Destaca a primeira entrada ativa da lista de espera ou a entrada ativa numerada em `value`	`https://io.socialstream.ninja/SESSIONID/highlightwaitlist/null/1`
`stopentries` / `startentries`	Interrompe ou retoma novas entradas na lista de espera sem limpar a lista existente. `openentries` e `resumeentries` são aliases de `startentries`.	`https://io.socialstream.ninja/SESSIONID/stopentries`
`selectwinner`	Seleciona um ou mais vencedores aleatórios da lista de espera/sorteio	`https://io.socialstream.ninja/SESSIONID/selectwinner/null/1`
`downloadwaitlist`	Baixa a lista de espera atual como arquivo TSV pela página/aplicativo do Social Stream em execução	`https://io.socialstream.ninja/SESSIONID/downloadwaitlist`
`drawmode`	Ativa/desativa o modo de sorteio ou alterna quando `value` é igual a `toggle`	`https://io.socialstream.ninja/SESSIONID/drawmode/null/toggle`
`waitlistmessage`	Define o título da lista de espera ou do sorteio mostrado na página da lista de espera	`https://io.socialstream.ninja/SESSIONID/waitlistmessage/null/Type%20!join%20to%20enter`
`resetwaitlist`	Limpa a lista de espera e reabre as entradas	`https://io.socialstream.ninja/SESSIONID/resetwaitlist`

Ver documentação completa da API

Ambiente interativo de testes da API

Experimente a API no nosso ambiente interativo de testes, que oferece acesso fácil a todos os comandos e recursos:

Para um conjunto menor de botões de operação ao vivo no OBS, use o Dock de controle do Social Stream e siga o guia de configuração do OBS.

Abrir ambiente de testes da API

Testar comandos

Experimente todos os comandos da API em um ambiente seguro

Gerar código

Obtenha exemplos de código para HTTP, WebSocket e SSE

Ver resultados

Veja respostas em tempo real aos seus comandos

Criar testes

Gere mensagens de teste com conteúdo aleatório

Nota: Lembre-se de substituir SESSIONID pelo seu ID real de sessão do Social Stream Ninja!

StreamDeck e Companion

Integração com StreamDeck

O Social Stream Ninja se integra ao StreamDeck de várias formas: ações HTTP nativas e integração com Bitfocus Companion.

Método HTTP/API

Use a ação "Website" do StreamDeck com "GET request in background" ativado para enviar comandos diretamente à API.

Bitfocus Companion

Integração nativa com ações prontas, retorno em tempo real e variáveis para conteúdo dinâmico.

Integração com Companion

O Bitfocus Companion oferece controle avançado do Social Stream Ninja por APIs WebSocket ou HTTP.

Ação	Descrição	Método de API
Limpar mensagem em destaque	Remove da sobreposição a mensagem atualmente em destaque	WebSocket/HTTP
Próxima da fila	Exibe a próxima mensagem enfileirada	WebSocket/HTTP
Alternar exibição automática	Ativa/desativa o destaque automático de mensagens	WebSocket/HTTP
Enviar mensagem de chat	Envia uma mensagem a todas as plataformas conectadas	WebSocket/HTTP

Variáveis dinâmicas

featured_message - Texto da mensagem atualmente em destaque
featured_username - Nome do usuário atualmente em destaque
queue_size - Quantidade de mensagens na fila

Recursos de configuração

Obter Companion Documentação do módulo

Integração com IA

Modo de bot de chat com IA

O Social Stream Ninja oferece ampla integração com IA para melhorar suas transmissões com respostas de chat, moderação e outros recursos de IA. Escolha provedores locais ou na nuvem conforme suas necessidades.

Respostas automatizadas de chat

Deixe a IA interagir automaticamente com seus espectadores, respondendo a perguntas e mantendo a conversa animada mesmo quando você estiver concentrado no conteúdo.

Moderação de conteúdo

Use IA para ajudar a moderar o chat, identificando mensagens potencialmente prejudiciais e tratando-as automaticamente conforme suas preferências. Escolha entre modo sem bloqueio ou com bloqueio estrito.

Busca RAG

A geração aumentada por recuperação permite que a IA pesquise sua base de conhecimento personalizada para fornecer respostas precisas e específicas sobre seu conteúdo.

Várias instâncias de bot

Execute diferentes instâncias de bot para várias finalidades: bot de chat público, bot privado individual, bot de censura e até um coapresentador multimodal de IA que vê e ouve.

Provedores de IA suportados

O Social Stream Ninja oferece suporte a vários provedores de IA, desde modelos totalmente locais no navegador/runtime até APIs hospedadas:

Ollama (API local nativa)

Modelos de IA gratuitos, privados e auto-hospedados no seu computador pela API própria do Ollama.

Local Gemma 4

Execute Gemma 4 no navegador após espelhar os arquivos do modelo no seu próprio servidor de recursos; o servidor largefiles do SSN atualmente não inclui arquivos do Gemma.

Local Qwen 3.5

Execute Qwen 3.5 no navegador a partir de arquivos de modelo hospedados por você para respostas locais e privadas.

ChatGPT / OpenAI

APIs da OpenAI, incluindo modelos modernos de chat e voz em tempo real.

Google Gemini

Modelos Google Gemini, incluindo opções atuais de texto Gemini 2.5 e multimodais ao vivo.

DeepSeek

Modelos de IA eficientes e econômicos, otimizados para tarefas de conversação.

xAI (Grok)

APIs xAI Grok, incluindo sessões de voz em tempo real ao usar segredos temporários de cliente.

AWS Bedrock

Modelos de IA de nível empresarial de vários provedores, incluindo Claude e Llama.

OpenRouter

Acesso a vários modelos de IA por uma interface de API unificada.

Groq

Inferência de chat de baixa latência compatível com OpenAI para respostas rápidas de conversação.

API personalizada (compatível com OpenAI)

Conecte a llama.cpp, LM Studio, vLLM ou qualquer outro endpoint compatível com OpenAI.

Nota: O Ollama usa sua própria API nativa. Para llama.cpp, LM Studio, vLLM ou outros servidores compatíveis com OpenAI, escolha API personalizada.

Integração de síntese de voz

O Social Stream Ninja inclui amplo suporte a síntese de voz para mensagens de bot e conteúdo de chat em destaque:

Síntese de voz do sistema

Síntese de voz gratuita e integrada usando o sintetizador de voz do sistema operacional.

Kokoro

Síntese de voz gratuita executada localmente com WebGPU/CPU para usuários que priorizam privacidade.

Kitten TTS

Síntese de voz leve no navegador que baixa um modelo pequeno para gerar voz localmente.

ElevenLabs

Síntese de voz premium com vozes naturais e personalizáveis.

Google Cloud TTS

Vozes de alta qualidade com amplas opções de idiomas e personalização.

Gemini (síntese de voz em prévia)

Modelos neurais de voz em prévia do Google com opções selecionáveis de voz e idioma.

Speechify

Síntese de voz com IA e recursos de conversão de voz natural.

OpenAI TTS

Síntese de voz da OpenAI com vozes, modelos e endpoints compatíveis opcionais selecionáveis.

Nota: A síntese de voz exige que a página de sobreposição apropriada esteja aberta no OBS. Cada provedor oferece opções diferentes de vozes, latência, preços ou requisitos de hardware.

Instâncias e sobreposições de bots

O Social Stream Ninja oferece várias instâncias de bot para diferentes usos:

Tipo de bot	URL	Descrição
Bot principal de chat	`/bot.html`	Sobreposição do bot principal com síntese de voz opcional e respostas no chat público
Interface de chat privado	`/chatbot.html`	Página dedicada de bot individual que não compartilha o conjunto de dados RAG nem o histórico de chat do bot principal
Bot de censura	(executa em segundo plano)	Filtra, limpa ou bloqueia automaticamente mensagens recebidas
Coapresentador de IA	`/cohost.html`	IA multimodal que pode ver sua tela, ouvir áudio e interagir

Configurar a integração com IA

Siga estas etapas para configurar a integração com IA no menu atual:

1

Escolha e conecte seu provedor LLM

Selecione seu provedor em Configurar provedor de serviço LLM e preencha os campos correspondentes:

Ollama: Instale localmente e defina o endpoint, se necessário
Local Gemma / Local Qwen: Use arquivos de modelo hospedados para o navegador e, opcionalmente, substitua a pasta do modelo; Qwen pode usar o largefiles do SSN, enquanto Gemma exige sua própria pasta espelhada
ChatGPT, Gemini, DeepSeek, xAI, Groq, OpenRouter, Bedrock: Adicione sua chave de API e modelo preferido
API personalizada: Insira um endpoint compatível com OpenAI, ID do modelo e chave de API opcional

2

Testar o bot de chat selecionado

Use o recurso integrado Testar bot de chat selecionado para verificar provedor, modelo e credenciais antes de entrar ao vivo.

3

Configure o comportamento do bot

Personalize como o bot se comporta no chat:

Ativar o bot de chat com IA LLM
Defina o nome do bot, as palavras de acionamento e o limite de frequência de respostas
Escolha se as respostas voltam ao chat ou vão apenas para a página de sobreposição do bot
Adicione instruções personalizadas de tom, função e regras de moderação

4

Ative recursos extras opcionais

Ative os recursos que deseja usar com o bot:

Ative síntese de voz para as respostas do bot e escolha um provedor
Escolha ocultação automática por tempo fixo, tamanho da mensagem ou após síntese de voz para /bot.html; use clearBotOverlay para limpeza manual
Ative RAG e envie documentos para respostas informadas por conhecimento
Ative o bot de censura para moderação ou modo de bloqueio estrito
Abrir /bot.html, /chatbot.html, ou /cohost.html no OBS ou em um navegador, conforme necessário

Documentação detalhada

Para instruções completas de configuração e mais detalhes sobre síntese de voz, use estes guias:

Guia de configuração do bot de chat com IA Guia de síntese de voz local com IA Contas de bot para respostas automáticas Download oficial do Ollama

Controle por MIDI e atalhos

Integração MIDI

Controle o Social Stream Ninja usando controladores MIDI, atalhos de teclado ou StreamDeck com plugins MIDI.

Requisitos de configuração

Ative o suporte a MIDI nas configurações da extensão
Instale um dispositivo virtual de loopback MIDI (ex.: loopMIDI)
Configure seu controlador MIDI ou plugin MIDI do StreamDeck

Número CC	Valor	Ação	Notas
102	1	Enviar "1" ao chat	Reação rápida
102	2	Enviar "LUL" ao chat	Reação com emote
102	3	Contar uma piada	Dispara uma resposta do bot
102	4	Limpar sobreposição	Remove a mensagem em destaque

Dica: O controle MIDI funciona melhor com controladores físicos, mas também pode ser acionado por dispositivos MIDI virtuais.

Suporte a atalhos de teclado

Use atalhos de teclado para acessar rapidamente funções comuns.

Atalhos podem ser configurados no menu e funcionam em todo o sistema quando o navegador está em foco ou quando o aplicativo é usado.

Integração por webhook

Serviços de doação

O Social Stream Ninja pode receber doações e eventos de serviços de terceiros por webhooks; veja alguns serviços populares abaixo:

Stripe

Processe doações por cartão de crédito diretamente pela sua conta Stripe.

Crie um link de pagamento em stripe.com
No painel do Stripe, acesse Desenvolvedores → Webhooks
Adicione o endpoint: https://io.socialstream.ninja/SESSIONID/stripe
Selecione o evento checkout.session.completed
Adicione &server à URL do seu dock

Ko-Fi

Receba doações de café dos seus apoiadores.

Entre na sua conta Ko-Fi
Vá para Configurações de webhook
Adicione https://io.socialstream.ninja/SESSIONID/kofi como URL do webhook
Adicione &server à URL do seu dock
Teste com o botão "Enviar teste de doação única"

Buy Me A Coffee

Receba doações pela popular plataforma Buy Me A Coffee.

Entre na sua conta Buy Me A Coffee
Acesse as configurações de webhook
Adicione https://io.socialstream.ninja/SESSIONID/bmac como URL do webhook
Adicione &server à URL do seu dock para receber eventos
Eventos de doações e de membros são suportados

Nota de segurança: Mantenha seu ID de sessão privado, pois qualquer pessoa que o tiver pode enviar doações falsas para sua sobreposição. A URL do webhook deve ser tratada como informação confidencial.

Integração com serviços externos

O Social Stream Ninja também pode enviar dados a serviços de terceiros:

Serviço	Parâmetro de URL	Descrição
Singular Live	`&singular=IDENTIFIER`	Envia mensagens selecionadas ao Singular Live para sobreposição de destaque
H2R	`&h2r=IDENTIFIER`	Envia mensagens selecionadas a um servidor H2R local
POST genérico	`&postserver=URL`	Envia mensagens selecionadas a um endpoint personalizado via POST
PUT genérico	`&putserver=URL`	Envia mensagens selecionadas a um endpoint personalizado via PUT

Estes parâmetros devem ser adicionados à URL da página do dock.

Scripts personalizados

JavaScript personalizado

Você pode criar seus próprios comandos e funcionalidades personalizando o código JavaScript:

Usar custom.js

Renomeie custom_sample.js com o nome de arquivo custom.js
Edite o arquivo para adicionar sua funcionalidade personalizada
Abra o arquivo dock.html localmente para que custom.js seja carregado

Este método permite personalizações e gatilhos complexos.

Sobreposições personalizadas

Criar sobreposições personalizadas

Você pode criar sobreposições de chat totalmente personalizadas do zero para combinar com o estilo e o funcionamento da sua transmissão. O Social Stream Ninja oferece uma base flexível para você desenvolver.

Começar com um modelo

Comece pelo nosso modelo de sobreposição de exemplo para entender o básico:

// View the sample overlay
https://socialstream.ninja/sampleoverlay?session=SESSIONID

Este modelo mínimo inclui apenas o código essencial para uma sobreposição funcional.

Ver sobreposição de exemplo

Principais recursos para personalizar

Alternar entre mensagens em destaque e todas as mensagens
Personalize a aparência com CSS
Adicione animações personalizadas para novas mensagens
Implemente sua própria filtragem de mensagens
Adicione elementos interativos com JavaScript

Etapas de implementação

Baixe o arquivo HTML de exemplo de sobreposição
Edite o HTML para seu layout personalizado
Personalize o CSS para a aparência desejada
Modifique o JavaScript conforme necessário para comportamentos personalizados
Salve o arquivo localmente para usar como Fonte de navegador no OBS

API do cronômetro

Controle remoto de `timer.html`

A página de cronômetro tem escopo intencionalmente limitado: um cronômetro, controles opcionais de operação, estados de aviso, tempo extra e alguns estilos visuais.

Ações úteis incluem starttimer, pausetimer, resettimer, timeradd, timersubtract, e settimer.

{
  "action": "settimer",
  "value": {
    "seconds": 300,
    "label": "Interview",
    "mode": "countdown",
    "style": "stage",
    "warnSeconds": 60,
    "dangerSeconds": 15
  }
}

Para consultar o estado atual do cronômetro, use gettimerstate com um token de retorno.

{ "action": "gettimerstate", "get": "timer-state-1" }

Use a página com timer.html?session=YOUR_SESSION&server se quiser controlá-la diretamente pelo servidor de API.