Skip to content
raucheachoPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Msgkit — embeddable WhatsApp messaging toolkit

Your own WhatsApp transport channel — run it as a service, or embed it in your Go binary.

License: MIT Build

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.


Contents

Quickstart

# 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/releases
msgkit init my-project
cd my-project
msgkit start
# Open the dashboard link printed in your terminal and scan the QR code with WhatsApp → done.

Use as a Go library

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/msgkit
package 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-core holds a *msgkit.Client — so the deployed server and an embedded binary share one implementation. Fix a bug in send/receive and both get it.

Architecture

┌───────────────────────────────────────────────────────────────┐
│                 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.

CLI reference

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

API Reference

Most endpoints require an apikey header with your anon or service key. Instance-admin endpoints (number pairing, key rotation, settings) require service.

POST /v1/messages/send

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

POST /v1/messages/presence

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

GET /v1/messages · GET /v1/chats

List recent outbound messages, or the WhatsApp contacts visible to the connected number.

Webhooks & inbound messages

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.

Conversations & human takeover

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.

Inbound media (GET /v1/media/{message_id})

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 file

GET /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.

GET /v1/health

Instance-wide liveness check (no auth required).

{
  "status": "ok",
  "uptime_seconds": 123456
}

Instance administration

These require the service key.

POST /v1/numbers/pair

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.

GET /v1/numbers

[
  {
    "jid": "212600000000@s.whatsapp.net",
    "phone": "212600000000",
    "connected": true
  }
]

POST /v1/keys/regenerate

{"tier": "anon" | "service"} — issues a new key for that tier, immediately invalidating the previous one.

GET /v1/settings · PATCH /v1/settings

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.

Error responses

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

SDK Examples

TypeScript

npm install msgkit-client
import { 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

go get github.com/raucheacho/msgkit-go
import 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)

Python

pip install msgkit
from 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.

Configuration

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

Deploying without the CLI (Docker Compose, Dokploy, Coolify, …)

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.

Project structure

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 the msgkit library to embed WhatsApp in-process (Use as a Go library).

Security

  • Two API key tiers: anon (send only, rate-limited) and service (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)
  • .env is 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

Development

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

Roadmap

Version What's coming
v1.0 Single-number instance, dashboard, 3 SDKs, CLI, embeddable Go library — shipped
v2.0 Dashboard authentication when exposed publicly

License

MIT — Use it, fork it, ship it.


Built by raucheacho · Star this repo if it saves you from a BSP invoice

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages