Genfity WA

Genfity WA is an implementation of the @tulir/whatsmeow library as a simple RESTful API service with multiple device support and concurrent sessions.

Whatsmeow does not use Puppeteer on headless Chrome, nor an Android emulator. It communicates directly with WhatsApp’s WebSocket servers, making it significantly faster and much less demanding on memory and CPU than those solutions. The drawback is that any changes to the WhatsApp protocol could break connections, requiring a library update.

⚠️ Warning

Using this software in violation of WhatsApp’s Terms of Service can get your number banned: Be very careful—do not use this to send SPAM or anything similar. Use at your own risk. If you need to develop something for commercial purposes, contact a WhatsApp global solution provider and sign up for the WhatsApp Business API service instead.

Available endpoints

• Session: Connect, disconnect, and log out from WhatsApp. Retrieve connection status and QR codes for scanning.

• Messages: Send text, image, audio, document, template, video, sticker, location, contact, and poll messages.

• Users: Check if phone numbers have WhatsApp, get user information and avatars, and retrieve the full contact list.

• Chat: Set presence (typing/paused, recording media), mark messages as read, download images from messages, send reactions.

• Groups: Create, delete and list groups, get info, get invite links, set participants, change group photos and names.

• Webhooks: Set and get webhooks that will be called whenever events or messages are received.

• HMAC Configuration: Configure HMAC keys for webhook security and signature verification.

• History: Configure and retrieve message history storage for analytics, backup, and audit purposes.

🆕 New Features

📊 Message History Storage

Store and retrieve chat history in the database for:

• 📈 Analytics and reporting

• 🔍 Message search and retrieval

• 💾 Backup and audit trail

• 🤖 AI/Chatbot training data

• 📊 Business intelligence

Enable History Storage

Endpoint: POST /session/history

Request:

{
  "history": 500
}

Parameters:

• history: 0 = Disabled, 1-999999 = Maximum messages per chat (FIFO when limit reached)

Retrieve Message History

Endpoint: GET /chat/history?chat_jid={jid}&limit={limit}

Query Parameters:

• chat_jid (required): Chat JID or use index to get all chats mapping

• limit (optional): Number of messages to retrieve (default: 50)

Example Response:

[
  {
    "id": 1234,
    "user_id": "user_1",
    "chat_jid": "[email protected]",
    "sender_jid": "[email protected]",
    "message_id": "3EB0123456789ABCDEF",
    "timestamp": "2025-11-06T10:30:45Z",
    "message_type": "text",
    "text_content": "Hello world!",
    "media_link": "",
    "quoted_message_id": "",
    "datajson": "{...}"
  }
]

🔔 MessageSent Webhook (Custom Genfity Feature)

Automatically triggered when your application successfully sends a message. Subscribe to MessageSent event to receive notifications.

Webhook Payload:

{
  "type": "MessageSent",
  "event": {
    "Info": {
      "ID": "3EB0123456789ABCDEF",
      "Timestamp": "2025-11-06T10:30:45Z",
      "Chat": "[email protected]",
      "IsFromMe": true,
      "MessageType": "text"
    },
    "Message": {
      // Original message object
    }
  }
}

Message Types: text, image, video, audio, document, sticker, contact, location, buttons, list, poll

Triggered by all send endpoints:

• /chat/send/text

• /chat/send/image

• /chat/send/video

• /chat/send/audio

• /chat/send/document

• /chat/send/sticker

• /chat/send/contact

• /chat/send/location

• /chat/send/buttons

• /chat/send/list

• /chat/send/poll

🌐 URL Support for Images & Videos

Send images and videos directly from URLs without base64 encoding!

Supported Endpoints:

• POST /chat/send/image

• POST /chat/send/video

Example with URL:

{
  "Phone": "[email protected]",
  "Image": "https://example.com/image.jpg",
  "Caption": "Image from URL"
}

Example with Base64 (still supported):

{
  "Phone": "[email protected]",
  "Image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
  "Caption": "Image from Base64"
}

Features:

• ✅ SSRF Protection (only http/https allowed)

• ✅ Size limit validation (prevents DOS attacks)

• ✅ Auto MIME-type detection

• ✅ Backward compatible with Base64

📋 Webhook Events List

Endpoint: GET /webhook/events?active=true

Get comprehensive list of all supported webhook events (no authentication required).

Response:

{
  "active_events": [
    "Message", "MessageSent", "Receipt", "Connected",
    "Disconnected", "QR", "HistorySync", ...
  ],
  "all_supported_events": [...],
  "not_implemented_events": [...]
}

Active Events:

• Messages: Message, MessageSent, Receipt

• Connection: Connected, Disconnected, ConnectFailure, LoggedOut, StreamReplaced, PairSuccess, QR

• Privacy: PushNameSetting

• Sync: AppState, AppStateSyncComplete, HistorySync

• Calls: CallOffer, CallAccept, CallTerminate, CallOfferNotice, CallRelayLatency

• Presence: Presence, ChatPresence

• Special: All (subscribe to all events)

📱 WhatsApp Status Management

Endpoint: POST /status/set/text

Set your WhatsApp profile status message.

Request:

{
  "Body": "Available - Powered by Genfity WA"
}

🔗 Get User Linked ID (LID)

Endpoint: GET /user/lid/{jid}

Retrieve the Linked ID for a specific WhatsApp user.

Example:

GET /user/lid/[email protected]

Webhook HMAC Signing

When HMAC is configured, all webhooks include an x-hmac-signature header with SHA-256 HMAC signature.

Signature Generation by Content-Type:

application/json

• Signed data: Raw JSON request body

• Verification: Use the exact JSON received

application/x-www-form-urlencoded

• Signed data: URL-encoded form string (key=value&key2=value2)

• Verification: Reconstruct the form string from received parameters

multipart/form-data (file uploads)

• Signed data: JSON representation of form fields (excluding files)

• Verification: Create JSON from non-file form fields

• Always verify signatures before processing webhooks

Prerequisites

Required:

• Go (Go Programming Language)

Optional:

• Docker (for containerization)

Updating dependencies

This project uses the whatsmeow library to communicate with WhatsApp. To update the library to the latest version, run:

go get -u go.mau.fi/whatsmeow@latest
go mod tidy

Building

go build .

Run

By default it will start a REST service in port 8080. These are the parameters you can use to alter behaviour

• -admintoken : sets authentication token for admin endpoints. If not specified it will be read from .env

• -address : sets the IP address to bind the server to (default 0.0.0.0)

• -port : sets the port number (default 8080)

• -logtype : format for logs, either console (default) or json

• -color : enable colored output for console logs

• -osname : Connection OS Name in Whatsapp

• -skipmedia : Skip downloading media from messages

• -wadebug : enable whatsmeow debug, either INFO or DEBUG levels are suported

• -sslcertificate : SSL Certificate File

• -sslprivatekey : SSL Private Key File

Example:

To have colored logs:

./wuzapi -logtype=console -color=true

For JSON logs:

./wuzapi -logtype json 

With time zone:

Set TZ=America/New_York ./genfity-wa ... in your shell or in your .env file or Docker Compose environment: TZ=America/New_York.

Configuration

Genfity WA uses a .env file for configuration. You can use the provided .env.sample as a template:

cp .env.sample .env

Environment Variables

Required Settings

GENFITY_ADMIN_TOKEN=your_admin_token_here

Security Settings

GENFITY_GLOBAL_ENCRYPTION_KEY=your_32_byte_encryption_key_here
GENFITY_GLOBAL_HMAC_KEY=your_global_hmac_key_here

Optional Settings

TZ=America/New_York
WEBHOOK_FORMAT=json
SESSION_DEVICE_NAME=Genfity
GENFITY_PORT=8080
GENFITY_GLOBAL_WEBHOOK=https://your-global-webhook.url

Important Notes

Auto-Generated Credentials

If the following settings are not provided, they will be auto-generated:

• GENFITY_ADMIN_TOKEN: Random 32-character token

• GENFITY_GLOBAL_ENCRYPTION_KEY: Random 32-byte key for AES-256 encryption

Important: Save auto-generated credentials to your .env file or you will lose access to encrypted data and admin functions on restart!

Webhook Security

• GENFITY_GLOBAL_HMAC_KEY: Global HMAC key for webhook signing (minimum 32 characters)

Database Configuration

For PostgreSQL:

DB_USER=genfity
DB_PASSWORD=genfity
DB_NAME=genfity
DB_HOST=db  # Use 'db' when running with Docker Compose, or 'localhost' for native execution
DB_PORT=5432
DB_SSLMODE=false

For SQLite (default): No database configuration needed - SQLite is used by default if no PostgreSQL settings are provided.

Optional Settings

TZ=America/New_York
WEBHOOK_FORMAT=json # or "form" for the default
SESSION_DEVICE_NAME=Genfity
GENFITY_PORT=8080 # Port for the Genfity WA server
GENFITY_GLOBAL_WEBHOOK= # Global webhook URL for all instances

RabbitMQ Integration

Genfity WA supports sending WhatsApp events to a RabbitMQ queue for global event distribution. When enabled, all WhatsApp events will be published to the specified queue regardless of individual user webhook configurations.

Set these environment variables to enable RabbitMQ integration:

RABBITMQ_URL=amqp://guest:guest@localhost:5672
RABBITMQ_QUEUE=whatsapp  # Optional (default: whatsapp_events)

When enabled:

• All WhatsApp events (messages, presence updates, etc.) will be published to the configured queue regardless of event subscritions for regular webhooks

• Events will include the userId and instanceName

• This works alongside webhook configurations - events will be sent to both RabbitMQ and any configured webhooks

• The integration is global and affects all instances

Webhook Security with HMAC

Genfity WA supports HMAC signatures for webhook verification:

• Per-instance HMAC: Configure unique HMAC keys for each user instance

• Global HMAC: Set a global HMAC key via GENFITY_GLOBAL_HMAC_KEY environment variable

• Signature Header: All signed webhooks include x-hmac-signature header

• Key Security: HMAC keys are never exposed after configuration

Priority: Instance HMAC > Global HMAC > No signature

Configure HMAC keys via the Dashboard or using the /session/hmac/config API endpoints.

Key configuration options:

• GENFITY_ADMIN_TOKEN: Required - Authentication token for admin endpoints

• TZ: Optional - Timezone for server operations (default: UTC)

• PostgreSQL-specific options: Only required when using PostgreSQL backend

• RabbitMQ options: Optional, only required if you want to publish events to RabbitMQ

Docker Configuration

When using Docker Compose, docker-compose.yml automatically loads environment variables from a .env file when available. However, docker-compose-swarm.yaml uses docker stack deploy, which does not automatically load from .env files. Variables in the swarm file will only be substituted if they are exported in the shell environment where the deploy command is run. For managing secrets in Swarm, consider using Docker secrets.

The Docker configuration will:

1. First load variables from the .env file (if present and supported)

2. Use default values as fallback if variables are not defined

3. Override with any variables explicitly set in the environment section of the compose file

Key differences for Docker deployment:

• Set DB_HOST=db instead of localhost to connect to the PostgreSQL container

• The GENFITY_PORT variable controls the external port mapping in docker-compose.yml

• In swarm mode, GENFITY_PORT configures the Traefik load balancer port

Note: The .env file is already included in .gitignore to avoid committing sensitive information to your repository.

Usage

To interact with the API, you must include the Authorization header in HTTP requests, containing the user's authentication token. You can have multiple users (different WhatsApp numbers) on the same server.

• A Swagger API reference at /api

• A sample web page to connect and scan QR codes at /login

• A fully featured Dashboard to create, manage and test instances at /dashboard

ADMIN Actions

You can list, add and remove users using the admin endpoints. For that you must use the WUZAPI_ADMIN_TOKEN in the Authorization header

Then you can use the /admin/users endpoint with the Authorization header containing the token to:

• GET /admin/users - List all users

• POST /admin/users - Create a new user

• DELETE /admin/users/{id} - Remove a user

The JSON body for creating a new user must contain:

• name [string] : User's name

• token [string] : Security token to authorize/authenticate this user

• webhook [string] : URL to send events via POST (optional)

• events [string] : Comma-separated list of events to receive (required) - Valid events are: "Message", "ReadReceipt", "Presence", "HistorySync", "ChatPresence", "All"

• expiration [int] : Expiration timestamp (optional, not enforced by the system)

User Creation with Optional Proxy and S3 Configuration

You can create a user with optional proxy and S3 storage configuration. All fields are optional and backward compatible. If you do not provide these fields, the user will be created with default settings.

Example Payload

{
  "name": "test_user",
  "token": "user_token",
  "proxyConfig": {
    "enabled": true,
    "proxyURL": "socks5://user:pass@host:port"
  },
  "s3Config": {
    "enabled": true,
    "endpoint": "https://s3.amazonaws.com",
    "region": "us-east-1",
    "bucket": "my-bucket",
    "accessKey": "AKIAIOSFODNN7EXAMPLE",
    "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "pathStyle": false,
    "publicURL": "https://cdn.yoursite.com",
    "mediaDelivery": "both",
    "retentionDays": 30
  }
}

• proxyConfig (object, optional):

  • enabled (boolean): Enable proxy for this user.

  • proxyURL (string): Proxy URL (e.g., socks5://user:pass@host:port).

• s3Config (object, optional):

  • enabled (boolean): Enable S3 storage for this user.

  • endpoint (string): S3 endpoint URL.

  • region (string): S3 region.

  • bucket (string): S3 bucket name.

  • accessKey (string): S3 access key.

  • secretKey (string): S3 secret key.

  • pathStyle (boolean): Use path style addressing.

  • publicURL (string): Public URL for accessing files.

  • mediaDelivery (string): Media delivery type (base64, s3, or both).

  • retentionDays (integer): Number of days to retain files.

If you omit proxyConfig or s3Config, the user will be created without proxy or S3 integration, maintaining full backward compatibility.

API reference

API calls should be made with content type json, and parameters sent into the request body, always passing the Token header for authenticating the request.

Check the API Reference

Contributors

Nicolas	Guilherme Jansen	Luiz Felipe Neves	cleitonme	M. Yoga	Wellington Fonseca
xenodium	ramon-victor	Netrix Ken	Luiz Ricardo Gonçalves Felipe	andreydruz	Vitor Silva Lima
Ruan Kaylo	Pedro Afonso	Igor Trindade	Christopher Mendes	luiis716	João Victor Souza
Gustavo Salomé	Anton Kozyk	Anil Gulecha	Alan Martines	Ahmad Dwi Rizqi Hidayatulloh	elohmeier
Fadlul Alim	joaokopernico	Joseph Fernandes	renancesarti-cyber	Rubén Salazar	Ryan Achdiadsyah
ViFigueiredo	Ricardo Maminhak	zen

Clients

• wuzapi TypeScript / Node Client

Star History

License

Copyright © 2025 Nicolás Gudiño and contributors

MIT

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Icon Attribution

Communication icons created by Vectors Market - Flaticon

Legal

This code is in no way affiliated with, authorized, maintained, sponsored or endorsed by WhatsApp or any of its affiliates or subsidiaries. This is an independent and unofficial software. Use at your own risk.

Cryptography Notice

This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted. See http://www.wassenaar.org/ for more information.

The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software as Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performing cryptographic functions with asymmetric algorithms. The form and manner of this distribution makes it eligible for export under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS Export Administration Regulations, Section 740.13) for both object code and source code.