AstraChatLigação WhatsApp no Chatwoot: o atendente liga e atende na tela
A ligação WhatsApp no Chatwoot funciona com o AstraCalls, uma API gratuita e open source de chamadas de voz, e um widget de chamadas que deixa o atendente ligar para o cliente e atender a ligação na mesma tela da conversa.
Quem atende pelo Chatwoot conhece a cena: o cliente pede para falar por voz e o atendente precisa pegar o celular da empresa, procurar o contato e ligar por fora. A conversa se divide em dois lugares e ninguém sabe depois o que foi combinado. Com a ligação WhatsApp no Chatwoot, voz e chat ficam no mesmo lugar.
Neste artigo eu mostro como instalar o AstraCalls, a API gratuita e open source que criamos para ligações de voz pelo WhatsApp, conectar ao Chatwoot e ativar o widget de chamadas. O foco aqui é o atendente humano. Se você procura uma IA que atenda por voz, o assunto está no artigo sobre IA que atende ligação no WhatsApp.
O que é o AstraCalls
Até pouco tempo, ligação pelo WhatsApp via API só existia em ferramentas pagas. Um grupo de desenvolvedores da comunidade abriu o código de um projeto em Go, feito sobre a biblioteca whatsmeow, que permite fazer chamadas de voz. Era uma API crua, com pouco mais que as rotas de criar sessão e ligar, pensada para quem já desenvolve.
O AstraCalls é a nossa versão desse projeto, com os créditos para quem fez a base. O que eu mudei:
- troquei o SQLite pelo PostgreSQL, para ficar mais estável;
- deixei pronto para Docker, com Dockerfile e stack;
- acrescentei as rotas de mensagem (texto, imagem, arquivos) e o webhook de retorno;
- copiei o módulo de integração com o Chatwoot que a WAHA usa, então mensagens e áudios vão e voltam;
- criei o widget de chamadas para o Chatwoot;
- coloquei uma autenticação leve, que o projeto original não tinha;
- documentei a API com Swagger.
A licença é AGPL-3.0. Você pode copiar, modificar e até comercializar, desde que compartilhe com a comunidade as alterações que fizer.
O que você precisa
- Uma VPS com Portainer e Docker Swarm. Se ainda não tem, veja qual painel usar para hospedar.
- Um Chatwoot instalado e desbloqueado (Enterprise). O desbloqueio é obrigatório porque o widget entra por uma tela de scripts que só aparece nesse caso. Funciona com a imagem oficial, com outras distribuições e com o AstraChat. Para instalar do zero, siga o guia de como instalar o Chatwoot.
- Um subdomínio apontado para a VPS.
- Um número de WhatsApp para conectar.
A stack e o tutorial com os comandos estão na página de apoio do vídeo.
Instalando a API no Portainer
- Abra a stack do AstraCalls. No vídeo usei a imagem
develop, porque a API estava em fase de testes, mas já existe uma versão fixa lançada. Em produção, prefira a versão fixa. - Ajuste o limite de ligações simultâneas por sessão. Deixei 8 como padrão.
- Troque a chave da API por uma sua.
- Coloque o seu subdomínio no campo de URL.
- No Portainer, crie a stack, desative o Access Control e faça o deploy. A própria stack sobe o Postgres e cria o banco.
- Abra o subdomínio no navegador e entre com a chave que você definiu.
Na stack há também um proxy interno que faz o roteamento entre o contêiner e a VPS para a chamada funcionar. Não precisa mexer nele.
Sobre o limite: uma única sessão consegue fazer várias ligações ao mesmo tempo. Testei com quatro e cinco e rodou bem. Se você colocar 20, a API aceita, mas ninguém ainda testou a fundo como isso escala. Se precisar de muitas ligações em paralelo, eu instalaria mais de uma API em vez de subir muito o número.
Conectando o número e o Chatwoot
- No painel, crie uma sessão e leia o QR Code com o WhatsApp.
- Clique no botão de integrar com o Chatwoot e preencha a URL do Chatwoot, sem a barra no final.
- Informe o ID da empresa (aparece nas configurações da conta, no meu caso 1).
- Cole o token de acesso, que fica em Configurações de perfil no Chatwoot.
- No Chatwoot, crie uma caixa de entrada do tipo API. No campo de webhook, cole a URL de retorno que o painel do AstraCalls mostra.
- Selecione os agentes da caixa e, nas configurações dela, copie o identificador da caixa de entrada para o painel.
- Informe o ID da caixa, que é o número que aparece na URL depois de
inbox. - Salve e mande um "oi" de outro celular para testar.
No mesmo formulário há duas opções que valem a atenção:
- Refletir mensagens enviadas pela API: o que for disparado por fora, por exemplo pelo n8n, aparece na conversa do Chatwoot como nota privada. Nada é reenviado ao contato.
- Importar histórico ao conectar: traz as conversas antigas que o WhatsApp envia no pareamento. Ative antes de conectar o número, porque o histórico só chega nesse momento.
No meu teste a mensagem entrou com foto e nome sincronizados, e a resposta voltou para o WhatsApp. Até aqui é uma integração de mensagens comum.
Ativando o widget de chamadas
O widget entra como um script que roda junto com o Chatwoot:
- Entre no super admin do Chatwoot.
- Abra a URL da tela oculta de scripts (está no tutorial). Ela vem com um endereço de exemplo: troque pelo seu e confira se não ficou barra dupla.
- No script, coloque a URL do seu AstraCalls e a chave da API. Cuidado com as aspas e com
https://. - Cole o script na tela e clique em enviar.
- Atualize o Chatwoot. Se o ícone não aparecer, limpe o cache do navegador.
Um ícone de celular aparece no topo da conversa, mas só na caixa ligada ao AstraCalls e na empresa certa. O script respeita o ID da empresa e o ID da caixa, então nas outras caixas o ícone não aparece.
Como fica o dia a dia do atendente
Na conversa, o atendente clica no ícone de celular e abre um pequeno widget no canto da tela. Um clique para ligar e o celular do cliente toca. Quando o cliente liga para o número, o widget toca no Chatwoot e o atendente atende ali mesmo.
Testei com dois aparelhos, um iPhone e um Android, para garantir que funciona nos dois sistemas. A ligação funcionou nos dois sentidos.
Algumas dicas de uso:
- use fone de ouvido no computador, senão dá eco e microfonia;
- teste uma ligação de cada lado sempre que atualizar o Chatwoot ou o script;
- registre o que foi combinado numa nota privada da conversa logo depois de desligar.
Se a ideia é ligar para uma lista inteira com um áudio ou vídeo gravado, em vez de um atendente por vez, veja o disparo de ligações no WhatsApp com n8n.
SIP e proxy: ligações no PABX e um IP por número
O painel tem mais dois botões que fazem diferença em operação maior.
O SIP liga a sessão do WhatsApp a um PABX ou softphone, de dois jeitos. No primeiro, o PABX do cliente se registra no servidor do AstraCalls com as credenciais que o painel mostra: servidor, domínio, usuário e senha. No segundo, é o AstraCalls que se registra no seu PABX. Nos dois casos, as chamadas discadas pelo tronco saem pelo WhatsApp daquele número.
Para configurar, o próprio painel resume:
- Transporte UDP na porta 5060 e codec G.711 u-law (PCMU).
- No FreePBX, crie um tronco PJSIP com o usuário SIP do painel como Username e o servidor como SIP Server.
- Disque no formato internacional, por exemplo 5511999999999.
- Guarde essas credenciais como senha: quem tem acesso a elas consegue ligar por esse número.
O proxy faz a conexão do WhatsApp daquela conta (websocket e mídia) sair por um proxy próprio, como SOCKS5, com host, porta e, se precisar, usuário e senha. Salvar reconecta a sessão sozinho, e deixar o host vazio volta para a conexão direta. Ajuda quando você roda vários números no mesmo servidor e não quer todos saindo pelo mesmo IP.
O lado honesto
| Vantagem | O que você assume |
|---|---|
| API gratuita, sem cobrança por ligação | É uma API não oficial: existe risco de bloqueio do número |
| Roda no seu servidor, com várias sessões | Você cuida da instalação, das atualizações e do backup |
| Ligações simultâneas na mesma sessão | Escala ainda pouco testada, vá com calma no limite |
| Funciona com qualquer Chatwoot | O Chatwoot precisa estar desbloqueado para o widget |
No vídeo, gravado em junho de 2026, a API estava recém-lançada. Encontrou um problema? Mande um PR no repositório, ou relate no nosso grupo aberto. Quero manter essa API ativa.
Perguntas frequentes
Dá para fazer ligação de WhatsApp pelo Chatwoot?
Sim. Com o AstraCalls conectado e o widget de chamadas ativado, o atendente clica no ícone de celular no topo da conversa para ligar e também atende ali mesmo as chamadas que o cliente faz para o número.
O que é o AstraCalls?
O AstraCalls é uma API gratuita e open source para ligações de voz pelo WhatsApp, feita a partir de um projeto em Go sobre a biblioteca whatsmeow. Ele usa PostgreSQL, roda em Docker, tem rotas de mensagem, integração com o Chatwoot e um widget de chamadas, sob a licença AGPL-3.0.
A API de ligação do AstraCalls é gratuita?
Sim, ela não cobra por ligação. Em troca, é uma API não oficial, com risco de bloqueio do número, e a instalação, as atualizações e o backup ficam por sua conta.
Quantas ligações simultâneas o AstraCalls aguenta?
A stack vem com limite padrão de 8 ligações simultâneas por sessão, e nos testes quatro e cinco ligações ao mesmo tempo rodaram bem. A API aceita números maiores, mas a escala ainda foi pouco testada, então para muitas ligações em paralelo a sugestão é instalar mais de uma API.
A ligação pelo Chatwoot funciona no iPhone e no Android?
Sim. O teste foi feito com um iPhone e um Android, e a ligação funcionou nos dois sentidos: o atendente ligando para o cliente e o cliente ligando para o número.
O AstraCalls funciona com PABX?
Sim. Pelo botão SIP do painel, o PABX ou softphone se registra no servidor do AstraCalls, ou o AstraCalls se registra no PABX, e as chamadas do tronco saem pelo WhatsApp da sessão. O painel indica UDP na porta 5060 e codec G.711 u-law.
Quer as ligações já nativas no Chatwoot?
No AstraChat, a nossa versão do Chatwoot, o AstraCalls entra como provedor nativo e as ligações aparecem na própria conversa, junto com Kanban, agentes de IA, disparador, flows e chat interno. Tudo no seu servidor, com a sua marca e sem limite de atendentes.
Ele vem na Comunidade Astra Online, com código-fonte, atualizações, grupo VIP e a primeira instalação feita pelo especialista em Chatwoot Raphael Popiolek. Se a sua equipe precisa de treinamento ou de integrar ligações a outro sistema, mande uma mensagem no WhatsApp que a gente vê o seu caso.
