Your own WhatsApp transport channel — run it as a service, or embed it in your Go binary.
Send transactional messages, receive replies, and forward everything to your app over webhooks. Use it two ways: run the self-contained server (API + dashboard, driven by the CLI or Docker, with SDKs in Go/TypeScript/Python), or import it as a Go library (github.com/raucheacho/msgkit) and link the whole stack — whatsmeow included — straight into your own binary, no separate service to deploy. Each instance runs one WhatsApp number end to end; need a second number, run a second instance.
Caution
Important disclaimer — read before using
Msgkit relies on whatsmeow, an unofficial library that reverse-engineers the WhatsApp Web protocol. This is not the official Meta Cloud API. This means:
- Risk of phone number ban — Meta may ban your number without warning if usage patterns are deemed abnormal. A ban permanently cuts the WhatsApp channel.
- No SLA, no official support — If WhatsApp changes its protocol, Msgkit may break until the community (whatsmeow or Msgkit) ships a fix.
- Recommended for: MVPs, side-projects, products in validation phase with moderate user volume.
- Not recommended for: production at scale with zero downtime tolerance — in that case, use the official Meta Cloud API once volume/budget justifies it.
This transparency is intentional. It builds more trust than silence and prevents bad surprises for early adopters.
- Quickstart
- Use as a Go library
- Architecture
- CLI reference
- API reference
- SDK examples
- Configuration
- Project structure
- Security
- Development
- Roadmap
- License
# macOS / Linux, via Homebrew
brew install raucheacho/tap/msgkit
# or download a prebuilt binary for your platform from the Releases page:
# https://github.com/raucheacho/msgkit/releasesmsgkit init my-project
cd my-project
msgkit start
# Open the dashboard link printed in your terminal and scan the QR code with WhatsApp → done.Don't want to run a separate service? Import msgkit and drive a WhatsApp number from inside your own program. Everything — the whatsmeow client, the SQLite session store — is statically linked into your binary. Because the SQLite driver is pure Go (modernc.org/sqlite), CGO_ENABLED=0 builds and cross-compilation just work; no C toolchain required.
go get github.com/raucheacho/msgkitpackage main
import (
"context"
"fmt"
"github.com/raucheacho/msgkit"
)
func main() {
c, err := msgkit.New(msgkit.Config{DataDir: "./data"})
if err != nil {
panic(err)
}
defer c.Close()
// Echo inbound messages back to the sender.
c.OnMessage(func(m msgkit.Inbound) {
c.SendText(context.Background(), m.From, "echo: "+m.Text)
})
c.Start(context.Background()) // reconnects an existing number, or begins pairing
if qr := c.QR(); qr != "" {
fmt.Println("scan this QR with WhatsApp → Linked devices:", qr)
}
c.SendText(context.Background(), "+212600000000", "hello from my binary")
select {} // keep running to receive
}Client also exposes SendMedia, SendLocation, SetPresence, Chats, Numbers, IsConnected, and OnStatus (delivery/read receipts). A runnable version lives in examples/whatsapp — CGO_ENABLED=0 go build ./examples/whatsapp produces a single static binary. The low-level whatsmeow wrapper is the public whatsapp package (Pool), usable on its own.
The server is built on this same library.
msgkit-coreholds a*msgkit.Client— so the deployed server and an embedded binary share one implementation. Fix a bug in send/receive and both get it.
┌───────────────────────────────────────────────────────────────┐
│ msgkit-core (single Go binary) │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ REST API (Chi) + WebSocket hub │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ apikey → anon | service tier │
│ │ │
│ ┌──────────────────────────▼──────────────────────────┐ │
│ │ 1 WhatsApp number (whatsmeow) │ │
│ │ messages · conversations · SQLite │ │
│ └───────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Dashboard (static, embed.FS) │ │
│ └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
▲
│ HTTP + WebSocket, port 54321
▼
Browser / SDK client
One binary. One image. One port. One process. Mono-tenant: one instance runs exactly one WhatsApp number (whatsmeow). No Redis, no Postgres, no message queue required — just SQLite, three files under data/: control.db (API keys, paired number, settings), data.db (messages, conversations, webhook logs), session.db (whatsmeow's own device state).
Why one number per instance, not a pool: an earlier design let one instance round-robin/fail over across several whatsmeow numbers. It's not worth the complexity: for a two-way conversation, a customer's reply could land on a different number than the one they messaged, which is confusing at best — at the real operational cost of running several actual phone numbers. Need a genuinely separate number (say, one per app) — run a second msgkit init && msgkit start in a second directory. Each instance is fully self-contained: its own keys, its own data, its own port.
Every command operates on the local msgkit/ directory (found by walking up from the current directory) and Docker directly.
| Command | What it does |
|---|---|
msgkit init [name] |
Scaffold a new instance: config.toml, .env with anon/service keys |
msgkit start |
Render docker-compose.yml, pull the image if needed, start the container, print keys and the dashboard URL |
msgkit stop |
Stop containers; all data is preserved |
msgkit restart |
Stop, re-render config (in case it changed), start again |
msgkit status |
Check whether the container is running and the API is responding |
msgkit logs |
Stream container logs in real time |
msgkit keys |
Show the anon/service keys stored in .env |
msgkit update |
Pull the latest image and restart |
msgkit reset |
Delete all instance data (WhatsApp session and history) and restart — forces a fresh QR scan |
msgkit destroy |
Remove containers and volumes; keeps config.toml and .env so msgkit start can recreate the instance |
Most endpoints require an apikey header with your anon or service key. Instance-admin endpoints (number pairing, key rotation, settings) require service.
Send a message to a phone number. type is text, image, video, audio, document, or location (media is accepted too, as a legacy alias for image). Media sends take url (a public link) and, for document, filename; caption works for every kind except audio — WhatsApp's protocol carries no caption field for voice notes. Location sends take latitude/longitude (required) and name/address (optional).
curl -X POST http://localhost:54321/v1/messages/send \
-H "Content-Type: application/json" \
-H "apikey: msgkit_anon_xxx" \
-d '{"phone": "+212600000000", "type": "text", "text": "Your order #1234 has shipped!"}'{
"message_id": "3EB00436D840039D465DC3"
}Set the typing indicator for a chat without sending a message — useful for AI agents that want to show "typing…" while composing a reply.
curl -X POST http://localhost:54321/v1/messages/presence \
-H "Content-Type: application/json" \
-H "apikey: msgkit_anon_xxx" \
-d '{"phone": "+212600000000", "state": "typing"}'state is "typing" or "paused".
List recent outbound messages, or the WhatsApp contacts visible to the connected number.
Msgkit supports two-way communication. Configure a webhook endpoint (via the dashboard or PATCH /v1/settings) to instantly receive HTTP POST payloads when:
message.received: a user replies to your WhatsApp number (useful for connecting AI support agents like n8n/Make).message.sent,message.delivered,message.read: status updates for your outbound messages.session.disconnected/session.reconnected: the number loses or regains connection.
By default, msgkit ignores group chats and WhatsApp status (stories) updates — message.received only fires for direct 1:1 messages, keeping your webhook feed and dashboard focused on transactional conversations. Toggle ignore_groups/ignore_status from the dashboard.
Every inbound message from a contact is tracked in a conversation (one per phone number, created automatically on first contact) that's either bot (default) or human. Take a conversation over from your own app's admin UI or an LLM tool call — not from the msgkit dashboard, which stays infra-only by design; conversations, agents, and takeover UX belong in your application, msgkit just gives it the mechanism. Every outbound send is linked to its conversation too, so GET /v1/conversations/<id>/messages shows the full thread — inbound replies and outbound sends — in one chronological list.
# List conversations
curl -H "apikey: msgkit_anon_xxx" http://localhost:54321/v1/conversations
# Full history for one conversation (inbound + outbound, chronological)
curl -H "apikey: msgkit_anon_xxx" http://localhost:54321/v1/conversations/<id>/messages
# Take over — marks the conversation human; msgkit keeps forwarding
# message.received either way, now carrying conversation_state so your
# bot knows to stay quiet
curl -X POST http://localhost:54321/v1/conversations/<id>/takeover \
-H "apikey: msgkit_anon_xxx" \
-d '{"actor": "agent-42", "reason": "customer asked for a refund"}'
# Hand it back to the bot
curl -X POST http://localhost:54321/v1/conversations/<id>/resume \
-H "apikey: msgkit_anon_xxx" \
-d '{"actor": "agent-42", "reason": "resolved"}'actor/reason are optional but recorded on every takeover/resume — a takeover is never a silent state flip. msgkit doesn't decide whether your bot should act on a human-owned conversation — it always forwards message.received and always records/broadcasts it over the WebSocket hub, human or not. It's up to your app's own logic to read conversation_state from the webhook payload and skip auto-replying when it's human. This also means your app keeps full visibility (logging, notifications, anything else) even while a human is handling the thread — msgkit never goes silent. Sending a reply while human uses the same POST /v1/messages/send you already use for outbound messages — there's no separate "send as human" endpoint.
When a contact sends an image, video, voice note, or document, msgkit downloads it right away and makes the raw bytes retrievable — so a bot built on msgkit can pull the file and run it through Whisper, OCR, or whatever else your app needs, without msgkit itself trying to be smart about the content:
curl -H "apikey: msgkit_anon_xxx" http://localhost:54321/v1/media/<message_id> -o fileGET /v1/conversations/<id>/messages and the message.received webhook payload both carry media_kind (image/video/audio/document) and the mimetype for any message that had an attachment — a caption, if the message had one, shows up as the message's content/text same as a plain text message would. Note two limitations by design: there's no retention or cleanup policy for downloaded media yet (files live under the instance's data directory until you delete them, same all-or-nothing model as msgkit reset), and GET /v1/media/{id} 404s if the download itself failed at receive time even though the message row exists — check for a non-empty media_kind before assuming the file is there.
Instance-wide liveness check (no auth required).
{
"status": "ok",
"uptime_seconds": 123456
}These require the service key.
Starts pairing a WhatsApp number. The QR code streams via the WebSocket hub (number.qr event) and is also renderable at GET /v1/numbers/qr — same PNG/JSON behavior the dashboard uses. Rejected with 409 if a number is already paired — each instance is capped at one.
[
{
"jid": "212600000000@s.whatsapp.net",
"phone": "212600000000",
"connected": true
}
]{"tier": "anon" | "service"} — issues a new key for that tier, immediately invalidating the previous one.
Read or partially update the instance's messaging/WhatsApp/webhook settings — see Configuration. A PATCH takes effect immediately (no restart needed), without disconnecting an already-paired number.
| HTTP Code | Error | Description |
|---|---|---|
401 |
invalid api key / missing apikey header |
Key is missing, unknown, or malformed |
403 |
insufficient permissions |
Key's tier can't access this endpoint (e.g. an anon key on /v1/numbers) |
429 |
rate_limit_exceeded |
Per-minute message rate limit exceeded |
npm install msgkit-clientimport { createClient, RateLimitError } from "msgkit-client";
const msgkit = createClient("http://localhost:54321", "msgkit_anon_xxx");
try {
const { messageId } = await msgkit.sendText("+212600000000", "Your order #1234 has shipped!");
console.log("sent", messageId);
} catch (err) {
if (err instanceof RateLimitError) {
console.log("slow down");
}
}go get github.com/raucheacho/msgkit-goimport msgkit "github.com/raucheacho/msgkit-go"
client := msgkit.NewClient("http://localhost:54321", msgkit.WithApiKey("msgkit_anon_xxx"))
resp, err := client.SendText(ctx, "+212600000000", "Your order #1234 has shipped!")
if err != nil {
log.Fatal(err)
}
fmt.Println("sent", resp.MessageID)pip install msgkitfrom msgkit import create_client
client = create_client("http://localhost:54321", "msgkit_anon_xxx")
resp = client.send_text("+212600000000", "Your order #1234 has shipped!")
print("sent", resp.message_id)All three SDKs take the same apikey — the instance's anon or service key.
msgkit/config.toml holds instance-wide deployment settings only — display name, API port, storage driver:
[project]
name = "my-project"
[api]
port = 54321
enable_dashboard = true
[storage]
driver = "sqlite" # "sqlite" | "postgres"Everything else — messaging (max_messages_per_minute, simulate_typing), WhatsApp inbound filters (ignore_groups, ignore_status), and the webhook endpoint/secret — lives in one settings row in the instance's control database and is managed via the dashboard or PATCH /v1/settings, not config.toml. A fresh instance gets sensible defaults (60 messages/min, group/status events ignored).
msgkit start is the zero-friction path for local dev — it generates config.toml and mounts it in. But msgkit-core doesn't actually require the file to exist: if it's missing, it boots on built-in defaults and a handful of MSGKIT_* environment variables layer on top — same self-hosting model as Supabase's docker-compose (.env-driven, no bespoke CLI needed at deploy time). This is what lets you point Dokploy/Coolify/a plain VPS straight at the published image:
cp .env.example .env # edit MSGKIT_PORT / MSGKIT_PROJECT_NAME / etc.
docker compose up -d| Variable | Overrides | Default |
|---|---|---|
MSGKIT_PORT |
api.port |
54321 |
MSGKIT_PROJECT_NAME |
project.name |
msgkit |
MSGKIT_PROJECT_REF |
project.ref |
msgkit-default |
MSGKIT_ENABLE_DASHBOARD |
api.enable_dashboard |
true |
MSGKIT_ANON_KEY / MSGKIT_SERVICE_KEY |
pins your own API keys instead of letting msgkit generate them | generated on first boot (printed once to the logs) |
/data still needs to be a persistent volume — it holds control.db/data.db (SQLite), the whatsmeow session (so you don't have to rescan the QR on every redeploy), and downloaded inbound media. On Dokploy/Coolify, attach a persistent volume mount to /data when creating the app; the docker-compose.yml at the repo root already declares one for local docker compose use. If you do want the customization config.toml gives you (a storage block, etc.), just mount your own file at /app/config.toml — it's read first, and MSGKIT_* env vars only override on top.
The repo root is the Go library module github.com/raucheacho/msgkit.
msgkit/ # module github.com/raucheacho/msgkit
├── msgkit.go # LIBRARY facade: the WhatsApp Client (New / OnMessage / SendText / …)
├── whatsapp/ # public low-level whatsmeow wrapper (Pool) — usable standalone
├── examples/whatsapp/ # runnable "embed msgkit in your own binary"
├── cmd/msgkit-core/ # msgkit-core: the server binary (main, graceful shutdown)
├── internal/ # server-only packages (not importable by consumers)
│ ├── api/ # HTTP handlers, routing, auth middleware
│ ├── project/ # Load(): builds the instance's single Runtime
│ ├── keys/ # API key generation/validation (anon/service tiers)
│ ├── store/ # SQLite: ControlStore + ProjectStore (messages/webhooks/conversations)
│ ├── sqlitedriver/ # registers pure-Go modernc SQLite under the "sqlite3" name
│ ├── webhooks/ # outbound webhook dispatch
│ └── ws/ # WebSocket hub
├── dashboard/ # React + Vite dashboard, embedded via go:embed
├── Dockerfile # CGO-free static build of msgkit-core
├── cli/ # nested module github.com/raucheacho/msgkit/cli (Cobra, drives Docker)
├── sdks/
│ ├── typescript/ # msgkit-client (npm) — HTTP client for the server
│ ├── go/ # github.com/raucheacho/msgkit/sdks/go — HTTP client for the server
│ └── python/ # msgkit (PyPI) — HTTP client for the server
├── .github/workflows/ # CI/CD: build, GoReleaser, SDK publishing
├── .goreleaser.yml # CLI binary releases (GitHub, Homebrew, Scoop)
├── Makefile # local multi-binary build into bin/
├── docker-compose.yml # deploy the published image directly — no CLI (see Configuration)
├── .env.example # MSGKIT_* variables for docker-compose.yml
├── LICENSE
└── README.md
The
sdks/are HTTP clients for talking to a deployed msgkit-core server over REST — distinct from importing themsgkitlibrary to embed WhatsApp in-process (Use as a Go library).
- Two API key tiers:
anon(send only, rate-limited) andservice(instance admin — number pairing, key rotation, settings) - Rate limiting per minute on outbound messages
- Dashboard is local-only and unauthenticated by default (trusted by network position) — put it behind a reverse proxy with auth before exposing it publicly (see Roadmap)
.envis gitignored and holds anon/service keys in plaintext locally — never commit it- Your number stays yours — history lives in a SQLite file under
data/that you own; back it up or export it like any local file, no vendor lock-in
Requires Go 1.23+, Node.js or Bun (dashboard), and Docker (for running the CLI's own integration path).
# Build every binary into bin/
make
# Or individually
make build-core # bin/msgkit-core (CGO-free, static)
make build-cli # bin/msgkit
make build-dashboard # builds dashboard/dist, embedded into msgkit-core via go:embed
# Run msgkit-core directly, without Docker or the CLI
go run ./cmd/msgkit-core -config=config.toml -data=./data
# Tests
go test ./... # library + server
cd cli && go test ./...
cd sdks/go && go test ./...
cd dashboard && npx tsc --noEmit && npm run build| Version | What's coming |
|---|---|
| v1.0 | Single-number instance, dashboard, 3 SDKs, CLI, embeddable Go library — shipped |
| v2.0 | Dashboard authentication when exposed publicly |
MIT — Use it, fork it, ship it.
Built by raucheacho · Star this repo if it saves you from a BSP invoice