📞 WhatsApp Call API

API REST em Node.js para realizar e gerenciar ligações de voz e vídeo via WhatsApp de forma programática

⚡ Início Rápido

# 1. Clone e instale
git clone https://github.com/seu-usuario/whatsapp-call-api.git
cd whatsapp-call-api
npm install

# 2. Configure
cp .env.example .env

# 3. Inicie o servidor
npm start

# 4. Escaneie o QR Code que aparecerá no terminal com seu WhatsApp

# 5. Faça sua primeira chamada!
curl -X POST http://localhost:3000/api/call \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "5511999999999", "isVideo": false}'

Pronto! 🎉 Sua API está rodando em http://localhost:3000

📋 Índice

Início Rápido
Sobre o Projeto
Características
Pré-requisitos
Instalação
Configuração
Uso
Documentação da API
Docker
Estrutura do Projeto
Tecnologias
Contribuindo
Licença

📚 Documentação Adicional

💡 Exemplos de Uso - Exemplos práticos e casos de uso
🐛 Solução de Problemas - Guia completo de troubleshooting

🎯 Sobre o Projeto

A WhatsApp Call API é uma solução REST completa que permite integrar funcionalidades de chamadas do WhatsApp em suas aplicações. Construída sobre a biblioteca Baileys, ela oferece endpoints simples e eficientes para:

Iniciar chamadas de voz e vídeo
Gerenciar chamadas recebidas
Monitorar status de conexão
Automatizar fluxos de atendimento

Por que usar?

✅ Simples: API REST fácil de integrar em qualquer linguagem
✅ Completo: Suporte a voz e vídeo
✅ Moderno: Node.js 20+ com ES Modules
✅ Dockerizado: Deploy fácil com Docker Compose
✅ Bem Documentado: Exemplos práticos e documentação detalhada

✨ Características

📞 Chamadas de Voz e Vídeo: Inicie chamadas programaticamente
🔐 Autenticação Persistente: QR Code gerado automaticamente na primeira execução
🔄 Reconexão Automática: Mantém a conexão ativa mesmo após instabilidades
📊 Status em Tempo Real: Monitore o estado da conexão WhatsApp
🎨 QR Code Visual: Endpoint para obter QR Code como imagem base64
🐳 Docker Ready: Configuração completa para containers
📝 Logging Estruturado: Utiliza Pino para logs eficientes
🛡️ Tratamento de Erros: Respostas padronizadas e informativas

🔧 Pré-requisitos

Antes de começar, certifique-se de ter instalado:

Node.js 20.x ou superior (Download)
npm 9.x ou superior (vem com Node.js)
Git (opcional, para clonar o repositório)
Docker e Docker Compose (opcional, para execução em containers)

Verificando versões

node --version   # Deve retornar v20.x.x ou superior
npm --version    # Deve retornar 9.x.x ou superior

📦 Instalação

Opção 1: Instalação Local

Clone o repositório

git clone https://github.com/seu-usuario/whatsapp-call-api.git
cd whatsapp-call-api

Instale as dependências

npm install

Configure as variáveis de ambiente

cp .env.example .env

Edite o arquivo .env conforme necessário:

PORT=3000
SESSION_NAME=whatsapp-call-session

Inicie o servidor

# Modo desenvolvimento (com auto-reload)
npm run dev

# Modo produção
npm start

Opção 2: Docker (Recomendado)

# Build e iniciar containers
docker-compose up -d

# Visualizar logs
docker-compose logs -f

# Parar containers
docker-compose down

⚙️ Configuração

Variáveis de Ambiente

Variável	Descrição	Padrão	Obrigatório
`PORT`	Porta do servidor Express	`3000`	Não
`SESSION_NAME`	Nome da sessão WhatsApp	`whatsapp-call-session`	Não

Autenticação WhatsApp

Na primeira execução, será necessário autenticar com o WhatsApp:

Inicie o servidor (o QR Code aparecerá no terminal)

npm start

Escaneie o QR Code com o WhatsApp no celular:
- Abra o WhatsApp
- Vá em Configurações > Aparelhos conectados
- Toque em Conectar um aparelho
- Escaneie o QR Code exibido no terminal
Alternativa: Obtenha o QR Code via API

curl http://localhost:3000/api/qr

A autenticação será salva em auth_info_baileys/ e reutilizada nas próximas execuções.

🚀 Uso

Iniciando o servidor

# Desenvolvimento (com nodemon - reinicia automaticamente)
npm run dev

# Produção
npm start

O servidor estará disponível em: http://localhost:3000

Verificando status

curl http://localhost:3000/api/status

Resposta esperada:

{
  "connected": true,
  "state": "connected",
  "timestamp": "2025-11-14T10:30:00.000Z"
}

📚 Documentação da API

Base URL

http://localhost:3000/api

🔌 Gerenciamento de Conexão

`GET /api/status`

Verifica o status da conexão com WhatsApp.

Resposta (200 OK)

{
  "connected": true,
  "state": "connected",
  "timestamp": "2025-11-14T10:30:00.000Z"
}

Estados possíveis:

disconnected - Desconectado
qr - Aguardando leitura do QR Code
connected - Conectado e autenticado
reconnecting - Reconectando

`GET /api/qr`

Obtém o QR Code para autenticação (disponível apenas quando não conectado).

Resposta (200 OK)

{
  "qrCode": "2@abc123...",
  "qrImage": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "timestamp": "2025-11-14T10:30:00.000Z"
}

Resposta (404 Not Found) - Quando já está conectado

{
  "error": "QR Code não disponível",
  "message": "WhatsApp já está conectado ou QR Code ainda não foi gerado"
}

Uso do QR Code:

qrCode: String do QR Code (para geração própria)
qrImage: Imagem base64 pronta para exibir em <img src="...">

📞 Operações de Chamada

`POST /api/call`

Inicia uma chamada de voz ou vídeo.

Request Body

{
  "phoneNumber": "5511999999999",
  "isVideo": false
}

Parâmetros:

phoneNumber (string, obrigatório): Número com código do país (sem + ou espaços)
isVideo (boolean, opcional): true para videochamada, false para voz (padrão)

Resposta (200 OK)

{
  "success": true,
  "callId": "call_1731582600000_abc123def",
  "to": "5511999999999@s.whatsapp.net",
  "type": "audio",
  "timestamp": "2025-11-14T10:30:00.000Z"
}

Resposta (400 Bad Request)

{
  "error": "Número de telefone é obrigatório"
}

Resposta (500 Internal Server Error)

{
  "error": "Erro ao fazer chamada",
  "message": "WhatsApp não está conectado"
}

Exemplo com cURL:

curl -X POST http://localhost:3000/api/call \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "5511999999999", "isVideo": false}'

`POST /api/call/reject`

Rejeita uma chamada recebida.

Request Body

{
  "callId": "call_123456",
  "callFrom": "5511999999999@s.whatsapp.net"
}

Parâmetros:

callId (string, obrigatório): ID da chamada a ser rejeitada
callFrom (string, obrigatório): JID de quem está ligando

Resposta (200 OK)

{
  "success": true,
  "message": "Chamada rejeitada",
  "callId": "call_123456",
  "timestamp": "2025-11-14T10:30:00.000Z"
}

`POST /api/call/terminate`

Encerra uma chamada ativa.

Request Body

{
  "callId": "call_123456"
}

Parâmetros:

callId (string, obrigatório): ID da chamada a ser encerrada

Resposta (200 OK)

{
  "success": true,
  "message": "Chamada encerrada",
  "callId": "call_123456",
  "timestamp": "2025-11-14T10:30:00.000Z"
}

`GET /api/call/history`

Obtém o histórico de chamadas (atualmente retorna array vazio - implementação futura).

Resposta (200 OK)

{
  "success": true,
  "message": "Histórico de chamadas não implementado",
  "calls": []
}

📝 Nota: Este endpoint será implementado em versões futuras com armazenamento em banco de dados.

🐳 Docker

Executar com Docker Compose

# Iniciar serviço
docker-compose up -d

# Ver logs em tempo real
docker-compose logs -f whatsapp-call-api

# Parar serviço
docker-compose down

# Rebuild após alterações
docker-compose up -d --build

Configuração Docker

O docker-compose.yml está configurado para:

✅ Mapear porta 3000
✅ Persistir autenticação em volume (auth_info_baileys)
✅ Reiniciar automaticamente após falhas
✅ Usar variáveis de ambiente

Volume de Dados

volumes:
  - ./auth_info_baileys:/app/auth_info_baileys

Importante: O diretório auth_info_baileys/ contém as credenciais da sessão WhatsApp. Mantenha-o seguro e nunca commite no Git.

💡 Exemplos

Para exemplos práticos e detalhados de uso da API, consulte:

📖 Guia Completo de Exemplos

Inclui:

📞 Fazer chamadas de voz e vídeo
🔍 Verificar status da conexão
🔐 Obter QR Code para autenticação
🧪 Scripts de teste
🎯 Casos de uso avançados

Exemplo rápido:

# Fazer uma chamada de voz
curl -X POST http://localhost:3000/api/call \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "5511999999999", "isVideo": false}'

📁 Estrutura do Projeto

whatsapp-call-api/
├── src/                        # Código fonte
│   ├── config/
│   │   └── baileys.js          # Configuração do Baileys e gestão do socket
│   ├── routes/
│   │   └── callRoutes.js       # Definição dos endpoints da API
│   ├── services/
│   │   └── callService.js      # Lógica de negócio das chamadas
│   └── index.js                # Entrada do servidor Express
│
├── examples/                   # Exemplos de uso
│   ├── call-examples.js        # Exemplos básicos
│   ├── advanced-call.js        # Exemplos avançados
│   └── webhook-handler.js      # Exemplo de webhook
│
├── auth_info_baileys/          # Sessão WhatsApp (não versionado)
│
├── .env.example                # Template de variáveis de ambiente
├── .gitignore                  # Arquivos ignorados pelo Git
├── CLAUDE.md                   # Documentação para AI assistants
├── Dockerfile                  # Configuração do container
├── docker-compose.yml          # Orquestração de containers
├── package.json                # Dependências e scripts
├── README.md                   # Este arquivo
└── test-api.sh                 # Script de teste da API

Principais Diretórios

src/: Todo o código fonte da aplicação
- config/: Configurações (Baileys, banco de dados futuro)
- routes/: Definição de rotas da API
- services/: Lógica de negócio
examples/: Exemplos práticos de uso da API
auth_info_baileys/: Credenciais da sessão (gerado automaticamente)

🛠️ Tecnologias

Principais Dependências

Tecnologia	Versão	Descrição
Node.js	20+	Runtime JavaScript
Express	4.18	Framework web minimalista
Baileys	6.7	Biblioteca WhatsApp Web API
Pino	8.19	Logger JSON de alta performance
QRCode	1.5	Geração de QR Codes
QRCode Terminal	0.12	QR Code no terminal

Dependências de Desenvolvimento

Nodemon 3.0 - Auto-reload durante desenvolvimento

Recursos do Node.js

✅ ES Modules: Uso nativo de import/export
✅ Async/Await: Código assíncrono moderno
✅ Top-level await: Suportado nativamente

🐛 Troubleshooting

Encontrou algum problema? Consulte nosso guia completo de solução de problemas:

🔧 Guia de Solução de Problemas

Soluções para:

❌ QR Code não aparece
❌ Erro "WhatsApp não está conectado"
❌ Porta 3000 já em uso
❌ Problemas com Docker
❌ Chamadas que não completam
📝 Logs e debugging detalhado

Dica rápida: Na maioria dos casos, limpar a sessão resolve:

rm -rf auth_info_baileys/
npm start

🤝 Contribuindo

Contribuições são bem-vindas! Siga os passos:

Fork o projeto
Crie uma branch para sua feature
```
git checkout -b feature/MinhaFeature
```

Commit suas mudanças

git commit -m '✨ Adiciona MinhaFeature'

Push para a branch
```
git push origin feature/MinhaFeature
```
Abra um Pull Request

Convenções

Use ES Modules (import/export)
Sempre inclua extensão .js nos imports
Use async/await (não .then())
Mensagens de commit em português
Siga o padrão do código existente

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

📞 Suporte

Encontrou um bug? Tem uma sugestão?

🐛 Abra uma issue
💬 Discussões

🙏 Agradecimentos

WhiskeySockets/Baileys - Pela excelente biblioteca
Comunidade Node.js e Express
Todos os contribuidores

⚠️ Disclaimer

Este projeto é para fins educacionais e de desenvolvimento. Use de forma responsável e de acordo com os Termos de Serviço do WhatsApp.

Não utilize para:

❌ Spam ou mensagens não solicitadas
❌ Violação de privacidade
❌ Atividades ilegais

O uso inadequado pode resultar no banimento da sua conta WhatsApp.

Desenvolvido com ❤️ usando Node.js e Baileys

⬆ Voltar ao topo

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
docs		docs
examples		examples
src		src
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
package.json		package.json
test-api.sh		test-api.sh

Folders and files

Latest commit

History

Repository files navigation

📞 WhatsApp Call API

⚡ Início Rápido

📋 Índice

📚 Documentação Adicional

🎯 Sobre o Projeto

Por que usar?

✨ Características

🔧 Pré-requisitos

Verificando versões

📦 Instalação

Opção 1: Instalação Local

Opção 2: Docker (Recomendado)

⚙️ Configuração

Variáveis de Ambiente

Autenticação WhatsApp

🚀 Uso

Iniciando o servidor

Verificando status

📚 Documentação da API

Base URL

🔌 Gerenciamento de Conexão

GET /api/status

GET /api/qr

📞 Operações de Chamada

POST /api/call

POST /api/call/reject

POST /api/call/terminate

GET /api/call/history

🐳 Docker

Executar com Docker Compose

Configuração Docker

Volume de Dados

💡 Exemplos

📖 Guia Completo de Exemplos

📁 Estrutura do Projeto

Principais Diretórios

🛠️ Tecnologias

Principais Dependências

Dependências de Desenvolvimento

Recursos do Node.js

🐛 Troubleshooting

🔧 Guia de Solução de Problemas

🤝 Contribuindo

Convenções

📄 Licença

📞 Suporte

🙏 Agradecimentos

⚠️ Disclaimer

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`GET /api/status`

`GET /api/qr`

`POST /api/call`

`POST /api/call/reject`

`POST /api/call/terminate`

`GET /api/call/history`