Golang WhatsApp - Built with Go for efficient memory use

If you're using this tools to generate income, consider supporting its development by becoming a Patreon member! Your support helps ensure the library stays maintained and receives regular updates!

Download:

• Release
• Docker Hub
• GitHub Container Registry

• n8n package
• Go to Settings -> Community Nodes -> Input @aldinokemal2104/n8n-nodes-gowa -> Install

• v6
  • For REST mode, you need to run <binary> rest instead of <binary>
    • for example: ./whatsapp rest instead of ./whatsapp
  • For MCP mode, you need to run <binary> mcp
    • for example: ./whatsapp mcp
• v7
  • Starting version 7.x we are using goreleaser to build the binary, so you can download the binary from release
• v8

  • Multi-device support: You can now connect and manage multiple WhatsApp accounts simultaneously in a single server instance

  • New Device Management API: New endpoints under /devices for managing multiple devices

  • Device scoping required: All device-scoped REST API calls now require either:

    • X-Device-Id header, or
    • device_id query parameter
    • If only one device is registered, it will be used as the default

  • WebSocket device scoping: Connect to /ws?device_id=<id> to scope WebSocket to a specific device

  • Webhook payload changes: All webhook payloads now include a top-level device_id field identifying which device received the event:

    {
      "event": "message",
      "device_id": "628123456789@s.whatsapp.net",
      "payload": { ... }
    }

• Send WhatsApp message via http API, docs/openapi.yml 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

• 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

• 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)

• 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

• 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 Documentation For detailed webhook payload schemas, security implementation, and integration examples, see Webhook Payload Documentation

• Webhook TLS Configuration

  If you encounter TLS certificate verification errors when using webhooks (e.g., with Cloudflare tunnels or self-signed certificates):

  tls: failed to verify certificate: x509: certificate signed by unknown authority
  

  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.

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)

You can configure the application using 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)

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

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

• For more command ./whatsapp --help

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

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

• Mac OS:
  • brew install ffmpeg
  • export CGO_CFLAGS_ALLOW="-Xpreprocessor"
• Linux:
  • sudo apt update
  • sudo apt install ffmpeg
• Windows (not recomended, prefer using WSL):
  • install ffmpeg, download here
  • add to ffmpeg to environment variable

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

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

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

This application can also run as an MCP server, allowing AI agents and tools to interact with WhatsApp through a standardized protocol.

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 . mcp or build the binary and run ./whatsapp mcp
5. The MCP server will start on http://localhost:8080 by default

• --host localhost - Set the host for MCP server (default: localhost)
• --port 8080 - Set the port for MCP server (default: 8080)

The WhatsApp MCP server provides comprehensive tools for AI agents to interact with WhatsApp through a standardized protocol. Below is the complete list of available tools:

• whatsapp_connection_status - Check whether the WhatsApp client is connected and logged in
• whatsapp_login_qr - Initiate QR code based login flow with image output
• whatsapp_login_with_code - Generate pairing code for multi-device login using phone number
• whatsapp_logout - Sign out the current WhatsApp session
• whatsapp_reconnect - Attempt to reconnect to WhatsApp using stored session

• whatsapp_send_text - Send text messages with reply and forwarding support
• whatsapp_send_contact - Send contact cards with name and phone number
• whatsapp_send_link - Send links with custom captions
• whatsapp_send_location - Send location coordinates (latitude/longitude)
• whatsapp_send_image - Send images with captions, compression, and view-once options
• whatsapp_send_sticker - Send stickers with automatic WebP conversion (supports JPG/PNG/GIF)

• whatsapp_list_contacts - Retrieve all contacts in your WhatsApp account
• whatsapp_list_chats - Get recent chats with pagination and search filters
• whatsapp_get_chat_messages - Fetch messages from specific chats with time/media filtering
• whatsapp_download_message_media - Download images/videos from messages

• whatsapp_group_create - Create new groups with optional initial participants
• whatsapp_group_join_via_link - Join groups using invite links
• whatsapp_group_leave - Leave groups by group ID
• whatsapp_group_participants - List all participants in a group
• whatsapp_group_manage_participants - Add, remove, promote, or demote group members
• whatsapp_group_invite_link - Get or reset group invite links
• whatsapp_group_info - Get detailed group information
• whatsapp_group_set_name - Update group display name
• whatsapp_group_set_topic - Update group description/topic
• whatsapp_group_set_locked - Toggle admin-only group info editing
• whatsapp_group_set_announce - Toggle announcement-only mode
• whatsapp_group_join_requests - List pending join requests
• whatsapp_group_manage_join_requests - Approve or reject join requests

• SSE endpoint: http://localhost:8080/sse
• Message endpoint: http://localhost:8080/message

Make sure you have the MCP server running: ./whatsapp mcp

For AI tools that support MCP with SSE (like Cursor), add this configuration:

{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:8080/sse"
    }
  }
}

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"

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

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

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

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
      - APP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp:

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
      - APP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp:

• download binary from release

You can fork or edit this source code !

• MCP server provides standardized tools for AI agents to interact with WhatsApp
• Supports Server-Sent Events (SSE) transport
• Available tools: whatsapp_send_text, whatsapp_send_contact, whatsapp_send_link, whatsapp_send_location
• Compatible with MCP-enabled AI tools and agents

• API Specification Document.
• Check docs/openapi.yml for detailed API specifications.
• Use SwaggerEditor to visualize the API.
• Generate HTTP clients using openapi-generator.

✅ = Available
❌ = Not Available Yet

• Setup MCP (tested in cursor)
• Test MCP
• Successfully setup MCP

Description	Image
Homepage
Login
Login With Code
Send Message
Send Image
Send File
Send Video
Send Sticker
Send Contact
Send Location
Send Audio
Send Poll
Send Presence
Send Link
My Group
Group Info From Link
Create Group
Join Group with Link
Manage Participant
My Newsletter
My Contacts
Business Profile

• Please do this if you have an error (invalid flag in pkg-config --cflags: -Xpreprocessor) export CGO_CFLAGS_ALLOW="-Xpreprocessor"

• This project is unofficial and not affiliated with WhatsApp.
• Please use official WhatsApp API to avoid any issues.
• We only able to run MCP or REST API, this is limitation from whatsmeow library. independent MCP will be available in the future.