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.
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
sendonlyna 1ª linha de áudio einactivenas 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
relaycujo 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ó comcandidate,sdpMidesdpMLineIndex, 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.
Moderação
| Ação no servidor | O que acontece com o bot |
|---|---|
| Tirar FALAR ou silenciar o bot | Continua 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, suspender | Sessão encerrada em até 5 s: voice:session_ended com reason unauthorized ou suspended. |
| Desconectar o bot da call | voice:session_ended com reason: 'disconnected'. |
| Mover o bot para outro canal | voice:session_ended com reason: 'moved' e toChannelId. Para seguir, chame channel_voice:join no destino. |
Quem está em cada canal
/api/bot/servers/:serverId/voice-members{
"channels": [
{ "channelId": "…", "memberIds": ["userId", "…"] }
]
}Eventos de sinalização
Enviados pelo bot no mesmo socket do Gateway.
| Evento (bot → NEX) | Dados | Observaçõ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. |
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_update | Alguém entrou ou saiu: { serverId, channelId, participants } |
channel_voice:signal | Sinal WebRTC de uma pessoa: { channelId, fromId, signal } (só candidatos relay) |
voice:permission_changed | Mudou a permissão de falar: { serverId, channelId, canSpeak, serverMuted, canConnect } |
voice:session_ended | Sessão encerrada pelo NEX: { serverId, channelId, reason, toChannelId? } — reason: unauthorized, suspended, disconnected, moved ou disabled |
Erros e limites
| Situação | Resposta |
|---|---|
| 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 demais | Cada 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.
npm install @nexapponline/voice-clientconst { 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.