Ligação pelo WhatsApp via API não oficial: fazer, atender e tocar áudio

Pela API não oficial do WhatsApp você faz ligação de voz com um POST /{key}/call, atende ou recusa chamadas recebidas, encerra a chamada e ainda toca um áudio dentro da ligação ativa — tudo pelo mesmo número conectado por QR Code, sem aprovação da Meta. Isso abre casos como confirmação por voz, lembrete para quem pediu e uma URA simples, sem contratar telefonia.

Este guia mostra cada endpoint com exemplo em cURL, um fluxo completo de confirmação por voz e os cuidados para que ligação automatizada não vire motivo de denúncia.

A camada não oficial não é afiliada, endossada ou suportada pelo WhatsApp ou pela Meta. O uso é de responsabilidade de quem envia.

Oficial vs não oficial: são coisas diferentes

Já temos um artigo sobre a WhatsApp Calling API, o recurso de chamadas da Cloud API oficial da Meta. Lá, há requisitos de habilitação na conta e regras de cobrança da Meta.

Na camada não oficial, a lógica é outra: a instância está conectada como um aparelho do número, então liga como o app ligaria. Na prática:

Se você já usa a API oficial e quer chamadas com garantia formal da Meta, a Calling API é o caminho — e está na mesma plataforma. Para o restante, a não oficial resolve com muito menos atrito.

Antes de tudo: permissão de chamadas

Ligações exigem que a permissão de chamadas esteja habilitada na instância. Sem ela, o POST /call não inicia a chamada. Confira a configuração no painel e na documentação antes de testar.

Todos os endpoints abaixo usam a base https://us.api-wa.me/SUA_KEY/ — a key na URL já autentica a instância.

Fazer uma ligação

curl -X POST "https://us.api-wa.me/SUA_KEY/call" \
  -H "Content-Type: application/json" \
  -d '{ "to": "5511999999999" }'

O número vai no formato internacional, só dígitos. A resposta traz a identificação da chamada, que você usa nos próximos passos (tocar áudio, encerrar). Guarde esse identificador.

Tocar um áudio dentro da chamada

Esta é a parte que transforma ligação em automação. Com a chamada ativa, envie um áudio para ser tocado para quem atendeu:

curl -X POST "https://us.api-wa.me/SUA_KEY/call/ID_DA_CHAMADA/audio" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://seusite.com.br/audios/confirmacao-consulta.mp3" }'

O áudio pode ir por url, base64 ou file. Para mensagens personalizadas ("Olá, Carla, sua consulta é quinta às 14h"), você pode gerar o arquivo com um serviço de síntese de voz e mandar em base64, sem precisar hospedar.

Dicas que fazem diferença:

• Curto. Quinze a trinta segundos. Ligação longa de robô é desligada no meio.
• Identifique-se no começo. "Aqui é da Clínica Sorriso" nos primeiros segundos.
• Diga o que a pessoa deve fazer depois. "Responda SIM na conversa para confirmar."

A chamada também tem o caminho de volta: depois de atendida, a voz de quem está do outro lado chega em tempo real pelo Socket.IO da instância (evento call-audio), e você pode responder com áudio ao vivo pelo evento call-audio-in. É o que permite colocar uma IA para conversar na ligação — o passo a passo está em IA para atender ligação no WhatsApp.

Encerrar a chamada

Quando o áudio terminar, encerre:

curl -X POST "https://us.api-wa.me/SUA_KEY/call/end" \
  -H "Content-Type: application/json" \
  -d '{ "callId": "ID_DA_CHAMADA", "peerJid": "[email protected]" }'

Atender e recusar ligações recebidas

Quando alguém liga para o número, a instância recebe um evento de chamada no webhook. No formato meta ele chega com field: "call" e uma lista em value.calls, e cada item traz id, from (só dígitos), from_jid (o JID completo), status (offer quando a chamada está chegando) e is_video. Para atender ou recusar, use o id e o from_jid: é o JID completo que a API precisa para falar com o aparelho de quem ligou.

# Atender
curl -X POST "https://us.api-wa.me/SUA_KEY/call/accept" \
  -H "Content-Type: application/json" \
  -d '{ "callId": "ID_DA_CHAMADA", "callFrom": "[email protected]" }'

# Recusar
curl -X DELETE "https://us.api-wa.me/SUA_KEY/call/ID_DA_CHAMADA/[email protected]"

Atender por API faz sentido quando você vai tocar uma mensagem (horário de funcionamento, aviso de que o atendimento é por texto). O caso mais comum, porém, é recusar e responder por texto — número de atendimento que recebe dezenas de ligações e não tem quem atenda. Esse fluxo tem um guia só dele: recusar ligação automaticamente e responder por mensagem.

Link de chamada: deixe o cliente ligar

Nem sempre é você quem deve ligar. Às vezes é melhor oferecer um link de chamada para o cliente entrar quando puder — uma consultoria marcada, um suporte por voz agendado.

Gerar o link, sem enviar para ninguém (para colocar num e-mail ou no seu sistema):

curl -X POST "https://us.api-wa.me/SUA_KEY/message/create-call-link" \
  -H "Content-Type: application/json" \
  -d '{ "type": "audio" }'

Ou enviar direto na conversa, com uma legenda:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/call-link" \
  -H "Content-Type: application/json" \
  -d '{ "to": "5511999999999", "type": "audio", "caption": "Nossa conversa de quinta, 14h. É só tocar aqui." }'

É o formato mais respeitoso de todos: a pessoa decide a hora.

Fluxo completo: confirmação de consulta por voz

Um exemplo de ponta a ponta, em Node.js com fetch. O cliente pediu lembrete por ligação no agendamento — isso fica registrado no seu sistema.

const API = 'https://us.api-wa.me/SUA_KEY';
const post = (path, body) => fetch(`${API}${path}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(body),
}).then((r) => r.json());

async function confirmarPorVoz(agendamento) {
  // Só liga para quem pediu lembrete por ligação
  if (!agendamento.aceitaLigacao) return;

  const chamada = await post('/call', { to: agendamento.telefone });
  const callId = chamada.callId ?? chamada.id; // confira o campo na documentação

  // Na prática, aguarde o evento de chamada atendida no webhook
  // antes de tocar o áudio.
  await post(`/call/${callId}/audio`, { url: agendamento.audioUrl });

  // Reforço por texto: a confirmação acontece na conversa
  await post('/message/text', {
    to: agendamento.telefone,
    text: `Oi, ${agendamento.nome}! Sua consulta é ${agendamento.quando}. Responda SIM para confirmar ou REMARCAR.`,
  });
}

Repare que a confirmação em si acontece por texto. A ligação chama atenção; a resposta fica registrada na conversa, onde o seu webhook consegue ler. Esse híbrido costuma funcionar melhor do que tentar capturar resposta por voz.

URA simples

Com atender + tocar áudio + encerrar, dá para montar uma URA básica: atende, toca "nosso atendimento é por mensagem, já te enviamos o menu" e encerra, seguido de uma mensagem de lista com as opções. Para a maioria dos negócios, é mais útil do que menu por tecla: a pessoa escolhe tocando, e o atendimento continua no texto, onde o seu bot já trabalha. Se preferir que a pessoa fale o que precisa em vez de ouvir opções, veja a URA inteligente com IA.

O que não fazer com ligação automatizada

Ligação é o canal mais invasivo que existe. Uma mensagem espera; uma chamada interrompe. Por isso:

• Nunca ligue para lista. Ligação automatizada em sequência para quem não pediu é robocall, é denunciada rápido e derruba número. A WAME não apoia esse uso.
• Só com consentimento específico. "Aceito receber lembrete por ligação" é diferente de "aceito WhatsApp".
• Respeite horário. Horário comercial do destinatário, sem exceção.
• Uma tentativa. Não atendeu? Mande texto. Não ligue de novo em seguida.
• Nada de fan-out. Muitas chamadas para números diferentes em pouco tempo é exatamente o padrão que o anti-spam procura — veja o que derruba um número.

Usada assim — pouca, combinada, útil —, ligação pela API tem risco muito baixo e resolve o que texto sozinho não resolve.

Conclusão

A API não oficial do WhatsApp da WAME trata ligação como qualquer outro recurso: um endpoint para ligar, outros para atender, recusar, encerrar e tocar áudio, mais o link de chamada para o cliente escolher a hora. Sem aprovação da Meta e dentro do plano por instância. Use para quem pediu — confirmação, lembrete, URA simples — e deixe a conversa por texto registrar a resposta. Todos os parâmetros estão na documentação.