GOWA - WhatsApp REST API with support for UI, Multi Account, Webhooks, and MCP, and Chatwoot. Built with Golang for efficient memory use.
Working on GOWA
GOWA is a Go WhatsApp API server using whatsmeow, Fiber, and SQLite. The Go module
and local runtime directory are src/. rest also mounts MCP at /mcp when
enabled; both transports share the same device manager and usecases.
WhatsApp protocol verification
- whatsmeow is GOWA's base WhatsApp library. Every agent working on WhatsApp protocol behavior must verify relevant assumptions against upstream source and documentation before implementing or reviewing changes.
- Use the version pinned in
src/go.mod(and any applicable module replacement). Inspect the matching module source or upstream revision; do not assume upstreammainmatches GOWA's dependency. This applies to messages, events, JIDs, receipts, presence, authentication, sessions, and protocol types. - Identify the upstream files or symbols checked in the work summary. If the relevant source is unavailable or behavior remains uncertain, state that limitation rather than claiming protocol verification. Preserve GOWA's own API contracts and application behavior when integrating upstream behavior.
Working scope and completion
- Use the applicable scoped
AGENTS.mdand task-relevant source. The entry points below are routing hints; follow the ones needed for the affected behavior. - For multi-step work, identify the requested outcome and how to verify it. Continue through implementation, relevant checks, and fixes caused by the change. When the request includes running or inspecting the result, include that in completion. If blocked, report what remains and the specific missing input or access.
- Preserve unrelated working-tree changes. Keep
.env, SQLite databases, session data, QR codes, generated media, and history dumps out of commits. - Local tests using temporary databases, mocks, and fake clients can be run and repaired within the task without repeated approval. Running the app against saved sessions can reconnect real WhatsApp devices; use that runtime only within the user's authorized scope.
Task entry points
- DTOs and interfaces: domains. Business orchestration: usecases. Input rules: validation.
- REST, MCP, and websocket transport: UI adapters. For MCP authentication, use the OAuth guide.
- Device lifecycle, events, JIDs, and presence: WhatsApp infrastructure. For webhook payload changes, consult the payload contract.
- SQL queries, migrations, and cleanup: chat storage.
- Chatwoot routing, live sync, and history: Chatwoot infrastructure. Setup or routing-mode changes: configuration. Direct Postgres changes: scoped guide.
- Embedded browser UI:
src/views/components/andsrc/views/index.html. These are plain Vue 3 modules loaded from CDN, with Fomantic UI and[[,]]delimiters. - Startup and configuration:
src/cmd/root.go,src/cmd/rest.go,src/cmd/helpers.go,src/config/settings.go, andsrc/.env.example. Configuration and service wiring use package globals; flags override env/Viper and.envdefaults. - Packaging:
docker/golang.Dockerfile,docker/entrypoint.sh, and.github/workflows/. Read toolchain versions from those files andsrc/go.mod.AppVersionis a source constant insrc/config/settings.go; release builds do not inject it with ldflags. Release jobs require a pushed tag and generate GoReleaser configuration in/tmp; there is no committed.goreleaser.yml. Docker image publication is tag/manual driven. - Publishing a stable release: use new-release only when explicitly invoked. For an existing release's notes, use update-release-note.
Cross-layer contracts
- Keep transport parsing in
ui/, orchestration inusecase/, and DTOs/interfaces indomains/. Preserve JSON/form fields used by REST, MCP, and browser clients. - User-facing chat/message access must carry device scope. After login, storage
uses
client.Store.ID.ToNonAD().String(), not the user-facing device alias. - Repository interface changes must reach all three layers:
src/domains/chatstorage/interfaces.go,src/infrastructure/chatstorage/sqlite_repository.go, andsrc/infrastructure/whatsapp/chatstorage_wrapper.go. - Tests that mutate config, package globals, or scheduler state stay serial and restore that state. Use existing colocated test helpers and stubs.
Local commands and validation
Run Go commands from src/; select checks for the affected behavior:
go test ./path/to/affected/package/...
go test ./...
go vet ./...
go build -o whatsapp .
Choose checks for the changed behavior. Use the full suite for shared contracts,
startup, or broad changes. After relevant checks pass, repeat or broaden them only
for new edits, failures, or unresolved risks. For Markdown-only changes, check the
diff and references; application tests are unnecessary. Report checks actually run
and any unverified behavior.
Default SQLite builds use CGO; -tags purego selects modernc.org/sqlite when that
build variant is relevant. Run go mod tidy when changing dependencies.
For an authorized runtime check, go run . rest starts the server. Runtime paths
are relative to the process directory. Direct runs use src/storages
and src/statics; Docker Compose mounts the root-level directories into /app.
Keep these paths excluded from hot reload in src/.air.toml. The Docker entrypoint
fixes volume ownership before dropping to gowauser.