WhatsApp API Multi Device Version

Um servidor de API WhatsApp multi-dispositivo para agentes e ferramentas de IA.

Documentação

Go WhatsApp — Feito para Uso Eficiente de Memória

Se você está usando esta ferramenta para gerar renda, considere apoiar seu desenvolvimento tornando-se um membro Patreon!

Seu apoio ajuda a garantir que o projeto continue mantido e receba atualizações regulares!

Suporte a ARM, AMD64 e MCP

Download:

Nó da Comunidade n8n

Pacote n8n
Vá para Configurações → Nós da Comunidade, insira @aldinokemal2104/n8n-nodes-gowa e selecione Instalar.

Mudanças de Quebra

v6
- O modo REST requer <binary> rest em vez de <binary>.
  - Exemplo: ./whatsapp rest em vez de ./whatsapp.
  - O modo MCP exigia <binary> mcp.
  - Exemplo: ./whatsapp mcp.
v7
- A partir da versão 7.x, os binários são compilados com GoReleaser e podem ser baixados da última release.
v8
- Suporte a múltiplos dispositivos: Agora você pode conectar e gerenciar várias contas do WhatsApp simultaneamente em uma única instância do servidor.
  - Nova API de Gerenciamento de Dispositivos: Novos endpoints sob /devices gerenciam múltiplos dispositivos.
  - Escopo de dispositivo obrigatório: Todas as chamadas da API REST com escopo de dispositivo agora exigem:
  - Cabeçalho X-Device-Id, ou - Parâmetro de consulta device_id. - Se apenas um dispositivo estiver registrado, ele será usado como padrão.
  - Escopo de dispositivo via WebSocket: Conecte-se a /ws?device_id=<id> para definir o escopo da conexão WebSocket para um dispositivo específico.
  - Suporte a UI remota: O CORS permite os cabeçalhos Authorization e X-Device-Id, para que uma UI web independente (por exemplo, gowa-ui) hospedada em outra origem possa chamar a API diretamente. GET /app/info expõe a versão e os limites de tamanho de mídia. Como os navegadores não podem definir cabeçalhos em conexões WebSocket, passe /ws?device_id=<id>&authorization=<base64(user:pass)> quando a Autenticação Básica estiver habilitada (use TLS — a credencial fica visível na URL).
  - Alterações no payload do webhook: Todos os payloads de webhook agora incluem um campo device_id de nível superior identificando qual dispositivo recebeu o evento:
```
{
  "event": "message",
  "device_id": "628123456789@s.whatsapp.net",
  "payload": { ... }
}
```
v9
- MCP e API unificados sob rest: O MCP não é mais um modo ou processo separado. Execute ./whatsapp rest para servir tanto a API REST quanto o MCP; o MCP está disponível em /mcp (sem o subcomando mcp autônomo). Consulte Servidor MCP (Model Context Protocol) para detalhes de migração.
  - UI movida para um repositório separado: O painel web não está mais incluído neste repositório. Agora ele está em aldinokemal/gowa-ui e é distribuído como um único gowa-ui.html autocontido. O servidor baixa a versão mais recente do painel na inicialização, verifica seu digest SHA-256, armazena em cache sob storages/ui/ e o serve em /. Consulte Painel web (gowa-ui) para as configurações de APP_UI_*, fixação da cadeia de suprimentos e implantação em ambiente isolado.

Recursos

Envie mensagens do WhatsApp através da API HTTP. Consulte docs/openapi.yaml para detalhes.
Suporte a servidor MCP (Model Context Protocol) — Integre-se a agentes e ferramentas de IA usando um protocolo padronizado.
OAuth 2.1 MCP opcional — Conecte clientes MCP remotos que não podem fornecer um cabeçalho de Autenticação Básica. Consulte MCP OAuth.
Mencione usuários em texto de mensagens e legendas de imagens, vídeos ou arquivos:
- @phoneNumber
  - Exemplo: Hello @628974812XXXX, @628974812XXXX
Menções fantasmas (mencionar todos) — Mencione participantes do grupo sem mostrar @phone no texto da mensagem.
- Passe números de telefone no campo mentions para mencionar usuários sem um @ visível na mensagem.
  - Use a palavra-chave especial @everyone para mencionar automaticamente todos os participantes do grupo.
Publique atualizações de status do WhatsApp.
Marque mensagens de áudio recebidas e notas de voz como reproduzidas.
Envio agendado — Envie qualquer mensagem mais tarde, uma vez ou com repetição diária, semanal ou mensal.
- Adicione scheduled_at (RFC3339) e timezone (IANA) a uma solicitação de envio; recurrence, weekdays, day_of_month, end_at e occurrence_limit controlam as repetições.
  - Os agendamentos sobrevivem a reinicializações e aguardam um dispositivo offline; liste, pause, retome ou cancele-os em /send/schedules.
Enviar figurinhas — Converta automaticamente imagens para o formato de figurinha WebP.
- Suporta formatos JPG, JPEG, PNG, WebP e GIF.
  - Redimensiona automaticamente imagens para 512×512 pixels.
  - Preserva a transparência em imagens PNG.
  - Figurinhas WebP animadas são suportadas, mas devem atender aos requisitos do WhatsApp:
  - Exatamente 512×512 pixels. - Menos de 500 KB. - No máximo 10 segundos de duração. - Se uma figurinha animada não atender a esses requisitos, redimensione-a antes de enviar com uma ferramenta como ezgif.com.
Comprima imagens antes de enviar.
Comprima vídeos antes de enviar.
Personalize o nome do SO exibido como o nome do dispositivo vinculado no WhatsApp:
- --os=Chrome ou --os=MyApplication
Autenticação Básica com múltiplas credenciais:
- --basic-auth=kemal:secret,toni:password,userName:secretPassword
  - Forma curta: -b=kemal:secret,toni:password,userName:secretPassword
Suporte a implantação em subcaminho:
- --base-path="/gowa" permite implantação sob um caminho como /gowa.
Porta personalizável e modo de depuração:
- --port 8000
  - --debug true
Respostas automáticas a mensagens recebidas:
- --autoreply="Don't reply to this message"
Marcar automaticamente mensagens recebidas como lidas:
- --auto-mark-read=true
Baixar automaticamente mídia de mensagens recebidas:
- --auto-download-media=false desativa downloads automáticos de mídia (padrão: true).
Ignorar download de mídia de status:
- --ignore-status-media=true desativa o download de mídia de status (padrão: false).
Rejeitar automaticamente chamadas recebidas:
- --auto-reject-call=true ou WHATSAPP_AUTO_REJECT_CALL=true (consulte Payload do Webhook para eventos de chamada).
Presença configurável ao conectar:
- --presence-on-connect=unavailable ou WHATSAPP_PRESENCE_ON_CONNECT=unavailable
  - available — Marca a conta como online (suprime notificações do telefone).
  - unavailable — Registra o nome de push sem ficar online (padrão; preserva notificações do telefone).
  - none — Ignora a presença completamente (o nome de push não é registrado, então os contatos podem ver - como o nome).
Pulso diário de presença:
- --presence-pulse-enabled=true ou WHATSAPP_PRESENCE_PULSE_ENABLED=true (padrão: true).
  - --presence-pulse-interval=24h controla com que frequência cada dispositivo conectado recebe o pulso.
  - --presence-pulse-duration=5m controla por quanto tempo a conta permanece available antes de retornar a unavailable.
Webhooks para mensagens recebidas e outros eventos:
- --webhook="http://yourwebhook.site/handler"
  - Forma curta: -w="http://yourwebhook.site/handler"
  - Consulte Documentação do Payload do Webhook para detalhes.
Webhooks por dispositivo — Cada dispositivo pode ter sua própria URL de webhook e filtros de eventos.
- Defina via API: PATCH /devices/:device_id/webhook com {"webhook_url": "https://device-webhook.site/handler"}.
  - Obtenha via API: GET /devices/:device_id/webhook.
  - Quando um dispositivo tem um webhook personalizado, os eventos desse dispositivo são enviados para a URL específica do dispositivo.
  - Quando nenhum webhook de dispositivo é definido, os eventos voltam para o webhook global (--webhook).
  - Defina webhook_url como uma string vazia com PATCH para limpá-lo e usar o webhook global.
  - Defina WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true (ou --webhook-device-merge-global=true) para tornar um webhook de dispositivo uma adição em vez de uma substituição: as URLs globais --webhook ainda recebem os eventos do dispositivo (assinados com o segredo global, filtrados por WHATSAPP_WEBHOOK_EVENTS) enquanto a URL do dispositivo mantém seu próprio segredo e filtro de eventos.
Assinaturas de webhook — As solicitações de webhook incluem uma assinatura HMAC-SHA-256 no cabeçalho X-Hub-Signature-256, gerada com a chave padrão secret. Altere a chave com:
- --webhook-secret="secret"
Documentação do payload do webhook — Para esquemas detalhados, implementação de segurança e exemplos de integração, consulte Documentação do Payload do Webhook.
Filtragem de eventos de webhook — Filtre quais eventos são encaminhados para seu webhook com:
- --webhook-events="message,message.ack" (uma lista separada por vírgulas), ou
  - WHATSAPP_WEBHOOK_EVENTS=message,message.ack. Eventos de Webhook Disponíveis: | Evento | Descrição | | --- | --- | | message | Mensagens de texto, mídia, contato e localização | | message.reaction | Reações de emoji a mensagens | | message.revoked | Mensagens excluídas/revogadas | | message.edited | Mensagens editadas | | message.ack | Recibos de entrega e leitura | | message.deleted | Mensagens excluídas para o usuário | | chat_presence | Indicadores de digitação e gravação de contatos | | group.participants | Eventos de entrada/saída/promoção/rebaixamento de membros do grupo | | group.joined | Você foi adicionado a um grupo | | label.edit | Metadados de etiqueta do WhatsApp alterados | | label.association | Etiqueta aplicada ou removida de um chat | | newsletter.joined | Você se inscreveu em um boletim informativo/canal | | newsletter.left | Você cancelou a inscrição em um boletim informativo | | newsletter.message | Nova(s) mensagem(ns) publicada(s) em um boletim informativo | | newsletter.mute | Configuração de silenciamento do boletim informativo alterada | | call.offer | Chamada recebida | Se esta configuração estiver vazia, todos os eventos são encaminhados.
Filtragem de JID de webhook Você pode pular eventos para chats ou remetentes específicos (por exemplo, silenciar todos os grupos) antes que sejam encaminhados:
- --webhook-ignore-jids="@g.us,628123456789@s.whatsapp.net" (uma lista separada por vírgulas), ou
  - WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us.
  - Suporta os curingas @g.us / @s.whatsapp.net / @lid (correspondem a todo um espaço de endereço) e JIDs exatos.
  - Isso filtra por conversa ou remetente e é independente de --webhook-events, que filtra por tipo de evento. A integração Chatwoot tem uma configuração separada CHATWOOT_IGNORE_JIDS.
Configuração TLS de webhook Se você encontrar erros de verificação de certificado TLS ao usar webhooks (por exemplo, com túneis Cloudflare ou certificados autoassinados):
```
tls: failed to verify certificate: x509: certificate signed by unknown authority
```
Você pode desativar a verificação de certificado TLS com:
- --webhook-insecure-skip-verify=true, ou
  - WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true. Aviso de Segurança: Esta opção desativa a verificação de certificado TLS e só deve ser usada em:
- Ambientes de desenvolvimento ou teste.
  - Túneis Cloudflare, que fornecem sua própria camada de segurança.
  - Redes internas com certificados autoassinados. Para ambientes de produção, use um certificado TLS válido (por exemplo, do Let's Encrypt) em vez de desativar a verificação.

Configuração

A configuração é carregada nesta ordem de prioridade:

Flags de linha de comando (maior prioridade)
Variáveis de ambiente
Arquivo .env (menor prioridade)

Variáveis de Ambiente

Para usar variáveis de ambiente:

A partir da raiz do repositório, copie o arquivo de exemplo: cp src/.env.example src/.env.
Atualize os valores em src/.env conforme necessário.
Alternativamente, defina as mesmas variáveis no ambiente do processo.

Variáveis de Ambiente Disponíveis

Variável	Descrição	Padrão	Exemplo
`APP_PORT`	Porta da aplicação	`3000`	`APP_PORT=8080`
`APP_HOST`	Endereço do host para vincular o servidor	`0.0.0.0`	`APP_HOST=127.0.0.1`
`APP_DEBUG`	Ativar registro de depuração	`false`	`APP_DEBUG=true`
`APP_OS`	Nome do SO (nome do dispositivo no WhatsApp)	`GOWA`	`APP_OS=MyApp`
`APP_BASIC_AUTH`	Credenciais de autenticação básica	-	`APP_BASIC_AUTH=user1:pass1,user2:pass2`
`APP_BASE_PATH`	Caminho base para implantação em subcaminho	-	`APP_BASE_PATH=/gowa`
`APP_TRUSTED_PROXIES`	Faixas de IP de proxy confiável para proxy reverso	-	`APP_TRUSTED_PROXIES=0.0.0.0/0`
`APP_CORS_ALLOWED_ORIGINS`	Origens CORS permitidas (qualquer origem quando vazio)	-	`APP_CORS_ALLOWED_ORIGINS=https://ui.example.com`
`APP_UI_ENABLED`	Servir o painel gowa-ui baixado	`true`	`APP_UI_ENABLED=false`
`APP_UI_AUTO_UPDATE`	Baixar e atualizar periodicamente o painel mais recente	`true`	`APP_UI_AUTO_UPDATE=false`
`APP_UI_REPO`	Repositório GitHub contendo os lançamentos do gowa-ui	`aldinokemal/gowa-ui`	`APP_UI_REPO=my-org/gowa-ui`
`APP_UI_ASSET_NAME`	Nome do arquivo do ativo de lançamento do painel	`gowa-ui.html`	`APP_UI_ASSET_NAME=gowa-ui.html`
`APP_UI_UPDATE_INTERVAL`	Intervalo entre verificações de atualização do painel	`3h`	`APP_UI_UPDATE_INTERVAL=6h`
`APP_UI_GITHUB_TOKEN`	Token GitHub opcional para limite de taxa de API maior	-	`APP_UI_GITHUB_TOKEN=github_pat_xxx`
`APP_UI_ASSET_SHA256`	Pin SHA-256 opcional para o ativo do painel	-	`APP_UI_ASSET_SHA256=<hex-digest>`
`MCP_ENABLED`	Servir o endpoint MCP HTTP transmitível em `/mcp`	`true`	`MCP_ENABLED=false`
`MCP_OAUTH_ENABLED`	Ativar autenticação OAuth 2.1 para MCP	`false`	`MCP_OAUTH_ENABLED=true`
`MCP_OAUTH_ISSUER_URL`	URL pública do emissor HTTPS OAuth	-	`MCP_OAUTH_ISSUER_URL=https://gowa.example.com`
`MCP_OAUTH_RESOURCE_URL`	URL pública canônica opcional do MCP	Derivado do emissor e do caminho base	`MCP_OAUTH_RESOURCE_URL=https://gowa.example.com/mcp`
`MCP_OAUTH_DB_URI`	URI SQLite para clientes OAuth, códigos e hashes de token	`file:storages/oauth.db`	`MCP_OAUTH_DB_URI=file:storages/oauth.db`
`DB_URI`	URI de conexão do banco de dados	`file:storages/whatsapp.db`	`DB_URI=postgres://user:pass@host/db`
`DB_KEYS_URI`	URI de banco de dados opcional para cache de chave de criptografia/sessão. Deixe em branco para usar `DB_URI`; evite armazenamento em memória em produção porque reinicializações podem perder o estado da sessão do WhatsApp.	-	`DB_KEYS_URI=file:storages/whatsapp-keys.db?_foreign_keys=on`
`CHAT_STORAGE_MAX_OPEN_CONNS`	Máximo de conexões SQLite simultâneas para armazenamento de conversas	`5`	`CHAT_STORAGE_MAX_OPEN_CONNS=10`
`WHATSAPP_AUTO_REPLY`	Mensagem de resposta automática	-	`WHATSAPP_AUTO_REPLY="Auto reply message"`
`WHATSAPP_AUTO_MARK_READ`	Marcar automaticamente mensagens recebidas como lidas	`false`	`WHATSAPP_AUTO_MARK_READ=true`
`WHATSAPP_AUTO_DOWNLOAD_MEDIA`	Baixar automaticamente mídia de mensagens recebidas	`true`	`WHATSAPP_AUTO_DOWNLOAD_MEDIA=false`
`WHATSAPP_IGNORE_STATUS_MEDIA`	Ignorar download de mídia de status (status@broadcast)	`false`	`WHATSAPP_IGNORE_STATUS_MEDIA=true`
`WHATSAPP_AUTO_REJECT_CALL`	Rejeitar automaticamente chamadas recebidas do WhatsApp	`false`	`WHATSAPP_AUTO_REJECT_CALL=true`
`WHATSAPP_WEBHOOK`	URL(s) de webhook para eventos (separados por vírgula)	-	`WHATSAPP_WEBHOOK=https://webhook.site/xxx`
`WHATSAPP_WEBHOOK_SECRET`	Segredo do webhook para validação	`secret`	`WHATSAPP_WEBHOOK_SECRET=super-secret-key`
`WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY`	Ignorar verificação TLS para webhooks (inseguro)	`false`	`WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true`
`WHATSAPP_WEBHOOK_EVENTS`	Lista de permissões de eventos para encaminhar (separados por vírgula, vazio = todos)	-	`WHATSAPP_WEBHOOK_EVENTS=message,message.ack`
`WHATSAPP_WEBHOOK_IGNORE_JIDS`	JIDs/curingas para ignorar ao encaminhar (separados por vírgula)	-	`WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us`
`WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL`	Webhooks por dispositivo adicionam às URLs globais em vez de substituí-las	`false`	`WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true`
`WHATSAPP_ACCOUNT_VALIDATION`	Ativar validação de conta	`true`	`WHATSAPP_ACCOUNT_VALIDATION=false`
`WHATSAPP_PRESENCE_ON_CONNECT`	Presença ao conectar: `available`, `unavailable` ou `none`	`unavailable`	`WHATSAPP_PRESENCE_ON_CONNECT=unavailable`
`WHATSAPP_PROXY`	Proxy de saída para o WebSocket do WhatsApp (SOCKS5/HTTP/HTTPS)	-	`WHATSAPP_PROXY=socks5://user:pass@host:1080`
`WHATSAPP_PRESENCE_PULSE_ENABLED`	Ativar pulso diário de presença disponível/indisponível	`true`	`WHATSAPP_PRESENCE_PULSE_ENABLED=false`
`WHATSAPP_PRESENCE_PULSE_INTERVAL`	Intervalo entre pulsos de presença	`24h`	`WHATSAPP_PRESENCE_PULSE_INTERVAL=24h`
`WHATSAPP_PRESENCE_PULSE_DURATION`	Duração para permanecer disponível durante cada pulso	`5m`	`WHATSAPP_PRESENCE_PULSE_DURATION=5m`
`CHATWOOT_ENABLED`	Ativar integração com Chatwoot	`false`	`CHATWOOT_ENABLED=true`
`CHATWOOT_URL`	URL da instância do Chatwoot	-	`CHATWOOT_URL=https://app.chatwoot.com`
`CHATWOOT_API_TOKEN`	Token de acesso da API do Chatwoot	-	`CHATWOOT_API_TOKEN=your-api-token`
`CHATWOOT_ACCOUNT_ID`	ID da conta do Chatwoot	-	`CHATWOOT_ACCOUNT_ID=12345`
`CHATWOOT_INBOX_ID`	ID da caixa de entrada do Chatwoot	-	`CHATWOOT_INBOX_ID=67890`
`CHATWOOT_DEVICE_ID`	ID do dispositivo WhatsApp para Chatwoot (fallback de dispositivo único/ambiente)	-	`CHATWOOT_DEVICE_ID=628xxx@s.whatsapp.net`
`CHATWOOT_ALLOWED_HOSTS`	Lista de permissões de hosts do Chatwoot para configurações por dispositivo (proteção SSRF)	-	`CHATWOOT_ALLOWED_HOSTS=app.chatwoot.com,chat.example.com`
`CHATWOOT_IMPORT_MESSAGES`	Ativar sincronização do histórico de mensagens com o Chatwoot	`false`	`CHATWOOT_IMPORT_MESSAGES=true`
`CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES`	Dias de histórico para importar	`3`	`CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES=7`
`CHATWOOT_IMPORT_DB_URI`	URI PostgreSQL direto do Chatwoot para sincronização de histórico	-	`CHATWOOT_IMPORT_DB_URI=postgresql://user:pass@host:5432/chatwoot_production?sslmode=disable`
`CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE`	Inserir espaços reservados de texto para linhas de mídia durante importação direta no banco de dados	`true`	`CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE=true`
`CHATWOOT_IMPORT_MEDIA_WITH_REST`	Enviar linhas de mídia de importação direta no banco de dados via REST do Chatwoot	`false`	`CHATWOOT_IMPORT_MEDIA_WITH_REST=true`
`CHATWOOT_AUTO_CREATE`	Criar automaticamente ou reutilizar a caixa de entrada da API do Chatwoot na inicialização	`false`	`CHATWOOT_AUTO_CREATE=true`
`CHATWOOT_INBOX_NAME`	Nome da caixa de entrada usado quando a criação automática está ativada	`WhatsApp`	`CHATWOOT_INBOX_NAME=WhatsApp Support`
`CHATWOOT_WEBHOOK_URL`	URL pública do webhook de resposta do GOWA Chatwoot	-	`CHATWOOT_WEBHOOK_URL=https://api.example.com/chatwoot/webhook?secret=shared`
`CHATWOOT_WEBHOOK_SECRET`	Segredo compartilhado exigido para webhooks recebidos do Chatwoot	-	`CHATWOOT_WEBHOOK_SECRET=shared`
`CHATWOOT_REOPEN_CONVERSATION`	Reabrir conversas resolvidas do Chatwoot para contatos que retornam	`true`	`CHATWOOT_REOPEN_CONVERSATION=false`
`CHATWOOT_CONVERSATION_PENDING`	Criar novas conversas do Chatwoot como pendentes	`false`	`CHATWOOT_CONVERSATION_PENDING=true`
`CHATWOOT_IGNORE_JIDS`	JIDs ou curingas para excluir do encaminhamento do Chatwoot	-	`CHATWOOT_IGNORE_JIDS=@g.us,628123@s.whatsapp.net`
`CHATWOOT_SIGN_MSG`	Prefixar respostas de agentes do Chatwoot com o nome do agente	`false`	`CHATWOOT_SIGN_MSG=true`
`CHATWOOT_SIGN_DELIMITER`	Delimitador entre a assinatura do agente do Chatwoot e o corpo da mensagem	`\n\n`	`CHATWOOT_SIGN_DELIMITER=" - "`
`CHATWOOT_FORWARD_EDITS`	Espelhar edições do WhatsApp em notas encadeadas do Chatwoot	`true`	`CHATWOOT_FORWARD_EDITS=false`
`CHATWOOT_FORWARD_DELETES`	Espelhar eventos de exclusão para todos do WhatsApp em notas do Chatwoot	`true`	`CHATWOOT_FORWARD_DELETES=false`
`CHATWOOT_MESSAGE_READ`	Sincronizar estado de leitura para mensagens vinculadas do WhatsApp/Chatwoot	`false`	`CHATWOOT_MESSAGE_READ=true`
`CHATWOOT_MESSAGE_DELETE`	Excluir mensagens vinculadas do lado oposto quando a exclusão for relatada	`false`	`CHATWOOT_MESSAGE_DELETE=true`

Documentação:

Para esquemas detalhados de payload de webhook, implementação de segurança e exemplos de integração, consulte Documentação de Payload de Webhook.
Para o guia abrangente de integração com Chatwoot, consulte Documentação de Integração com Chatwoot.
Para detalhes de implantação e segurança OAuth, consulte MCP OAuth.

Execute ./whatsapp --help para ver todas as flags de linha de comando.

Requisitos

Requisitos do Sistema

Go 1.26.0 ou posterior (ao compilar a partir do código-fonte)
FFmpeg (para processamento de mídia)

Plataformas Suportadas

Linux (x86_64, ARM64)
macOS (Intel, Apple Silicon)
Windows (x86_64; WSL recomendado)

Dependências (sem Docker)

macOS:
- brew install ffmpeg webp
  - export CGO_CFLAGS_ALLOW="-Xpreprocessor"
Linux:
- sudo apt update
  - sudo apt install ffmpeg webp
Windows (WSL é recomendado; consulte Instalar WSL):
- Instale FFmpeg.
  - Instale libwebp, depois extraia e adicione o diretório bin ao PATH.

Nota: O pacote webp fornece as ferramentas cwebp (codificador), dwebp (decodificador) e webpmux (extrator de quadros). FFmpeg é necessário para processamento de mídia. As ferramentas libwebp (webpmux + dwebp) são usadas para suporte a adesivos WebP animados.

Como usar

Básico

Clone o repositório: git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice.
Abra o diretório clonado em um terminal.
Execute cd src.
Execute go run . rest.
Abra http://localhost:3000.

Docker

Docker evita a necessidade de instalar Go, FFmpeg e libwebp diretamente no host.

Clone o repositório: git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice.
Abra o diretório clonado em um terminal.
Copie o arquivo de ambiente: cp src/.env.example src/.env.
Execute docker compose up -d --build.
Abra http://localhost:3000.

Compilar seu próprio binário

Clone o repositório: git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice.
Abra o diretório clonado em um terminal.
Execute cd src.
Compile o binário:
- Linux e macOS: go build -o whatsapp
  - Windows (Prompt de Comando ou PowerShell): go build -o whatsapp.exe
Inicie o servidor:
- Linux e macOS: ./whatsapp rest
  - Windows: .\whatsapp.exe rest
Abra http://localhost:3000 em um navegador.

Execute ./whatsapp --help (ou .\whatsapp.exe --help no Windows) para ver todas as flags.

Compilação cruzada para Raspberry Pi (ARM)

Para compilar para um Raspberry Pi ou outro dispositivo ARM sem um toolchain C (CGO), use a tag de compilação purego. Isso seleciona uma implementação SQLite puramente em Go.

Clone o repositório: git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice.
Abra o diretório clonado em um terminal.
Execute cd src.

Compile para Raspberry Pi Zero / 1 (ARMv6):

CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=6 go build -tags purego -o whatsapp-armv6

Compile para Raspberry Pi 2 / 3 / 4 (ARMv7 32 bits):

CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build -tags purego -o whatsapp-armv7

Transfira o binário para seu Pi, conceda permissão de execução (chmod +x) e execute-o:
- Se você compilou ARMv6: ./whatsapp-armv6 rest
  - Se você compilou ARMv7: ./whatsapp-armv7 rest

Servidor MCP (Model Context Protocol)

MCP não é um modo ou processo separado — ele é servido pelo próprio servidor REST. Sempre que ./whatsapp rest estiver em execução, o endpoint MCP está disponível em http://<host>:<port><base-path>/mcp (padrão http://localhost:3000/mcp) usando o transporte HTTP transmitível. Desative-o com MCP_ENABLED=false ou --mcp-enabled=false (padrão: ativado).

Ferramentas MCP Disponíveis

Existem seis ferramentas consolidadas; os agentes escolhem o comportamento por meio de um argumento type / action em vez de uma ferramenta por operação:

Ferramenta	Valores de `type` / `action`
`whatsapp_send`	`text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `contact`, `poll`, `link`, `forward`
`whatsapp_schedule`	`list`, `get`, `pause`, `resume`, `cancel`
`whatsapp_message`	`react`, `edit`, `revoke`, `delete`, `mark_read`, `mark_played`, `star`, `unstar`, `download_media`
`whatsapp_chat`	`list_chats`, `list_contacts`, `get_messages`, `archive`
`whatsapp_group`	`create`, `join_with_link`, `leave`, `info`, `participants`, `add_participants`, `remove_participants`, `promote`, `demote`, `invite_link`, `set_name`, `set_topic`, `set_settings`, `join_requests`, `manage_join_requests`
`whatsapp_app`	`status`, `login_qr`, `login_code`, `logout`, `reconnect`

whatsapp_send também aceita scheduled_at, timezone, recurrence, weekdays, day_of_month, end_at e occurrence_limit para agendar a mensagem em vez de enviá-la agora; gerencie o resultado com whatsapp_schedule.

Seleção de dispositivo

Para implantações com vários dispositivos, o cabeçalho X-Device-Id na conexão do cliente MCP seleciona o dispositivo usado por cada chamada de ferramenta nessa conexão. Se omitido, ele volta para o dispositivo padrão, assim como no REST. Qualquer chamada individual pode substituí-lo com um argumento opcional device_id.

Configuração do MCP

Aponte seu cliente MCP para o endpoint /mcp. Ele herda a autenticação Basic Auth do servidor REST, então inclua o mesmo cabeçalho Authorization que suas chamadas REST usam:

{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Basic dXNlcjpzZWNyZXQ=",
        "X-Device-Id": "628123456789"
      }
    }
  }
}

headers é opcional: inclua Authorization apenas quando a autenticação Basic Auth estiver configurada, e X-Device-Id apenas para configurações com vários dispositivos.

OAuth para clientes MCP remotos

OAuth 2.1 está disponível para clientes remotos que não podem anexar um cabeçalho Basic Auth. Ele está desabilitado por padrão. Uma configuração mínima é:

APP_BASIC_AUTH=admin:replace-with-a-strong-password
MCP_ENABLED=true
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://gowa.example.com

Quando o OAuth está habilitado, /mcp aceita um token Bearer ou as credenciais Basic Auth configuradas. O OAuth não autentica rotas REST ou de interface. Consulte MCP OAuth para configuração do cliente, requisitos de proxy reverso, comportamento de subcaminho e o modelo de segurança.

Migrando do modo MCP autônomo

./whatsapp mcp → ./whatsapp rest (o MCP agora é incluído automaticamente).
http://localhost:8080/sse → http://localhost:3000/mcp.
40 ferramentas granulares → 5 ferramentas consolidadas (os agentes escolhem ações por meio do campo type / action).

Servidor REST de Produção (Docker)

Usando Docker Hub:

docker volume create whatsapp-storages
docker volume create whatsapp-statics
docker run --detach \
  --publish 3000:3000 \
  --name whatsapp \
  --restart always \
  --volume whatsapp-storages:/app/storages \
  --volume whatsapp-statics:/app/statics \
  aldinokemal2104/go-whatsapp-web-multidevice \
  rest --autoreply="Don't reply to this message, please"

Usando GitHub Container Registry:

docker volume create whatsapp-storages
docker volume create whatsapp-statics
docker run --detach \
  --publish 3000:3000 \
  --name whatsapp \
  --restart always \
  --volume whatsapp-storages:/app/storages \
  --volume whatsapp-statics:/app/statics \
  ghcr.io/aldinokemal/go-whatsapp-web-multidevice \
  rest --autoreply="Don't reply to this message, please"

Servidor REST de Produção (Docker Compose)

Crie um arquivo docker-compose.yml com uma das seguintes configurações.

Usando Docker Hub:

services:
  whatsapp:
    image: aldinokemal2104/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    command:
      - rest
      - --basic-auth=admin:admin
      - --port=3000
      - --debug=true
      - --os=Chrome
      - --account-validation=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Usando GitHub Container Registry:

services:
  whatsapp:
    image: ghcr.io/aldinokemal/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    command:
      - rest
      - --basic-auth=admin:admin
      - --port=3000
      - --debug=true
      - --os=Chrome
      - --account-validation=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Usando variáveis de ambiente com Docker Hub:

services:
  whatsapp:
    image: aldinokemal2104/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - WHATSAPP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Usando variáveis de ambiente com GitHub Container Registry:

services:
  whatsapp:
    image: ghcr.io/aldinokemal/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - WHATSAPP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Inicie a pilha selecionada com docker compose up -d.

Servidor de Produção (Binário)

Baixe um binário da página de lançamentos e execute-o com o subcomando rest.

Você também pode fazer um fork ou modificar o código-fonte.

API Atual

API MCP (Model Context Protocol)

Servida em /mcp pelo servidor REST usando HTTP transmissível sempre que MCP_ENABLED for verdadeiro. Com APP_BASE_PATH definido, a rota é <base-path>/mcp.
As ferramentas disponíveis estão listadas na seção "Ferramentas MCP Disponíveis" acima.
Compatível com ferramentas e agentes de IA habilitados para MCP.

API REST HTTP

Consulte docs/openapi.yaml para especificações detalhadas da API.
Use o Swagger Editor para visualizar a API.
Gere clientes HTTP usando openapi-generator.

Status	Operação	Método	URL
✅	Verificação de Saúde	GET	/health
✅	Listar Dispositivos	GET	/devices
✅	Adicionar Dispositivo	POST	/devices
✅	Obter Informações do Dispositivo	GET	/devices/:device_id
✅	Remover Dispositivo	DELETE	/devices/:device_id
✅	Login do Dispositivo (QR)	GET	/devices/:device_id/login
✅	Login do Dispositivo (Código)	POST	/devices/:device_id/login/code
✅	Logout do Dispositivo	POST	/devices/:device_id/logout
✅	Reconectar Dispositivo	POST	/devices/:device_id/reconnect
✅	Obter Status do Dispositivo	GET	/devices/:device_id/status
✅	Obter Webhook do Dispositivo	GET	/devices/:device_id/webhook
✅	Definir Webhook do Dispositivo	PATCH	/devices/:device_id/webhook
✅	Entrar com Código QR	GET	/app/login
✅	Entrar com Código de Pareamento	GET	/app/login-with-code
✅	Status do Pareamento por Chave de Acesso	GET	/app/passkey
✅	Resposta do Pareamento por Chave de Acesso	POST	/app/passkey/response
✅	Confirmar Pareamento por Chave de Acesso	POST	/app/passkey/confirm
✅	Logout	GET	/app/logout
✅	Reconectar	GET	/app/reconnect
✅	Dispositivos	GET	/app/devices
✅	Status da Conexão	GET	/app/status
✅	Informações do Aplicativo (versão, limites)	GET	/app/info
✅	Informações do Usuário	GET	/user/info
✅	Avatar do Usuário	GET	/user/avatar
✅	Alterar Avatar do Usuário	POST	/user/avatar
✅	Alterar Nome de Exibição do Usuário	POST	/user/pushname
✅	Listar Meus Grupos*	GET	/user/my/groups
✅	Listar Meus Boletins	GET	/user/my/newsletters
✅	Obter Minhas Configurações de Privacidade	GET	/user/my/privacy
✅	Listar Meus Contatos	GET	/user/my/contacts
✅	Verificar Usuário do WhatsApp	GET	/user/check
✅	Obter Perfil Comercial	GET	/user/business-profile
✅	Enviar Mensagem	POST	/send/message
✅	Enviar Imagem	POST	/send/image
✅	Enviar Áudio	POST	/send/audio
✅	Enviar Arquivo	POST	/send/file
✅	Enviar Vídeo	POST	/send/video
✅	Enviar Figurinha	POST	/send/sticker
✅	Enviar Contato	POST	/send/contact
✅	Enviar Link	POST	/send/link
✅	Enviar Localização	POST	/send/location
✅	Enviar Enquete / Votação	POST	/send/poll
✅	Enviar Presença	POST	/send/presence
✅	Enviar Presença no Chat (Indicador de Digitação)	POST	/send/chat-presence
✅	Listar Envios Agendados	GET	/send/schedules
✅	Obter Envio Agendado	GET	/send/schedules/:schedule_id
✅	Pausar Envio Agendado	POST	/send/schedules/:schedule_id/pause
✅	Retomar Envio Agendado	POST	/send/schedules/:schedule_id/resume
✅	Cancelar Envio Agendado	POST	/send/schedules/:schedule_id/cancel
✅	Revogar Mensagem	POST	/message/:message_id/revoke
✅	Reagir à Mensagem	POST	/message/:message_id/reaction
✅	Excluir Mensagem	POST	/message/:message_id/delete
✅	Editar Mensagem	POST	/message/:message_id/update
✅	Marcar Mensagem como Lida	POST	/message/:message_id/read
✅	Marcar Mensagem de Áudio como Reproduzida	POST	/message/:message_id/played
✅	Favoritar Mensagem	POST	/message/:message_id/star
✅	Desfavoritar Mensagem	POST	/message/:message_id/unstar
✅	Encaminhar Mensagem	POST	/message/:message_id/forward
✅	Baixar Mídia da Mensagem	GET	/message/:message_id/download
✅	Rejeitar Chamada	POST	/call/reject
✅	Entrar no Grupo com Link	POST	/group/join-with-link
✅	Obter Informações do Grupo pelo Link	GET	/group/info-from-link
✅	Obter Informações do Grupo	GET	/group/info
✅	Sair do Grupo	POST	/group/leave
✅	Criar Grupo	POST	/group
✅	Listar Participantes do Grupo	GET	/group/participants
✅	Adicionar Participantes ao Grupo	POST	/group/participants
✅	Remover Participantes do Grupo	POST	/group/participants/remove
✅	Promover Participantes do Grupo	POST	/group/participants/promote
✅	Rebaixar Participantes do Grupo	POST	/group/participants/demote
✅	Exportar Participantes do Grupo (CSV)	GET	/group/participants/export
✅	Listar Solicitações de Entrada no Grupo	GET	/group/participant-requests
✅	Aprovar Solicitações de Entrada no Grupo	POST	/group/participant-requests/approve
✅	Rejeitar Solicitações de Entrada no Grupo	POST	/group/participant-requests/reject
✅	Definir Foto do Grupo	POST	/group/photo
✅	Definir Nome do Grupo	POST	/group/name
✅	Bloquear ou Desbloquear Configurações do Grupo	POST	/group/locked
✅	Definir Modo de Anúncio do Grupo	POST	/group/announce
✅	Definir Tópico do Grupo	POST	/group/topic
✅	Obter Link de Convite do Grupo	GET	/group/invite-link
✅	Deixar de Seguir Boletim	POST	/newsletter/unfollow
✅	Obter Mensagens do Boletim	GET	/newsletter/messages
✅	Baixar Mídia de Mensagem do Boletim	GET	/newsletter/messages/{server_id}/download
✅	Obter Lista de Chats	GET	/chats
✅	Obter Mensagens do Chat	GET	/chat/:chat_jid/messages
✅	Fixar Chat	POST	/chat/:chat_jid/pin
✅	Arquivar Chat	POST	/chat/:chat_jid/archive
✅	Definir Mensagens que Desaparecem	POST	/chat/:chat_jid/disappearing
✅	Solicitar Histórico do Chat (Carregar Mensagens Antigas)	POST	/chat/:chat_jid/history
✅	Sincronizar Histórico do Chatwoot	POST	/chatwoot/sync
✅	Status da Sincronização do Chatwoot	GET	/chatwoot/sync/status
✅	Listar Configurações do Chatwoot	GET	/chatwoot/configs
✅	Obter Configuração do Chatwoot do Dispositivo	GET	/devices/:device_id/chatwoot/config
✅	Definir Configuração do Chatwoot do Dispositivo	PUT	/devices/:device_id/chatwoot/config
✅	Excluir Configuração do Chatwoot do Dispositivo	DELETE	/devices/:device_id/chatwoot/config
✅	Webhook de Resposta do Chatwoot	POST	/chatwoot/webhook
✅	Webhook de Resposta do Chatwoot do Dispositivo	POST	/chatwoot/webhook/:device_id

✅ = disponível. * = tem limitações conhecidas; consulte as notas abaixo.

Notas:

*List My Groups: Retorna no máximo 500 grupos devido a uma limitação do protocolo do WhatsApp. Os servidores do WhatsApp, não esta API, impõem o limite. Consulte a fonte do whatsmeow para detalhes.
/health é público e sempre registrado no caminho raiz, mesmo quando APP_BASE_PATH está definido.
As rotas do Chatwoot são registradas apenas quando CHATWOOT_ENABLED=true.

Interface do Usuário

Interface MCP

Configurar MCP (testado no Cursor)
Testar MCP
Configuração MCP bem-sucedida

Painel web (gowa-ui)

O painel está em seu próprio repositório: aldinokemal/gowa-ui. Cada lançamento do gowa-ui publica um único gowa-ui.html autocontido; o servidor baixa o lançamento mais recente na inicialização (e a cada APP_UI_UPDATE_INTERVAL, que por padrão é 3h), verifica seu digest SHA-256, armazena em cache em storages/ui/ e o serve em / atrás da autenticação Basic Auth.

Configuração	Padrão	Finalidade
`APP_UI_ENABLED`	`true`	Servir o painel em `/`; `false` retorna um banner JSON (somente API)
`APP_UI_AUTO_UPDATE`	`true`	Baixar/atualizar do GitHub; desative para implantações isoladas
`APP_UI_REPO`	`aldinokemal/gowa-ui`	Repositório que o atualizador segue—sempre seu lançamento mais recente, não um pin de versão
`APP_UI_ASSET_NAME`	`gowa-ui.html`	Nome do arquivo do ativo do lançamento para baixar
`APP_UI_UPDATE_INTERVAL`	`3h`	Com que frequência verificar `releases/latest`
`APP_UI_GITHUB_TOKEN`	(vazio)	Token opcional para aumentar o limite de taxa da API do GitHub
`APP_UI_ASSET_SHA256`	(vazio)	Pin da cadeia de suprimentos: recusa qualquer painel cujo SHA-256 seja diferente

Modelo de confiança: o digest do lançamento prova que o download corresponde ao que o GitHub anuncia, não quem o publicou. Operadores que auditam uma compilação específica podem fixá-la com APP_UI_ASSET_SHA256 (cada lançamento inclui um ativo .sha256—esta é a única configuração que fixa uma compilação exata), apontar APP_UI_REPO para um fork que controlam (o atualizador ainda rastreia o lançamento mais recente desse repositório) ou pré-popular o cache e desabilitar a atualização automática completamente.

Servidores isolados: coloque um gowa-ui.html baixado em storages/ui/index.html e defina APP_UI_AUTO_UPDATE=false. O painel também pode ser auto-hospedado em qualquer lugar estático e apontado para a URL deste servidor (consulte o README do gowa-ui).

Nota para macOS

Se você vir invalid flag in pkg-config --cflags: -Xpreprocessor, execute:

export CGO_CFLAGS_ALLOW="-Xpreprocessor"

Importante

Este projeto não é oficial e não tem afiliação com o WhatsApp.
Use a Plataforma Oficial de Negócios do WhatsApp quando precisar de uma integração suportada e pronta para produção.