Chamadas WhatsApp API não oficial com a GoZAP

Quais operações de chamada existem na API?

O contrato separa ações de chamada, consulta, áudio e vídeo, histórico, gravação, SIP e links. As rotas abaixo descrevem os recursos documentados; a presença de uma rota não confirma que uma conta, serviço externo ou linha simultânea esteja habilitada em todo ambiente.

As rotas de controle e estado usam autenticação de chamada (callAuth); histórico, gravação, SIP e links usam autenticação da instância (auth). A credencial é o token da instância, não o ID. Para as operações com auth, o header token ou Authorization: Bearer SEU_TOKEN são aceitos. O middleware de chamada também reconhece um token de widget com escopo restrito.

Como iniciar, aceitar ou encerrar uma chamada?

Para iniciar, envie o telefone em phone; video é opcional. O handler também aceita telefone com pontuação e sinal de mais, removidos durante o processamento, ou um JID válido. Chamadas de grupo não são suportadas. A resposta de ações principais inclui success e call_id, que a aplicação deve guardar para consultar ou encerrar aquela sessão.

curl -X POST 'https://SEU-DOMINIO/call/make' \
  -H 'Content-Type: application/json' \
  -H 'token: SEU_TOKEN' \
  -d '{"phone":"5511999999999","video":false}'

Para aceitar, o corpo usa call_id obrigatório e from opcional. Para rejeitar, os mesmos campos são aceitos, embora o handler não marque campos obrigatórios nessa estrutura. Para encerrar, envie call_id. Leia a resposta e consulte o estado quando precisar refletir a situação na interface. A existência de uma resposta de sucesso de uma ação não deve ser apresentada como garantia de duração ou conclusão da chamada com outra pessoa.

O histórico aceita filtros direction, status, leg, limit, offset, from e to. Datas nos filtros são RFC3339; datas inválidas são ignoradas. O limite padrão é 100 registros e o máximo é 500. Use a consulta por call_id quando precisar abrir um item individual e separar os metadados da operação de mídia relacionada.

Quais são as formas de ligar na GoZAP?

Há quatro caminhos para fazer ou atender uma chamada de voz ou vídeo. Eles não são produtos separados: usam as operações descritas neste guia, e muda apenas onde fica a interface.

Como ligar por voz e vídeo pelo GoChat?

O GoChat é o aplicativo de atendimento web que o POD serve em /chat. Ele conversa direto com a API da instância, sem um servidor intermediário próprio. Para uma chamada, o GoChat usa as mesmas rotas documentadas acima:

1. Ligar: envia POST /call/make com o telefone em formato internacional e video verdadeiro ou falso, para escolher entre voz e vídeo. A resposta traz o call_id.
2. Atender: quando chega uma chamada, a pessoa aceita ou rejeita pela tela, e o GoChat envia POST /call/accept ou POST /call/reject com o call_id.
3. Áudio: o áudio do operador e o do contato passam pelo WebSocket GET /call/pcm. O navegador pede permissão para usar o microfone.
4. Vídeo: o vídeo do contato chega pelo WebSocket GET /call/video, em H.264, e é desenhado na tela da chamada. A câmera pode ser ligada durante a chamada, e o GoChat avisa a API com POST /call/video/upgrade.
5. Encerrar: POST /call/end com o call_id.

Como o navegador não consegue enviar cabeçalhos ao abrir um WebSocket, o GoChat envia o token da instância na query string dessas conexões; a API aceita essa forma para as rotas de chamada. As operações de iniciar, aceitar e áudio PCM exigem uma instância com connection_mode=companion. Chamadas de grupo não são suportadas.

O mesmo vale para a aparência: o GoChat pode receber o nome, o logo e as cores da sua marca, conforme descrito no guia de white label no seu domínio. Isso muda o visual, não o funcionamento das chamadas.

Como funcionam gravação, SIP e links?

Quando houver gravação disponível, a API fornece um link assinado com validade de 300 segundos. O parâmetro disposition=attachment orienta o download, e a rota DELETE remove a gravação. A gravação de áudio tem limite técnico de uma hora e depende do R2 e do serviço GoVoIP; o histórico informa uma janela de gravação R2 de sete dias. Essas dependências não equivalem a uma promessa de disponibilidade universal de gravação.

As operações SIP de ativação e rotação retornam parâmetros como uri, auth_user, auth_pass, baresip, domain e transport. Trate os valores de autenticação como segredo, armazene-os com controles apropriados e não os exponha em registros do navegador ou mensagens de suporte. GET /call/sip informa estado como enabled, registered, contact e call_runtime. As rotas retornam erro se o recurso estiver indisponível, e a ausência de linha simultânea comprada resulta em HTTP 402.

POST /call/link/create aceita media, waiting_room e event_start_time; nenhum é obrigatório. O valor video define mídia de vídeo e os demais valores resultam em áudio. A configuração de sala de espera recebe token, media e enabled, sendo o token exigido pelo serviço. /send/call-link pode encaminhar o link a number ou chatid, com pelo menos um destino, e aceita ainda media, waiting_room, event_start_time, name, description e text.

O que chega pelos webhooks de chamada?

Os eventos documentados incluem incoming-call, call-status e call. O payload pode trazer call_id, from, peer, phone, direction, status, media_type, video, operator_leg e, quando existente, reason. O timestamp é informado em milissegundos Unix. No bridge Mobile, o evento call também pode incluir call_creator e kind.

Projete o consumidor para registrar o evento e o identificador, atualizar a interface e tratar estados posteriores. Não interprete um webhook isolado como uma garantia de que a chamada permaneceu conectada, foi atendida ou teve duração mínima. Disponibilidade e entrega da chamada dependem da sessão e dos serviços envolvidos.

O endereço /call tem uma personalização específica: o HTML servido nessa rota pode ser substituído por HTML definido pelo cliente. As operações administrativas consultam, salvam e removem esse template, e permitem ler o HTML padrão. Isso descreve personalização do HTML em /call, sem ampliar a afirmação para outros caminhos ou para qualquer aspecto técnico não documentado.

A Calling API da Meta é um recurso da plataforma oficial, conforme a documentação da Meta sobre Calling. Essa referência estabelece o enquadramento oficial da funcionalidade da Meta; este guia descreve as rotas GoZAP e não atribui a elas o status de recurso oficial.

Toda API não oficial opera fora dos termos do WhatsApp e tem risco de restrição; a GoZAP não garante contra bloqueio. A documentação das rotas não promete duração, entrega ou gravação em qualquer configuração. Para avaliar os demais recursos de comunicação, veja grupos, comunidades, canais e status pela API e eventos e webhooks GoZAP.

Quando não escolher a GoZAP

Não escolha a GoZAP se seu requisito é usar apenas a plataforma oficial da Meta, ou se a operação exige um compromisso confirmado de entrega, duração mínima de chamada ou gravação em todas as sessões. A conexão GoZAP está disponível pelos modos Web e Mobile, ambos fora da API oficial da Meta. Esses compromissos não estão estabelecidos pelas rotas descritas. Se a personalização necessária for além do HTML servido em /call, valide o requisito antes de adotar o fluxo.

Para conferir parâmetros e autenticação das chamadas, abra a documentação da API GoZAP. O guia de risco de uso de API não oficial contextualiza o limite de política e operação.