Voz

Entre em canais de voz e transmita áudio.

Bots podem entrar em canais de voz de servidor e transmitir áudio (música, efeitos, texto falado). O áudio é WebRTC: o bot abre uma conexão com cada pessoa do canal, sempre passando pelo servidor de relay (TURN) do NEX, e o NEX faz a sinalização pelo Gateway e aplica as regras abaixo.

Pré-requisitos
Intent voice.connect ligado, bot instalado no servidor, VER_CANAL e CONECTAR_VOZ no canal e FALAR para ser ouvido (sem ele, o bot entra mudo).

Bots só transmitem

A voz de bot é só de saída. O NEX aplica isso no servidor, independente do código do bot:

  • O bot não recebe áudio, câmera nem tela de ninguém. A descrição de sessão (SDP) que o bot envia é reescrita para sendonly na 1ª linha de áudio e inactive nas demais, e os clientes do NEX nunca enviam mídia ao bot.
  • O bot não vê o IP das pessoas. Os clientes do NEX conectam com bots apenas por relay (TURN do NEX). O servidor só repassa ao bot candidatos ICE relay cujo endereço é o IP do TURN do NEX e cuja porta está na faixa de relay dele, conforme a configuração do próprio servidor. Um candidato "relay" com outro endereço é descartado, e o endereço relacionado (raddr) é sempre zerado. O candidato é reescrito só com candidate, sdpMid e sdpMLineIndex, e o SDP das pessoas chega sem IP. Sem TURN confiável configurado, o bot não entra em voz. Versões antigas do app que não seguem essa regra não trocam nenhum sinal com bots: veem o bot na call, mas não ouvem o áudio dele.
  • O bot recebe a lista pública de participantes. Para cada pessoa no canal chegam o perfil público (o mesmo que qualquer membro do servidor vê) e o estado de voz: mudo, surdo, câmera ligada, compartilhando tela, pode falar e horário de entrada. São indicadores, não o conteúdo do áudio, da câmera ou da tela.
  • O bot aparece para todos. Ele fica na lista do canal com o selo BOT e o indicador de fala, como qualquer participante. Não existe modo invisível em voz.

Essas garantias cobrem o que o NEX entrega ao bot pela sinalização e pela mídia de voz, para os clientes oficiais atuais. Não cobrem o que as pessoas publicam por outros meios (mensagens, perfil, links), e não são uma promessa de segurança absoluta.

Atenção
Gravação, transcrição ou qualquer uso do áudio das pessoas não é suportado. Não há permissão nem intent que libere isso.

Moderação

Ação no servidorO que acontece com o bot
Tirar FALAR ou silenciar o botContinua no canal, mas os clientes calam o áudio dele na hora (mesmo que ele continue enviando). Chega voice:permission_changed com canSpeak: false.
Tirar CONECTAR_VOZ/VER_CANAL, expulsar, desinstalar, suspenderSessão encerrada em até 5 s: voice:session_ended com reason unauthorized ou suspended.
Desconectar o bot da callvoice:session_ended com reason: 'disconnected'.
Mover o bot para outro canalvoice:session_ended com reason: 'moved' e toChannelId. Para seguir, chame channel_voice:join no destino.

Quem está em cada canal

GET/api/bot/servers/:serverId/voice-members
Auth: Bot
200
{
  "channels": [
    { "channelId": "…", "memberIds": ["userId", "…"] }
  ]
}

Eventos de sinalização

Enviados pelo bot no mesmo socket do Gateway.

Evento (bot → NEX)DadosObservações
channel_voice:join{ channelId }Exige callback de ack. Uma sessão por servidor; até 25 servidores ao mesmo tempo por bot.
channel_voice:signal{ channelId, toId, signal }Oferta/resposta/ICE para uma pessoa do canal. Até 64 KB. Sinal para outro bot é descartado.
channel_voice:leave{ channelId }Sai do canal.
Entrar
socket.emit('channel_voice:join', { channelId }, (res) => {
  if (!res.ok) return console.error(res.code, res.error);
  // { ok, participants, serverId, channelId, generation, canSpeak, botUserId }
  console.log('na call com', res.participants.length, 'pessoas; pode falar:', res.canSpeak);
});
Evento (NEX → bot)Quando
channel_voice:participants_updateAlguém entrou ou saiu: { serverId, channelId, participants }
channel_voice:signalSinal WebRTC de uma pessoa: { channelId, fromId, signal } (só candidatos relay)
voice:permission_changedMudou a permissão de falar: { serverId, channelId, canSpeak, serverMuted, canConnect }
voice:session_endedSessão encerrada pelo NEX: { serverId, channelId, reason, toChannelId? } — reason: unauthorized, suspended, disconnected, moved ou disabled

Erros e limites

SituaçãoResposta
Sem o intent voice.connect{ ok: false, error }
Sem acesso ao canal{ ok: false, error }
Já está em outro canal do mesmo servidor{ ok: false, error, channelId } (o canal atual)
Mais de 25 canais ao mesmo tempo{ ok: false, code: "SESSION_LIMIT", error }
Voz de bots desativada temporariamente pelo NEX{ ok: false, code: "VOICE_DISABLED", error }. Sessões ativas recebem voice:session_ended com reason: 'disabled'.
Servidor de relay indisponível{ ok: false, code: "RELAY_UNAVAILABLE", error }
Eventos demaisCada socket tem limite por evento por janela de tempo (ex.: 10 join). Acima disso o ack responde { ok: false, rateLimited: true }.

Se o socket cair, a vaga no canal fica reservada por 45 s para o bot reconectar. Depois disso, a sessão é encerrada.

Toda a mídia entre o bot e as pessoas passa pelo TURN do NEX, então a rede do bot precisa alcançar o TURN (UDP 3478). Peça credenciais temporárias em GET /api/bot/turn-credentials. Se o relay falhar, quem está na call vê "Sem áudio do bot" e o play() do SDK rejeita depois de 20 s sem ninguém conectado. Não existe conexão direta como alternativa.

Se o processo do bot reiniciar dentro dos 45 s de reconexão, o NEX avisa os clientes do canal para refazerem a conexão com ele. Não é preciso sair e entrar de novo.

Cliente de voz

O cliente de voz do NEX para Node.js 18+ (@nexapponline/voice-client no npm) cuida do Gateway, das conexões WebRTC por relay e do áudio (via ffmpeg). Ele só transmite: não tem API para receber mídia.

Instalação
npm install @nexapponline/voice-client
bot.js
const { VoiceClient } = require('@nexapponline/voice-client');

const voice = new VoiceClient({ token: process.env.NEX_BOT_TOKEN });

async function main(serverId, channelId) {
  await voice.connect();
  await voice.joinChannel(serverId, channelId);
  await voice.play(serverId, './musica.mp3');
}

main('ID_DO_SERVIDOR', 'ID_DO_CANAL_DE_VOZ').catch((err) => console.error(err.code, err.message));

A referência completa (eventos, erros, limites e privacidade) está no README do pacote. Quem preferir outra biblioteca pode implementar o mesmo protocolo com os eventos desta página.