WhatsApp API Multi Device Version

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

GitHub
4.6k
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 seu desenvolvimento tornando-se membro do 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:

  • Release
  • Docker Hub
  • GitHub Container Registry

Suporte ao pacote n8n (n8n.io)

  • Pacote n8n
  • Vá para Configurações -> Nós da Comunidade -> Insira @aldinokemal2104/n8n-nodes-gowa -> Instalar

Mudanças de última hora

  • 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, usamos 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 do 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 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 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 versão e limites de tamanho de mídia. Como 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 and API are unified under rest: MCP is no longer a separate mode or process. Run./whatsapp rest to serve both the REST API and MCP; MCP is available at /mcp (no standalone mcpsubcommand). See MCP Server (Model Context Protocol) for migration details.
    • UI moved to a separate repository: The web dashboard is no longer bundled in this repo. It now lives at aldinokemal/gowa-ui and ships as a single self-containedgowa-ui.html. This server is now a pure API backend that downloads the latest dashboard release at startup, verifies its sha256 digest, caches it under storages/ui/, and serves it at /. See Web dashboard (gowa-ui) for the APP_UI_* settings, supply-chain pinning, and air-gapped deployment.

Feature

  • Send WhatsApp message via http API, docs/openapi.yaml for more details
  • MCP (Model Context Protocol) Server Support - Integrate with AI agents and tools using standardized protocol
  • Mention someone
    • @phoneNumber
    • example: Hello @628974812XXXX, @628974812XXXX
  • Ghost Mentions (Mention All) - Mention group participants without showing @phone in message text
    • Pass phone numbers in mentions field to mention users without visible @ in message
    • Use special keyword @everyone to automatically mention ALL group participants
    • UI checkbox available in Send Message modal for groups
  • Post Whatsapp Status
  • Send Stickers - Automatically converts images to WebP sticker format
    • Supports JPG, JPEG, PNG, WebP, and GIF formats
    • Automatic resizing to 512x512 pixels
    • Preserves transparency for PNG images
    • Animated WebP stickers are supported but must meet WhatsApp requirements:
      * Must be exactly 512x512 pixels
      * Must be under 500KB file size
      * Maximum 10 seconds duration
      * If your animated sticker doesn't meet these requirements, please resize it before uploading using tools like ezgif.com
  • Compress image before send
  • Compress video before send
  • Change OS name become your app (it's the device name when connect via mobile)
    • --os=Chrome or --os=MyApplication
  • Basic Auth (able to add multi credentials)
    • --basic-auth=kemal:secret,toni:password,userName:secretPassword, or you can simplify
    • -b=kemal:secret,toni:password,userName:secretPassword
  • Subpath deployment support
    • --base-path="/gowa" (allows deployment under a specific path like /gowa/sub/path)
  • Customizable port and debug mode
    • --port 8000
    • --debug true
  • Auto reply message
    • --autoreply="Don't reply this message"
  • Auto mark read incoming messages
    • --auto-mark-read=true (automatically marks incoming messages as read)
  • Auto download media from incoming messages
    • --auto-download-media=false (disable automatic media downloads, default: true)
  • Auto reject incoming calls
    • --auto-reject-call=true or WHATSAPP_AUTO_REJECT_CALL=true (see Webhook Payload for call events)
  • Configurable presence on connect
    • --presence-on-connect=unavailable or WHATSAPP_PRESENCE_ON_CONNECT=unavailable
    • available — mark as online (suppresses phone notifications)
    • unavailable — register pushname without going online (default, preserves phone notifications)
    • none — skip presence entirely (pushname won't be registered, contacts may see "-" as name)
  • Daily presence pulse
    • --presence-pulse-enabled=true or WHATSAPP_PRESENCE_PULSE_ENABLED=true (default: true)
    • --presence-pulse-interval=24h controls how often each connected device is pulsed
    • --presence-pulse-duration=5m controls how long the account stays available before returning to unavailable
  • Webhook for received message
    • --webhook="http://yourwebhook.site/handler", or you can simplify
    • -w="http://yourwebhook.site/handler"
    • for more detail, see Webhook Payload Documentation
  • Per-Device Webhook - Each device can have its own webhook URL
    • Set via API: PATCH /devices/:device_id/webhook with {"webhook_url": "https://device-webhook.site/handler"}
    • Get via API: GET /devices/:device_id/webhook
    • When a device has a custom webhook, events for that device are sent to the device-specific URL
    • When no device webhook is set, events fall back to the global webhook (--webhook)
    • Set to empty string "" via PATCH to clear and use global webhook
  • Webhook Secret Our webhook will be sent to you with an HMAC header and a sha256 default key secret.
    You may modify this by using the option below:
    • --webhook-secret="secret"
  • Webhook Payload DocumentationFor detailed webhook payload schemas, security implementation, and integration examples, see Webhook Payload Documentation
  • Webhook Event FilteringYou can filter which events are forwarded to your webhook using:
    • --webhook-events="message,message.ack" (comma-separated list)
    • Or environment variable: WHATSAPP_WEBHOOK_EVENTS=message,message.ack
      Available Webhook Events:
      | Event | Description |
      | ------------------ | --------------------------------------------- |
      | message | Text, media, contact, location messages |
      | message.reaction | Emoji reactions to messages |
      | message.revoked | Deleted/revoked messages |
      | message.edited | Edited messages |
      | message.ack | Delivery and read receipts |
      | message.deleted | Messages deleted for the user |
      | chat_presence | Typing and recording indicators from contacts |
      | group.participants | Group member join/leave/promote/demote events |
      | group.joined | You were added to a group |
      | label.edit | WhatsApp label metadata changed |
      | label.association | Label applied to or removed from a chat |
      | newsletter.joined | You subscribed to a newsletter/channel |
      | newsletter.left | You unsubscribed from a newsletter |
      | newsletter.message | New message(s) posted in a newsletter |
      | newsletter.mute | Newsletter mute setting changed |
      | call.offer | Incoming call received |
      If not configured (empty), all events will be forwarded.
  • Webhook JID Filtering
    You can skip events for specific chats or senders (e.g. mute all groups) before they are forwarded:
    • --webhook-ignore-jids="@g.us,628123456789@s.whatsapp.net" (comma-separated list)
    • Or environment variable: WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us
    • Supports the @g.us / @s.whatsapp.net / @lid wildcards (match a whole address space) and exact JIDs.
    • This filters by conversation/sender and is independent of --webhook-events (which filters by event type). The Chatwoot integration keeps its own CHATWOOT_IGNORE_JIDS.
  • Webhook TLS Configuration
    If you encounter TLS certificate verification errors when using webhooks (e.g., with Cloudflare tunnels or self-signed certificates):
tls: falha ao verificar certificado: x509: certificado assinado por autoridade desconhecida

You can disable TLS certificate verification using:

  • --webhook-insecure-skip-verify=true
  • Or environment variable: WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true
    Security Warning: This option disables TLS certificate verification and should only be used in:
  • Development/testing environments
  • Cloudflare tunnels (which provide their own security layer)
  • Internal networks with self-signed certificates
    For production environments, it's strongly recommended to use proper SSL certificates (e.g., Let's Encrypt) instead of disabling verification.

Configuration

You can configure the application using either command-line flags (shown above) or environment variables. Configuration can be set in three ways (in order of priority):

  1. Command-line flags (highest priority)
  2. Environment variables
  3. .env file (lowest priority)

Environment Variables

You can configure the application using environment variables. Configuration can be set in three ways (in order of priority):

To use environment variables:

  1. Copy .env.example to .env in your project root (cp src/.env.example src/.env)
  2. Modify the values in .env according to your needs
  3. Or set the same variables as system environment variables

Available Environment Variables

VariableDescriptionDefaultExample
APP_PORTApplication port3000APP_PORT=8080
APP_HOSTHost address to bind the server0.0.0.0APP_HOST=127.0.0.1
APP_DEBUGEnable debug loggingfalseAPP_DEBUG=true
APP_OSOS name (device name in WhatsApp)GOWAAPP_OS=MyApp
APP_BASIC_AUTHBasic authentication credentials-APP_BASIC_AUTH=user1:pass1,user2:pass2
APP_BASE_PATHBase path for subpath deployment-APP_BASE_PATH=/gowa
APP_TRUSTED_PROXIESTrusted proxy IP ranges for reverse proxy-APP_TRUSTED_PROXIES=0.0.0.0/0
APP_CORS_ALLOWED_ORIGINSAllowed CORS origins (any origin when empty)-APP_CORS_ALLOWED_ORIGINS=https://ui.example.com
DB_URIDatabase connection URIfile:storages/whatsapp.dbDB_URI=postgres://user:pass@host/db
DB_KEYS_URIOptional database URI for encryption/session key cache. Leave blank to use DB_URI; avoid in-memory storage in production because restarts can lose WhatsApp session state.-DB_KEYS_URI=file:storages/whatsapp-keys.db?_foreign_keys=on
CHAT_STORAGE_MAX_OPEN_CONNSMax concurrent SQLite connections for chat storage5CHAT_STORAGE_MAX_OPEN_CONNS=10
WHATSAPP_AUTO_REPLYAuto-reply message-WHATSAPP_AUTO_REPLY="Auto reply message"
WHATSAPP_AUTO_MARK_READAuto-mark incoming messages as readfalseWHATSAPP_AUTO_MARK_READ=true
WHATSAPP_AUTO_DOWNLOAD_MEDIAAuto-download media from incoming messagestrueWHATSAPP_AUTO_DOWNLOAD_MEDIA=false
WHATSAPP_AUTO_REJECT_CALLAuto-reject incoming WhatsApp callsfalseWHATSAPP_AUTO_REJECT_CALL=true
WHATSAPP_WEBHOOKWebhook URL(s) for events (comma-separated)-WHATSAPP_WEBHOOK=https://webhook.site/xxx
WHATSAPP_WEBHOOK_SECRETWebhook secret for validationsecretWHATSAPP_WEBHOOK_SECRET=super-secret-key
WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFYSkip TLS verification for webhooks (insecure)falseWHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true
WHATSAPP_WEBHOOK_EVENTSWhitelist of events to forward (comma-separated, empty = all)-WHATSAPP_WEBHOOK_EVENTS=message,message.ack
WHATSAPP_WEBHOOK_IGNORE_JIDSJIDs/wildcards to skip when forwarding (comma-separated)-WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us
WHATSAPP_ACCOUNT_VALIDATIONEnable account validationtrueWHATSAPP_ACCOUNT_VALIDATION=false
WHATSAPP_PRESENCE_ON_CONNECTPresence on connect: available, unavailable, or noneunavailableWHATSAPP_PRESENCE_ON_CONNECT=unavailable
WHATSAPP_PROXYOutbound proxy for the WhatsApp WebSocket (socks5/http/https)-WHATSAPP_PROXY=socks5://user:pass@host:1080
WHATSAPP_PRESENCE_PULSE_ENABLEDEnable daily available/unavailable presence pulsetrueWHATSAPP_PRESENCE_PULSE_ENABLED=false
WHATSAPP_PRESENCE_PULSE_INTERVALInterval between presence pulses24hWHATSAPP_PRESENCE_PULSE_INTERVAL=24h
WHATSAPP_PRESENCE_PULSE_DURATIONDuration to stay available during each pulse5mWHATSAPP_PRESENCE_PULSE_DURATION=5m
CHATWOOT_ENABLEDEnable Chatwoot integrationfalseCHATWOOT_ENABLED=true
CHATWOOT_URLChatwoot instance URL-CHATWOOT_URL=https://app.chatwoot.com
CHATWOOT_API_TOKENChatwoot API access token-CHATWOOT_API_TOKEN=your-api-token
CHATWOOT_ACCOUNT_IDChatwoot account ID-CHATWOOT_ACCOUNT_ID=12345
CHATWOOT_INBOX_IDChatwoot inbox ID-CHATWOOT_INBOX_ID=67890
CHATWOOT_DEVICE_IDWhatsApp device ID for Chatwoot (single-device / env fallback)-CHATWOOT_DEVICE_ID=628xxx@s.whatsapp.net
CHATWOOT_ALLOWED_HOSTSAllowlist of Chatwoot hosts for per-device configs (SSRF guard)-CHATWOOT_ALLOWED_HOSTS=app.chatwoot.com,chat.example.com
CHATWOOT_IMPORT_MESSAGESEnable message history sync to ChatwootfalseCHATWOOT_IMPORT_MESSAGES=true
CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGESDays of history to import3CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES=7
CHATWOOT_IMPORT_DB_URIDirect Chatwoot PostgreSQL URI for history sync-CHATWOOT_IMPORT_DB_URI=postgresql://user:pass@host:5432/chatwoot_production?sslmode=disable
CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGEInsert text placeholders for media rows during direct DB importtrueCHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE=true
CHATWOOT_IMPORT_MEDIA_WITH_RESTUpload direct-DB import media rows through Chatwoot RESTfalseCHATWOOT_IMPORT_MEDIA_WITH_REST=true
CHATWOOT_AUTO_CREATEAuto-create or reuse the Chatwoot API inbox at startupfalseCHATWOOT_AUTO_CREATE=true
CHATWOOT_INBOX_NAMEInbox name used when auto-create is enabledWhatsAppCHATWOOT_INBOX_NAME=WhatsApp Support
CHATWOOT_WEBHOOK_URLPublic GOWA Chatwoot reply webhook URL-CHATWOOT_WEBHOOK_URL=https://api.example.com/chatwoot/webhook?secret=shared
CHATWOOT_WEBHOOK_SECRETShared secret required for incoming Chatwoot webhooks-CHATWOOT_WEBHOOK_SECRET=shared
CHATWOOT_REOPEN_CONVERSATIONReopen resolved Chatwoot conversations for returning contactstrueCHATWOOT_REOPEN_CONVERSATION=false
CHATWOOT_CONVERSATION_PENDINGCreate new Chatwoot conversations as pendingfalseCHATWOOT_CONVERSATION_PENDING=true
CHATWOOT_IGNORE_JIDSJIDs or wildcards to exclude from Chatwoot forwarding-CHATWOOT_IGNORE_JIDS=@g.us,628123@s.whatsapp.net
CHATWOOT_SIGN_MSGPrefix Chatwoot agent replies with the agent namefalseCHATWOOT_SIGN_MSG=true
CHATWOOT_SIGN_DELIMITERDelimiter between Chatwoot agent signature and message body\n\nCHATWOOT_SIGN_DELIMITER=" - "
CHATWOOT_FORWARD_EDITSMirror WhatsApp edits into Chatwoot threaded notestrueCHATWOOT_FORWARD_EDITS=false
CHATWOOT_FORWARD_DELETESMirror WhatsApp delete-for-everyone events into Chatwoot notestrueCHATWOOT_FORWARD_DELETES=false
CHATWOOT_MESSAGE_READSync read state for linked WhatsApp/Chatwoot messagesfalseCHATWOOT_MESSAGE_READ=true
CHATWOOT_MESSAGE_DELETEDelete linked opposite-side messages when deletion is reportedfalseCHATWOOT_MESSAGE_DELETE=true

Documentation:

  • For detailed webhook payload schemas, security implementation, and integration examples, see Webhook Payload Documentation
  • For comprehensive Chatwoot integration guide, see Chatwoot Integration Documentation

Note: Command-line flags will override any values set in environment variables or .env file.

  • For more command ./whatsapp --help

Requirements

System Requirements

  • Go 1.25.5 or higher (for building from source)
  • FFmpeg (for media processing)

Platform Support

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

Dependencies (without docker)

  • Mac OS:
    • brew install ffmpeg webp
    • export CGO_CFLAGS_ALLOW="-Xpreprocessor"
  • Linux:
    • sudo apt update
    • sudo apt install ffmpeg webp
  • Windows (not recommended, prefer using WSL):
    • Install ffmpeg: download here
    • Install libwebp: download here (extract and add bin folder to PATH)
    • Add both to environment variable

Note: The webp package provides cwebp (encoder), dwebp (decoder), and webpmux (frame extractor) tools. FFmpeg is required for media processing. The libwebp tools (webpmux + dwebp) are used for animated WebP sticker support.

How to use

Basic

  1. Clone this repo: git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
  2. Open the folder that was cloned via cmd/terminal.
  3. run cd src
  4. run go run . rest (for REST API mode)
  5. Open http://localhost:3000

Docker (you don't need to install in required)

  1. Clone this repo: git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
  2. Open the folder that was cloned via cmd/terminal.
  3. run docker-compose up -d --build
  4. open http://localhost:3000

Build your own binary

  1. Clone this repo git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
  2. Open the folder that was cloned via cmd/terminal.
  3. run cd src
  4. run
    1. Linux & MacOS: go build -o whatsapp
    2. Windows (CMD / PowerShell): go build -o whatsapp.exe
  5. run
    1. Linux & MacOS: ./whatsapp rest (for REST API mode)
      1. run ./whatsapp --help for more detail flags
    2. Windows: .\whatsapp.exe rest (for REST API mode)
      1. run .\whatsapp.exe --help for more detail flags
  6. open http://localhost:3000 in browser

Cross-Compile for Raspberry Pi (ARM)

If you want to build for Raspberry Pi or other ARM devices without needing a C toolchain (CGO), you can use the purego build tag. This will use a pure-Go SQLite implementation.

  1. Clone this repo git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
  2. Open the folder that was cloned via cmd/terminal.
  3. run cd src
  4. Build for Raspberry Pi Zero / 1 (ARMv6):
    CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=6 go build -tags purego -o whatsapp-armv6
  5. Build for Raspberry Pi 2 / 3 / 4 (ARMv7 32-bit):
    CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build -tags purego -o whatsapp-armv7
  6. Transfer the binary to your Pi, give it execution permission (chmod +x), and run it:
    • If you built ARMv6: ./whatsapp-armv6 rest
    • If you built ARMv7: ./whatsapp-armv7 rest

MCP Server (Model Context Protocol)

MCP is not a separate mode or process — it's served by the REST server itself. Whenever ./whatsapp rest is running, the MCP endpoint is available at http://<host>:<port><base-path>/mcp (defaulthttp://localhost:3000/mcp) using the streamable HTTP transport. Disable it with MCP_ENABLED=false or--mcp-enabled=false (default: enabled).

Available MCP Tools

There are 5 consolidated tools; agents pick behavior via a type/action argument instead of one tool per operation:

Tooltype / action values
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

Device selection

For multi-device deployments, the X-Device-Id header on the MCP client connection selects the device used by every tool call on that connection (falls back to the default device if omitted, same as REST). Any individual call can override it with an optional device_id argument.

MCP Configuration

Point your MCP client at the /mcp endpoint. It inherits the REST server's basic auth, so include the sameAuthorization header your REST calls use:

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

headers is optional: include Authorization only when basic auth is configured, and X-Device-Id only for multi-device setups.

Migrating from the standalone MCP mode

  • ./whatsapp mcp → ./whatsapp rest (MCP is now included automatically)
  • http://localhost:8080/sse → http://localhost:3000/mcp
  • 40 granular tools → 5 consolidated tools (agents pick actions via the type/action field)

Production Mode REST (docker)

Using 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"

Using 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"

Production Mode REST (docker compose)

create docker-compose.yml file with the following configuration:

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:

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

or with env file (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

or with env file (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

Production Mode (binary)

  • download binary from release

You can fork or edit this source code !

Current API

MCP (Model Context Protocol) API

  • Served at /mcp by the REST server (streamable HTTP transport) whenever MCP_ENABLED is true; with APP_BASE_PATH set, the route is <base-path>/mcp.
  • Available tools are listed in the "Available MCP Tools" section above.
  • Compatible with MCP-enabled AI tools and agents

HTTP REST API

  • Check docs/openapi.yaml for detailed API specifications.
  • Use SwaggerEditor to visualize the API.
  • Generate HTTP clients using openapi-generator.
FeatureMenuMethodURL
✅Health CheckGET/health
✅List DevicesGET/devices
✅Add DevicePOST/devices
✅Get Device InfoGET/devices/:device_id
✅Remove DeviceDELETE/devices/:device_id
✅Login Device (QR)GET/devices/:device_id/login
✅Login Device (Code)POST/devices/:device_id/login/code
✅Logout DevicePOST/devices/:device_id/logout
✅Reconnect DevicePOST/devices/:device_id/reconnect
✅Get Device StatusGET/devices/:device_id/status
✅Get Device WebhookGET/devices/:device_id/webhook
✅Set Device WebhookPATCH/devices/:device_id/webhook
✅Login with Scan QRGET/app/login
✅Login With Pair CodeGET/app/login-with-code
✅Passkey Pairing StatusGET/app/passkey
✅Passkey Pairing ResponsePOST/app/passkey/response
✅Passkey Pairing ConfirmPOST/app/passkey/confirm
✅LogoutGET/app/logout
✅ReconnectGET/app/reconnect
✅DevicesGET/app/devices
✅Connection StatusGET/app/status
✅App Info (version, limits)GET/app/info
✅User InfoGET/user/info
✅User AvatarGET/user/avatar
✅User Change AvatarPOST/user/avatar
✅User Change PushNamePOST/user/pushname
✅User My Groups*GET/user/my/groups
✅User My NewsletterGET/user/my/newsletters
✅User My Privacy SettingGET/user/my/privacy
✅User My ContactsGET/user/my/contacts
✅User CheckGET/user/check
✅User Business ProfileGET/user/business-profile
✅Send MessagePOST/send/message
✅Send ImagePOST/send/image
✅Send AudioPOST/send/audio
✅Send FilePOST/send/file
✅Send VideoPOST/send/video
✅Send StickerPOST/send/sticker
✅Send ContactPOST/send/contact
✅Send LinkPOST/send/link
✅Send LocationPOST/send/location
✅Send Poll / VotePOST/send/poll
✅Send PresencePOST/send/presence
✅Send Chat Presence (Typing Indicator)POST/send/chat-presence
✅Revoke MessagePOST/message/:message_id/revoke
✅React MessagePOST/message/:message_id/reaction
✅Delete MessagePOST/message/:message_id/delete
✅Edit MessagePOST/message/:message_id/update
✅Read Message (DM)POST/message/:message_id/read
✅Star MessagePOST/message/:message_id/star
✅Unstar MessagePOST/message/:message_id/unstar
✅Download Message MediaGET/message/:message_id/download
✅Reject CallPOST/call/reject
✅Join Group With LinkPOST/group/join-with-link
✅Group Info From LinkGET/group/info-from-link
✅Group InfoGET/group/info
✅Leave GroupPOST/group/leave
✅Create GroupPOST/group
✅List Participants in GroupGET/group/participants
✅Add Participants in GroupPOST/group/participants
✅Remove Participant in GroupPOST/group/participants/remove
✅Promote Participant in GroupPOST/group/participants/promote
✅Demote Participant in GroupPOST/group/participants/demote
✅Export Group Participants (CSV)GET/group/participants/export
✅List Requested Participants in GroupGET/group/participant-requests
✅Approve Requested Participant in GroupPOST/group/participant-requests/approve
✅Reject Requested Participant in GroupPOST/group/participant-requests/reject
✅Set Group PhotoPOST/group/photo
✅Set Group NamePOST/group/name
✅Set Group LockedPOST/group/locked
✅Set Group AnnouncePOST/group/announce
✅Set Group TopicPOST/group/topic
✅Get Group Invite LinkGET/group/invite-link
✅Unfollow NewsletterPOST/newsletter/unfollow
✅Get Newsletter MessagesGET/newsletter/messages
✅Get Chat ListGET/chats
✅Get Chat MessagesGET/chat/:chat_jid/messages
✅Pin ChatPOST/chat/:chat_jid/pin
✅Archive ChatPOST/chat/:chat_jid/archive
✅Set Disappearing MessagesPOST/chat/:chat_jid/disappearing
✅Chatwoot Sync HistoryPOST/chatwoot/sync
✅Chatwoot Sync StatusGET/chatwoot/sync/status
✅Chatwoot Reply WebhookPOST/chatwoot/webhook
✅ = Disponível
❌ = Ainda não disponível
* = Tem limitações conhecidas (veja notas abaixo)

Notas:

  • *User My Groups: Retorna no máximo 500 grupos devido à limitação do protocolo 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

UI do MCP

  • Configurar MCP (testado no cursor)Setup MCP
  • Testar MCPTest MCP
  • MCP configurado com sucessoSuccess MCP

Painel web (gowa-ui)

O painel vive em seu próprio repositório: aldinokemal/gowa-ui. Cada release do gowa-ui publica um único gowa-ui.html autocontido; o servidor baixa o release mais recente na inicialização (e a cada APP_UI_UPDATE_INTERVAL, padrão 3h), verifica seu digest sha256, armazena em cache sob 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 isoladas
APP_UI_REPOaldinokemal/gowa-uiRepositório que o atualizador segue — sempre o release mais recente, sem fixar versão
APP_UI_ASSET_NAMEgowa-ui.htmlNome do arquivo do asset do release para baixar
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)Fixação da cadeia de suprimentos: recusar qualquer painel cujo sha256 difira

Modelo de confiança: o digest do release prova que o download corresponde ao que o GitHub anuncia, não quem o publicou. Operadores que auditam um build específico podem fixá-lo com APP_UI_ASSET_SHA256 (cada release inclui um asset .sha256 — esta é a única configuração que fixa um build exato), apontar APP_UI_REPO para um fork que controlam (o atualizador ainda rastreia o release mais recente desse repositório), ou pré-popular o cache e desativar 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 (veja o readme do gowa-ui).

NOTA para Mac OS

  • Por favor, faça isso se você tiver um erro (flag inválida em 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.