WhatsApp API Multi Device Version

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

GitHub
4.7k
Experimente este MCPPatrocinado

Documentação

GoWA Logo

Golang WhatsApp - Construído com Go para uso eficiente de memória

Patreon Se você está usando estas ferramentas para gerar renda, considere apoiar o desenvolvimento tornando-se um membro Patreon! Seu apoio ajuda a garantir que a biblioteca permaneça mantida e receba atualizações regulares!

release version Build Image Binary Release

Suporte para Arquitetura ARM & AMD juntamente com Suporte MCP

Download:

Suporte ao pacote n8n (n8n.io)

  • Pacote n8n
  • Vá para Configurações -> Community Nodes -> Insira @aldinokemal2104/n8n-nodes-gowa -> Instalar

Mudanças de Quebra

  • v6
    • Para o modo REST, você precisa executar <binary> rest em vez de <binary>
      • por exemplo: ./whatsapp rest em vez de ./whatsapp
      • Para o modo MCP, você precisa executar <binary> mcp
      • por exemplo: ./whatsapp mcp
  • v7
    • A partir da versão 7.x, estamos usando goreleaser para compilar o binário, então você pode baixar o binário do release
  • v8
    • Suporte a múltiplos dispositivos: Agora você pode conectar e gerenciar múltiplas contas WhatsApp simultaneamente em uma única instância do servidor
      • Nova API de Gerenciamento de Dispositivos: Novos endpoints sob /devices para gerenciar múltiplos dispositivos
      • Escopo de dispositivo obrigatório: Todas as chamadas REST da API 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 WebSocket: Conecte-se a /ws?device_id=<id> para definir o escopo do WebSocket para um dispositivo específico
      • Suporte a UI remota: CORS permite os cabeçalhos Authorization e X-Device-Id, então uma UI web independente (ex.: gowa-ui) hospedada em outra origem pode 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)
      • Mudanças 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:
      \`\`\`json
{
  "event": "message",
  "device_id": "628123456789@s.whatsapp.net",
  "payload": { ... }
}
\`\`\`
  • v9
    • MCP e API estão unificados sob rest: MCP não é mais um modo ou processo separado. Execute ./whatsapp rest para servir tanto a API REST quanto o MCP; MCP está disponível em /mcp (sem 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. Este servidor agora é um backend de API puro que baixa a versão mais recente do painel na inicialização, verifica seu hash sha256, 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

  • Enviar mensagem WhatsApp via API http, docs/openapi.yaml para mais detalhes
  • Suporte a Servidor MCP (Model Context Protocol) - Integre-se a agentes e ferramentas de IA usando protocolo padronizado
  • Mencionar alguém
    • @phoneNumber
      • exemplo: Hello @628974812XXXX, @628974812XXXX
  • Menções Fantasma (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 @ visível na mensagem
      • Use a palavra-chave especial @everyone para mencionar automaticamente TODOS os participantes do grupo
      • Caixa de seleção na UI disponível no modal Enviar Mensagem para grupos
  • Publicar Status do WhatsApp
  • Enviar Figurinhas - Converte automaticamente imagens para o formato de figurinha WebP
    • Suporta formatos JPG, JPEG, PNG, WebP e GIF
      • Redimensionamento automático para 512x512 pixels
      • Preserva transparência para imagens PNG
      • Figurinhas WebP animadas são suportadas, mas devem atender aos requisitos do WhatsApp:
      • Devem ter exatamente 512x512 pixels - Devem ter menos de 500KB de tamanho de arquivo - Duração máxima de 10 segundos - Se sua figurinha animada não atender a esses requisitos, redimensione-a antes de enviar usando ferramentas como ezgif.com
  • Comprimir imagem antes de enviar
  • Comprimir vídeo antes de enviar
  • Alterar o nome do SO para o seu aplicativo (é o nome do dispositivo ao conectar via celular)
    • --os=Chrome ou --os=MyApplication
  • Autenticação Básica (capaz de adicionar múltiplas credenciais)
    • --basic-auth=kemal:secret,toni:password,userName:secretPassword, ou você pode simplificar
      • -b=kemal:secret,toni:password,userName:secretPassword
  • Suporte a implantação em subcaminho
    • --base-path="/gowa" (permite implantação sob um caminho específico como /gowa/sub/path)
  • Porta personalizável e modo de depuração
    • --port 8000
      • --debug true
  • Resposta automática de mensagens
    • --autoreply="Don't reply this message"
  • Marcação automática de leitura de mensagens recebidas
    • --auto-mark-read=true (marca automaticamente mensagens recebidas como lidas)
  • Download automático de mídia de mensagens recebidas
    • --auto-download-media=false (desativa downloads automáticos de mídia, padrão: true)
  • Rejeição automática de 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 — marcar como online (suprime notificações do telefone)
      • unavailable — registrar pushname sem ficar online (padrão, preserva notificações do telefone)
      • none — pular presença completamente (pushname não será registrado, contatos podem ver "-" como 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
  • Webhook para mensagem recebida
  • Webhook por Dispositivo - Cada dispositivo pode ter sua própria URL de webhook
    • Definir via API: PATCH /devices/:device_id/webhook com {"webhook_url": "https://device-webhook.site/handler"}
      • Obter via API: GET /devices/:device_id/webhook
      • Quando um dispositivo tem um webhook personalizado, eventos para esse 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 como string vazia "" via PATCH para limpar e usar o webhook global
  • Segredo do Webhook Nosso webhook será enviado a você com um cabeçalho HMAC e uma chave padrão sha256 secret. Você pode modificar isso usando a opção abaixo:
    • --webhook-secret="secret"
  • Documentação do Payload do Webhook Para esquemas detalhados de payload de webhook, implementação de segurança e exemplos de integração, consulte Documentação do Payload do Webhook
  • Filtragem de Eventos do Webhook Você pode filtrar quais eventos são encaminhados para seu webhook usando:
    • --webhook-events="message,message.ack" (lista separada por vírgulas)
      • Ou variável de ambiente: WHATSAPP_WEBHOOK_EVENTS=message,message.ack Eventos de Webhook Disponíveis: | Evento | Descrição | | --- | --- | | message | Mensagens de texto, mídia, contato, localização | | message.reaction | Reações de emoji a mensagens | | message.revoked | Mensagens excluídas/revogadas | | message.edited | Mensagens editadas | | message.ack | Confirmações 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 não configurado (vazio), todos os eventos serão encaminhados.
  • Filtragem de JID do Webhook Você pode pular eventos para chats ou remetentes específicos (ex.: silenciar todos os grupos) antes de serem encaminhados:
    • --webhook-ignore-jids="@g.us,628123456789@s.whatsapp.net" (lista separada por vírgulas)
      • Ou variável de ambiente: WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us
      • Suporta os curingas @g.us / @s.whatsapp.net / @lid (correspondem a um espaço de endereço inteiro) e JIDs exatos.
      • Isso filtra por conversa/remetente e é independente de --webhook-events (que filtra por tipo de evento). A integração Chatwoot mantém seu próprio CHATWOOT_IGNORE_JIDS.
  • Configuração TLS do Webhook Se você encontrar erros de verificação de certificado TLS ao usar webhooks (ex.: 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 usando:
    • --webhook-insecure-skip-verify=true
      • Ou variável de ambiente: WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true Aviso de Segurança: Esta opção desativa a verificação de certificado TLS e deve ser usada apenas em:
    • Ambientes de desenvolvimento/teste
      • Túneis Cloudflare (que fornecem sua própria camada de segurança)
      • Redes internas com certificados autoassinados Para ambientes de produção, é fortemente recomendado usar certificados SSL adequados (ex.: Let's Encrypt) em vez de desativar a verificação.

Configuração

Você pode configurar o aplicativo usando flags de linha de comando (mostradas acima) ou variáveis de ambiente. A configuração pode ser definida de três maneiras (em ordem de prioridade):

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

Variáveis de Ambiente

Você pode configurar o aplicativo usando variáveis de ambiente. A configuração pode ser definida de três maneiras (em ordem de prioridade):

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

Para usar variáveis de ambiente:

  1. Copie .env.example para .env na raiz do seu projeto (cp src/.env.example src/.env)
  2. Modifique os valores em .env de acordo com suas necessidades
  3. Ou defina as mesmas variáveis como variáveis de ambiente do sistema

Variáveis de Ambiente Disponíveis

VariávelDescriçãoPadrãoExemplo
APP_PORTPorta da aplicação3000APP_PORT=8080
APP_HOSTEndereço do host para vincular o servidor0.0.0.0APP_HOST=127.0.0.1
APP_DEBUGAtivar registro de depuraçãofalseAPP_DEBUG=true
APP_OSNome do SO (nome do dispositivo no WhatsApp)GOWAAPP_OS=MyApp
APP_BASIC_AUTHCredenciais de autenticação básica-APP_BASIC_AUTH=user1:pass1,user2:pass2
APP_BASE_PATHCaminho base para implantação em subcaminho-APP_BASE_PATH=/gowa
APP_TRUSTED_PROXIESFaixas de IP de proxy confiável para proxy reverso-APP_TRUSTED_PROXIES=0.0.0.0/0
APP_CORS_ALLOWED_ORIGINSOrigens CORS permitidas (qualquer origem quando vazio)-APP_CORS_ALLOWED_ORIGINS=https://ui.example.com
DB_URIURI de conexão do banco de dadosfile:storages/whatsapp.dbDB_URI=postgres://user:pass@host/db
DB_KEYS_URIURI opcional do banco de dados para cache de criptografia/chave de 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_CONNSMáximo de conexões SQLite simultâneas para armazenamento de conversas5CHAT_STORAGE_MAX_OPEN_CONNS=10
WHATSAPP_AUTO_REPLYMensagem de resposta automática-WHATSAPP_AUTO_REPLY="Auto reply message"
WHATSAPP_AUTO_MARK_READMarcar automaticamente mensagens recebidas como lidasfalseWHATSAPP_AUTO_MARK_READ=true
WHATSAPP_AUTO_DOWNLOAD_MEDIABaixar automaticamente mídia de mensagens recebidastrueWHATSAPP_AUTO_DOWNLOAD_MEDIA=false
WHATSAPP_AUTO_REJECT_CALLRejeitar automaticamente chamadas recebidas do WhatsAppfalseWHATSAPP_AUTO_REJECT_CALL=true
WHATSAPP_WEBHOOKURL(s) de webhook para eventos (separados por vírgula)-WHATSAPP_WEBHOOK=https://webhook.site/xxx
WHATSAPP_WEBHOOK_SECRETSegredo do webhook para validaçãosecretWHATSAPP_WEBHOOK_SECRET=super-secret-key
WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFYIgnorar verificação TLS para webhooks (inseguro)falseWHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true
WHATSAPP_WEBHOOK_EVENTSLista de permissões de eventos para encaminhar (separados por vírgula, vazio = todos)-WHATSAPP_WEBHOOK_EVENTS=message,message.ack
WHATSAPP_WEBHOOK_IGNORE_JIDSJIDs/curingas para ignorar ao encaminhar (separados por vírgula)-WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us
WHATSAPP_ACCOUNT_VALIDATIONAtivar validação de contatrueWHATSAPP_ACCOUNT_VALIDATION=false
WHATSAPP_PRESENCE_ON_CONNECTPresença ao conectar: available, unavailable ou noneunavailableWHATSAPP_PRESENCE_ON_CONNECT=unavailable
WHATSAPP_PROXYProxy de saída para o WebSocket do WhatsApp (socks5/http/https)-WHATSAPP_PROXY=socks5://user:pass@host:1080
WHATSAPP_PRESENCE_PULSE_ENABLEDAtivar pulso diário de presença disponível/indisponíveltrueWHATSAPP_PRESENCE_PULSE_ENABLED=false
WHATSAPP_PRESENCE_PULSE_INTERVALIntervalo entre pulsos de presença24hWHATSAPP_PRESENCE_PULSE_INTERVAL=24h
WHATSAPP_PRESENCE_PULSE_DURATIONDuração para permanecer disponível durante cada pulso5mWHATSAPP_PRESENCE_PULSE_DURATION=5m
CHATWOOT_ENABLEDAtivar integração com ChatwootfalseCHATWOOT_ENABLED=true
CHATWOOT_URLURL da instância do Chatwoot-CHATWOOT_URL=https://app.chatwoot.com
CHATWOOT_API_TOKENToken de acesso da API do Chatwoot-CHATWOOT_API_TOKEN=your-api-token
CHATWOOT_ACCOUNT_IDID da conta do Chatwoot-CHATWOOT_ACCOUNT_ID=12345
CHATWOOT_INBOX_IDID da caixa de entrada do Chatwoot-CHATWOOT_INBOX_ID=67890
CHATWOOT_DEVICE_IDID do dispositivo WhatsApp para Chatwoot (dispositivo único / fallback de env)-CHATWOOT_DEVICE_ID=628xxx@s.whatsapp.net
CHATWOOT_ALLOWED_HOSTSLista 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_MESSAGESAtivar sincronização de histórico de mensagens para o ChatwootfalseCHATWOOT_IMPORT_MESSAGES=true
CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGESDias de histórico para importar3CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES=7
CHATWOOT_IMPORT_DB_URIURI 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_MESSAGEInserir espaços reservados de texto para linhas de mídia durante importação direta no bancotrueCHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE=true
CHATWOOT_IMPORT_MEDIA_WITH_RESTEnviar linhas de mídia de importação direta no banco via REST do ChatwootfalseCHATWOOT_IMPORT_MEDIA_WITH_REST=true
CHATWOOT_AUTO_CREATECriar automaticamente ou reutilizar a caixa de entrada da API do Chatwoot na inicializaçãofalseCHATWOOT_AUTO_CREATE=true
CHATWOOT_INBOX_NAMENome da caixa de entrada usado quando a criação automática está ativadaWhatsAppCHATWOOT_INBOX_NAME=WhatsApp Support
CHATWOOT_WEBHOOK_URLURL pública do webhook de resposta do GOWA Chatwoot-CHATWOOT_WEBHOOK_URL=https://api.example.com/chatwoot/webhook?secret=shared
CHATWOOT_WEBHOOK_SECRETSegredo compartilhado exigido para webhooks recebidos do Chatwoot-CHATWOOT_WEBHOOK_SECRET=shared
CHATWOOT_REOPEN_CONVERSATIONReabrir conversas resolvidas do Chatwoot para contatos que retornamtrueCHATWOOT_REOPEN_CONVERSATION=false
CHATWOOT_CONVERSATION_PENDINGCriar novas conversas do Chatwoot como pendentesfalseCHATWOOT_CONVERSATION_PENDING=true
CHATWOOT_IGNORE_JIDSJIDs ou curingas para excluir do encaminhamento do Chatwoot-CHATWOOT_IGNORE_JIDS=@g.us,628123@s.whatsapp.net
CHATWOOT_SIGN_MSGPrefixar respostas de agentes do Chatwoot com o nome do agentefalseCHATWOOT_SIGN_MSG=true
CHATWOOT_SIGN_DELIMITERDelimitador entre a assinatura do agente do Chatwoot e o corpo da mensagem\n\nCHATWOOT_SIGN_DELIMITER=" - "
CHATWOOT_FORWARD_EDITSEspelhar edições do WhatsApp em notas encadeadas do ChatwoottrueCHATWOOT_FORWARD_EDITS=false
CHATWOOT_FORWARD_DELETESEspelhar eventos de exclusão para todos do WhatsApp em notas do ChatwoottrueCHATWOOT_FORWARD_DELETES=false
CHATWOOT_MESSAGE_READSincronizar estado de leitura para mensagens vinculadas do WhatsApp/ChatwootfalseCHATWOOT_MESSAGE_READ=true
CHATWOOT_MESSAGE_DELETEExcluir mensagens vinculadas do lado oposto quando a exclusão for relatadafalseCHATWOOT_MESSAGE_DELETE=true

Documentação:

Nota: Os sinalizadores de linha de comando substituirão quaisquer valores definidos em variáveis de ambiente ou no arquivo .env.

  • Para mais comandos ./whatsapp --help

Requisitos

Requisitos do Sistema

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

Suporte de Plataforma

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

Dependências (sem docker)

  • Mac OS:
    • brew install ffmpeg webp
      • export CGO_CFLAGS_ALLOW="-Xpreprocessor"
  • Linux:
    • sudo apt update
      • sudo apt install ffmpeg webp
  • Windows (não recomendado, prefira usar WSL):

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

Como usar

Básico

  1. Clone este repositório: git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
  2. Abra a pasta clonada via cmd/terminal.
  3. execute cd src
  4. execute go run . rest (para modo REST API)
  5. Abra http://localhost:3000

Docker (você não precisa instalar os requisitos)

  1. Clone este repositório: git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
  2. Abra a pasta clonada via cmd/terminal.
  3. execute docker-compose up -d --build
  4. abra http://localhost:3000

Compile seu próprio binário

  1. Clone este repositório git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
  2. Abra a pasta clonada via cmd/terminal.
  3. execute cd src
  4. execute
    1. Linux e MacOS: go build -o whatsapp 2. Windows (CMD / PowerShell): go build -o whatsapp.exe
  5. execute
    1. Linux e MacOS: ./whatsapp rest (para modo REST API)
      1. execute ./whatsapp --help para mais detalhes de sinalizadores
      2. Windows: .\whatsapp.exe rest (para modo REST API)
      3. execute .\whatsapp.exe --help para mais detalhes de sinalizadores
  6. abra http://localhost:3000 no navegador

Compilação Cruzada para Raspberry Pi (ARM)

Se você quiser compilar para Raspberry Pi ou outros dispositivos ARM sem precisar de um toolchain C (CGO), você pode usar a tag de compilação purego. Isso usará uma implementação SQLite pura em Go.

  1. Clone este repositório git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
  2. Abra a pasta clonada via cmd/terminal.
  3. execute cd src
  4. Compile para Raspberry Pi Zero / 1 (ARMv6): 
    CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=6 go build -tags purego -o whatsapp-armv6
  5. 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
  6. Transfira o binário para o seu Pi, dê 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 streamable. Desative-o com MCP_ENABLED=false ou --mcp-enabled=false (padrão: ativado).

Ferramentas MCP Disponíveis

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

FerramentaValores de type / action
whatsapp_sendtext, image, video, audio, document, sticker, location, contact, poll, link, forward
whatsapp_messagereact, edit, revoke, delete, mark_read, star, unstar, download_media
whatsapp_chatlist_chats, list_contacts, get_messages, archive
whatsapp_groupcreate, 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_appstatus, login_qr, login_code, logout, reconnect

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 (usa o dispositivo padrão se omitido, igual ao REST). Qualquer chamada individual pode substituí-lo com um argumento opcional device_id.

Configuração MCP

Aponte seu cliente MCP para o endpoint /mcp. Ele herda a autenticação básica 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 básica estiver configurada, e X-Device-Id apenas para configurações com vários dispositivos.

Migrando do modo MCP autônomo

  • ./whatsapp mcp → ./whatsapp rest (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)

Modo de Produção REST (docker)

Usando Docker Hub:

docker run --detach --publish=3000:3000 --name=whatsapp --restart=always --volume=$(docker volume create --name=whatsapp):/app/storages aldinokemal2104/go-whatsapp-web-multidevice rest --autoreply="Dont't reply this message please"

Usando GitHub Container Registry:

docker run --detach --publish=3000:3000 --name=whatsapp --restart=always --volume=$(docker volume create --name=whatsapp):/app/storages ghcr.io/aldinokemal/go-whatsapp-web-multidevice rest --autoreply="Dont't reply this message please"

Modo de Produção REST (docker compose)

crie o arquivo docker-compose.yml com a seguinte configuração:

Usando Docker Hub:

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

volumes:
  whatsapp:

Usando GitHub Container Registry:

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

volumes:
  whatsapp:

ou com arquivo env (Docker Hub):

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

volumes:
  whatsapp:

ou com arquivo env (GitHub Container Registry):

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

volumes:
  whatsapp:

Modo de Produção (binário)

Você pode fazer fork ou editar este código-fonte!

API Atual

API MCP (Model Context Protocol)

  • Servida em /mcp pelo servidor REST (transporte HTTP streamable) 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 HTTP REST

  • Consulte docs/openapi.yaml para especificações detalhadas da API.
  • Use o SwaggerEditor para visualizar a API.
  • Gere clientes HTTP usando o openapi-generator. | Recurso | Menu | Método | URL | | --- | --- | --- | --- | | ✅ | Health Check | 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 | | ✅ | Login com QR Scan | GET | /app/login | | ✅ | Login com Código de Pareamento | GET | /app/login-with-code | | ✅ | Status do Pareamento Passkey | GET | /app/passkey | | ✅ | Resposta do Pareamento Passkey | POST | /app/passkey/response | | ✅ | Confirmar Pareamento Passkey | 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 App (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 PushName do Usuário | POST | /user/pushname | | ✅ | Meus Grupos do Usuário* | GET | /user/my/groups | | ✅ | Meus Newsletters do Usuário | GET | /user/my/newsletters | | ✅ | Minha Configuração de Privacidade do Usuário | GET | /user/my/privacy | | ✅ | Meus Contatos do Usuário | GET | /user/my/contacts | | ✅ | Verificação do Usuário | GET | /user/check | | ✅ | Perfil Comercial do Usuário | 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 Sticker | 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 | | ✅ | 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 (DM) | POST | /message/:message_id/read | | ✅ | Favoritar Mensagem | POST | /message/:message_id/star | | ✅ | Desfavoritar Mensagem | POST | /message/:message_id/unstar | | ✅ | Baixar Mídia da Mensagem | GET | /message/:message_id/download | | ✅ | Rejeitar Chamada | POST | /call/reject | | ✅ | Entrar em Grupo com Link | POST | /group/join-with-link | | ✅ | Informações do Grupo a partir do Link | GET | /group/info-from-link | | ✅ | 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 no Grupo | POST | /group/participants | | ✅ | Remover Participante do Grupo | POST | /group/participants/remove | | ✅ | Promover Participante no Grupo | POST | /group/participants/promote | | ✅ | Rebaixar Participante no Grupo | POST | /group/participants/demote | | ✅ | Exportar Participantes do Grupo (CSV) | GET | /group/participants/export | | ✅ | Listar Participantes Solicitados no Grupo | GET | /group/participant-requests | | ✅ | Aprovar Participante Solicitado no Grupo | POST | /group/participant-requests/approve | | ✅ | Rejeitar Participante Solicitado no Grupo | POST | /group/participant-requests/reject | | ✅ | Definir Foto do Grupo | POST | /group/photo | | ✅ | Definir Nome do Grupo | POST | /group/name | | ✅ | Definir Grupo como Bloqueado | POST | /group/locked | | ✅ | Definir 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 Newsletter | POST | /newsletter/unfollow | | ✅ | Obter Mensagens do Newsletter | GET | /newsletter/messages | | ✅ | 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 | | ✅ | Sincronizar Histórico do Chatwoot | POST | /chatwoot/sync | | ✅ | Status da Sincronização do Chatwoot | GET | /chatwoot/sync/status | | ✅ | Webhook de Resposta do Chatwoot | POST | /chatwoot/webhook |
✅ = Available
❌ = Not Available Yet
* = Has known limitations (see notes below)

Notas:

  • *User My Groups: Retorna no máximo 500 grupos devido à limitação do protocolo do WhatsApp. Isso é imposto pelos servidores do WhatsApp, não por esta API. 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

MCP UI

  • Configurar MCP (testado no cursor) Setup MCP
  • Testar MCP Test MCP
  • MCP configurado com sucesso Success MCP

Painel web (gowa-ui)

O painel vive em seu próprio repositório: aldinokemal/gowa-ui. Cada versão do gowa-ui publica um único gowa-ui.html autocontido; o servidor baixa a versão mais recente na inicialização (e a cada APP_UI_UPDATE_INTERVAL, padrão 3h), verifica seu digest sha256, armazena em cache em storages/ui/ e o serve em / atrás de autenticação básica.

ConfiguraçãoPadrãoFinalidade
APP_UI_ENABLEDtrueServir o painel em /; false retorna um banner JSON (somente API)
APP_UI_AUTO_UPDATEtrueBaixar/atualizar do GitHub; desative para implantações sem conexão com a internet
APP_UI_REPOaldinokemal/gowa-uiRepositório que o atualizador segue — sempre sua versão mais recente, não um pin de versão
APP_UI_ASSET_NAMEgowa-ui.htmlNome do arquivo do asset da versão a ser baixado
APP_UI_UPDATE_INTERVAL3hCom 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: recusar qualquer painel cujo sha256 seja diferente

Modelo de confiança: o digest da versão 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 versão inclui um asset .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 a versão mais recente desse repositório), ou pré-popular o cache e desativar a atualização automática completamente.

Servidores sem conexão com a internet: 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 (veja o readme do gowa-ui).

NOTA para Mac OS

  • Por favor, faça isso se você tiver um erro (invalid flag in pkg-config --cflags: -Xpreprocessor) export CGO_CFLAGS_ALLOW="-Xpreprocessor"

Importante

  • Este projeto não é oficial e não é afiliado ao WhatsApp.
  • Por favor, use a API oficial do WhatsApp para evitar quaisquer problemas.