Pular para o conteúdo principal
Um canal de voz é uma ligação de WhatsApp em andamento. Ele é a unidade de simultaneidade da conexão: com 3 canais, a conexão pode ter até 3 ligações ao mesmo tempo, somando as de saída e as recebidas.
Toda conexão WhatsApp não oficial vem com 1 canal incluso. Conexões da API Oficial (cloud_api) não fazem ligações por esta API.

Limites e preço

Os canais são por conexão: cada número tem os seus. Na fatura, os extras de todas as conexões da conta aparecem somados numa linha.

Consultar os canais da conexão

integer
Canais da conexão hoje (inclui o canal incluso).
integer
Máximo de canais por conexão.
number
Preço mensal de cada canal extra, em reais.
string | null
Como a conta paga: stripe (cartão) ou internal_pix (fatura Pix). null quando não há assinatura Scale.
boolean
true quando a conta não está no plano Scale e, por isso, não pode contratar canais extras.

Alterar a quantidade de canais

PUT /sessions/{sessionId}/voice-channels define o total de canais da conexão. Envie o número final desejado, não o incremento: para ir de 1 para 3 canais, envie 3. Repetir a mesma chamada não cobra de novo nem reinicia a conexão.
integer
obrigatório
Total de canais da conexão, de 1 a 5.
integer
Canais extras cobrados nesta conexão depois da troca.

Cobrança

1

Aumento

No cartão, o valor proporcional até o fim do ciclo é cobrado na hora. Se o cartão for recusado, a troca é desfeita e a API responde 402. Na fatura Pix, o proporcional entra na próxima fatura.
2

Redução

Vale na hora e não gera crédito do período já pago.
3

Aplicação

A conexão reinicia para aplicar a nova quantidade. Ligações em andamento nessa conexão caem; mensagens não são perdidas.

Erros

Ligações com mais de um canal

Com mais de um canal, cada ligação é independente e identificada pelo seu callId.
  • Novas ligações (POST /calls/place, POST /calls/stream) e atender uma recebida (POST /calls/accept) ocupam um canal. Com todos ocupados, a API recusa com o erro a call is already in progress — trate como “ocupado” e tente de novo quando uma ligação terminar.
  • Ofertas recebidas só ocupam canal quando você atende. Uma oferta tocando não bloqueia novas ligações.
  • Encerrar, silenciar e consultar estado (POST /calls/end, POST /calls/mute, POST /calls/state) passam a exigir o callId quando houver mais de uma ligação ativa. Sem ele, a API responde callId is required: N calls active em vez de agir na ligação errada. Com uma ligação só, o callId continua opcional.
  • Áudio em tempo real: cada ligação tem o seu próprio WebSocket de mídia (wsUrl), exatamente como em Ligações por Stream. Fechar o WebSocket encerra só aquela ligação.
  • Webhooks call.* não mudam: cada evento já traz o callId da ligação a que pertence. Use-o para separar as conversas.
Guarde o callId devolvido por place, stream ou accept junto do seu atendimento. É ele que endereça a ligação certa quando várias estão ativas.