Whatsmeow WhatsApp Connector
Send and receive WhatsApp via self-hosted whatsmeow gateways — no Cloud API, no template approval, no 24-hour session window.
Own your WhatsApp channel.
End to end.
Whatsmeow WhatsApp Connector drives one or more self-hosted whatsmeow gateways straight from Odoo — send and receive WhatsApp messages without Meta’s Cloud API, without template pre-approval, and without a 24-hour session window. Each gateway connection is one endpoint, each session is one WhatsApp number paired by QR, and every inbound message is logged, matched to a contact, and posted where you can act on it.
It is built for teams who want to own their WhatsApp channel: a support desk running a shared number, a sales team messaging leads, or any business that needs WhatsApp inside Odoo but does not want to route customer conversations through a third-party SaaS. Deliverability safeguards — pacing, warm-up ramps, daily caps, opt-out handling, and number validation — are part of the core, because staying unbanned on the unofficial protocol is the whole game.
Self-Hosted, No Cloud Middleman
Connect Odoo to your own whatsmeow gateway instead of a paid WhatsApp Business API. No per-message fee, no template approval queue, no session window.
Deliverability Built In
Bursting is what gets a number banned. The queue paces every send, ramps a new number’s allowance over its first weeks, and honours opt-outs before a message leaves.
Inbound That Lands Where You Work
Incoming messages are matched to the right contact by phone number, downloaded with their media, and posted to that contact’s chatter.
Everything the channel needs,
safeguards included.
Eight capabilities covering gateways, pairing, sending, pacing, and everything that arrives back.
Multi-Gateway & Multi-Number Management
Register any number of gateway endpoints as connections, each with its own URL, API key, and webhook secret, and pair any number of WhatsApp numbers as sessions beneath them. A one-click Test button validates that a gateway is reachable and its key is valid.
QR Pairing & Live Status
Start a session and Odoo renders the WhatsApp pairing QR right on the form. A scheduled action keeps each session’s status current — Starting, Waiting for QR Scan, Connected, Disconnected, or Logged Out.
Send Text & Media, With Replies
Compose text, images, video, audio, documents, or stickers from a message form. Reply to an inbound message to quote it in WhatsApp, and send voice notes that play inline. Sends can target a private chat or a group.
Paced Outgoing Queue
Outgoing messages go onto a throttled queue that spaces each number’s sends apart by a random delay, takes turns between numbers, and carries an idempotency key so a mid-transaction crash can never send the same message twice.
Warm-Up Ramp & Volume Caps
Each session can cap how many queued messages it sends per day, starting low for a brand-new number and growing automatically as it ages toward a ceiling you set. An hourly cap stops a day’s allowance leaving in one burst.
Opt-Out & Number Validation
A contact who asks to stop is flagged, and no path can ever message them again — not the queue, composer, server action, or Discuss reply. The gateway is also asked which queued numbers are actually on WhatsApp, so dead numbers are skipped.
Inbound Filter Rules
Every session carries an ordered list of accept/reject rules matched on chat type, message kind, sender, phone, chat JID, LID, or a body keyword — combine them into a blocklist or an allowlist. A dedicated opt-out action flags the sender while keeping the message on file.
Inbound Delivery to the Chatter
An accepted message is matched to a contact on the last ten digits of their number and posted to their chatter with media attached and voice notes flagged to play inline. Group messages are labelled with the group name.
Deploy the gateway first
Installing the add-on from the Apps list is the standard Odoo step. What is specific to this module is deploying the whatsmeow gateway — the self-hosted service the connector talks to. It is a single Go binary that speaks the WhatsApp Web protocol on one side and HTTP+JSON to Odoo on the other. An installer sets it up as a systemd service on Debian 12/13 or Ubuntu 22.04/24.04.
Clone the repository
Clone it onto the gateway host — running it on the same machine as Odoo is the simple case.
Run the installer
From the repository root, run sudo ./install.sh.
Keep the printed credentials
It prints a Gateway URL, API Key, and Webhook Secret — keep these for the connection record.
$ cd whatsmeow-odoo
$ sudo ./install.sh
One gateway can host several WhatsApp numbers, and one Odoo can drive several gateways. Re-running the installer safely rebuilds and restarts the service, keeping your credentials and paired sessions. See DEPLOY.md for options such as a custom port, a cross-host webhook URL, TLS, and backups. With the gateway running, register it under WhatsApp → Configuration → Gateways using the printed credentials.
From gateway to live number
All setup lives under the WhatsApp → Configuration menu, visible to WhatsApp Administrators.
Register a gateway
Under Gateways, enter the URL, API Key, and Webhook Secret, then click Test.
Point the webhook at Odoo
POST events to /whatsmeow/webhook using the same secret.
Pair a WhatsApp number
Under Sessions, add a Session Key, pick the gateway, click Start, and scan the QR.
Tune send pacing
Set Min/Max Delay and, under Warm-Up & Daily Cap, the Day-1 Allowance, Growth, Ceiling, Hourly Cap, and Timezone.
Set inbound behaviour
Choose what to do with unmatched messages, add Inbound Filter Rules, and optionally enable Auto Mark as Read.
See it in action
Connecting a gateway, pairing a number, sending a message, and keeping a number healthy.
From zero to a live channel
Four workflows covering setup, sending, and keeping the number healthy.
Connect a Gateway
Register your self-hosted gateway so Odoo can talk to WhatsApp through it.
Pair a WhatsApp Number
Bring a WhatsApp number online as a session you can send and receive from.
Send a Message
Send a text or a file to a WhatsApp contact.
Keep a Number Healthy
Protect a number’s reputation so it keeps sending.
Full transparency
This module talks to an unofficial WhatsApp protocol through a self-hosted gateway, so a few things are outside Odoo’s control by design.
A number can still be rate-limited or banned
WhatsApp can restrict a number that behaves like a bulk sender. The pacing, warm-up, opt-out, and number-validation features exist to reduce that risk, but no safeguard can guarantee a number is never restricted — warm up new numbers slowly and keep your lists clean.
Validation lookups are rationed on purpose
Number-registration and validation lookups are rationed by the gateway. A number Odoo has not yet been able to check is treated as sendable, not as invalid, so a fresh contact is never permanently blocked by a missing answer.
Questions, answered
Quick answers to the most common questions.
Do I need a WhatsApp Business API account or Meta approval?
No. This module connects to your own self-hosted whatsmeow gateway over the unofficial Web protocol. There is no template approval, no per-message fee, and no 24-hour session window.
Can I run more than one WhatsApp number?
Yes. Register as many gateway connections as you like and pair as many sessions (numbers) beneath them as you need. Each session has its own pacing, warm-up, and inbound rules — one number’s reputation never affects another’s.
How are incoming messages matched to my contacts?
By the last ten digits of the sender’s phone number, compared against your contacts’ phone fields regardless of how they are formatted. A message from an unknown number is still stored; it simply has no contact attached.
Who can configure gateways and see the API keys?
Only members of the WhatsApp / Administrator group. The API key and webhook secret are restricted fields — a regular WhatsApp user can send and receive messages without ever being able to read a gateway’s credentials.
What happens if a send fails or the gateway is down?
The message is marked in error with the reason, and the rest of the queue keeps moving — one bad send never stalls the others. You can retry it once the gateway is healthy; the idempotency key ensures a message that already reached WhatsApp is never sent twice.
Release history
A clean record of every release.
Bytesraw
🛠️ Need help?
Got a question, found a bug, or need a custom enhancement? Our support team responds within 24 hours on business days.
help@bytesraw.com →💼 Custom development
Need this module tailored to your workflow, or a brand-new Odoo solution? Let’s talk about your project.
info@bytesraw.com →
Please log in to comment on this module