Free, Open Source, Self-Hosted WhatsApp API Gateway
OpenWA Go SDK
This document describes SDK 0.7.0. Send idempotency, webhook failure redrive, message-window filters, poll choices, last-message types, and the event.response webhook event name require OpenWA 0.25.0 or later. The message.receipt and poll.vote webhook event names require OpenWA 0.26.0 or later.
Idiomatic Go client for the OpenWA WhatsApp API Gateway. Stdlib-only (no dependencies), context-first, with typed errors and an injectable transport pipeline.
OpenWA is an independent project, not affiliated with or endorsed by WhatsApp or Meta.
go get github.com/rmyndharis/OpenWA/sdk/go
Requires Go 1.22+.
Quick start
package main
import (
"context"
"log"
openwa "github.com/rmyndharis/OpenWA/sdk/go"
)
func main() {
client, err := openwa.New("http://localhost:2785", "owa_k1_…")
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
// Sessions are addressed by the UUID that Create returns, not by name. Create a
// session once; afterwards, find its ID with Sessions.List and a Name filter.
session, err := client.Sessions.Create(ctx, openwa.CreateSessionRequest{Name: "my-session"})
if err != nil {
log.Fatal(err)
}
if _, err := client.Sessions.Start(ctx, session.ID); err != nil {
log.Fatal(err)
}
// Link the account before sending: scan Sessions.QRCode (or use Sessions.RequestPairingCode for a number with no linked session),
// then wait for status "ready". An unlinked session answers the send with 409.
res, err := client.Messages.SendText(ctx, session.ID, openwa.SendTextRequest{
ChatID: "[email protected]",
Text: "Hello from the OpenWA Go SDK!",
})
if err != nil {
log.Fatal(err)
}
log.Println(res.MessageID)
}
Design
- Client entry point —
openwa.New(baseURL, apiKey, opts...)returns a*Client. Required credentials are positional; everything else is a functional Option. The client is safe for concurrent use. - Services by domain — the API is grouped onto exported fields:
client.Sessions,client.Messages,client.Contacts,client.Groups,client.Webhooks,client.Chats,client.Status,client.Labels,client.Channels,client.Catalog,client.Templates,client.Health,client.Search,client.Auth,client.Profile,client.Calls,client.Media. - Context-first — every network method takes
ctx context.Contextas its first argument; the context bounds the request (and any retries). - Functional options + DI — inject dependencies instead of relying on
globals:
WithHTTPClient,WithTransport,WithLogger,WithRetry,WithMiddleware,WithTimeout,WithUserAgent,WithHeader. - Typed errors — match with
errors.Isagainst the sentinels, or unwrap the concrete*APIErrorwitherrors.As.
Configuration
| Option | Purpose |
|---|---|
WithTimeout(d) |
Per-request timeout (default 30s). |
WithHTTPClient(hc) |
Inject a preconfigured *http.Client (pool, jar, timeout). |
WithTransport(rt) |
Inject the base http.RoundTripper (proxy, TLS, test double). |
WithLogger(l) |
Inject a Logger (default: no-op). |
WithRetry(p) |
Enable automatic retries (off by default). |
WithMiddleware(mw...) |
Add transport middleware (tracing, metrics, auth). |
WithUserAgent(ua) |
Override the User-Agent. |
WithHeader(k, v) |
Add a default header on every request. |
WithInsecureHTTP() |
Suppress the plaintext-http:// warning. |
Typed errors
res, err := client.Messages.SendText(ctx, sessionID, req)
switch {
case errors.Is(err, openwa.ErrConflict):
// 409 — a conflicting state, typically a session that is not "ready" yet:
// retry once it is. A keyed send can also answer 409 for a pending or
// uncertain outcome; APIError.Code tells them apart ("Send idempotency"
// below says what to do).
case errors.Is(err, openwa.ErrNotFound):
// 404 — unknown session/resource.
case err != nil:
var apiErr *openwa.APIError
if errors.As(err, &apiErr) {
log.Printf("API %d: %s (body: %v)", apiErr.StatusCode, apiErr.Message, apiErr.Body)
}
}
Sentinels: ErrBadRequest (400), ErrUnauthorized (401), ErrForbidden (403),
ErrNotFound (404), ErrConflict (409), ErrRateLimited (429),
ErrNotImplemented (501), ErrServiceUnavailable (503). 503 means the gateway
could not complete the request right now: the path to WhatsApp failed, the
gateway is draining or short of a dependency, or, on Baileys, WhatsApp throttled
(code 429) or timed out (code 408) the request. Back off and retry later instead
of at once, because repeating a throttled request straight away prolongs the
throttle; a catalog 503 can persist because WhatsApp may never answer that
query, so bound any retry. A 429 from the global rate limiter lifts when its
window expires (seconds for the per-second tier, up to an hour for the hourly
tier by default); APIError.RetryAfter carries its Retry-After header, which
WithRetry also honors. A 429 whose APIError.Code is "SEND_PACING_LIMITED"
is usually not transient: do not retry it before RetryAfter, which then comes
from the body: a few seconds when only sends still in flight caused it, the rest
of the failure breaker's cooldown (SEND_PACING_BREAKER_COOLDOWN_MS, 15 minutes
by default) after a run of send failures, otherwise up to the next UTC day.
APIError.Header holds the response headers. A timeout surfaces as
*openwa.TimeoutError. A 503 does not always prove a write was never carried
out: when WhatsApp timed out, the change may still have been applied, so re-read
the state before repeating it. A throttle on a send or a single write is the
exception: it was turned away before it ran, so nothing was sent or applied, and
a keyed send frees its Idempotency-Key. A group settings update with several
fields applies them one at a time, so a 503 on a later field, a throttle
included, leaves the earlier ones applied; its message lists them after
already applied:, so re-read the settings before retrying, or send one field
per request. In a routed deployment a forward that fails before reaching the
owner node answers 503, one that fails after the request reached it answers 502
or 504, and a 503 from the owner itself is relayed unchanged.
Retries
Off by default. Opt in with a policy. Idempotent requests (GET, HEAD, OPTIONS,
PUT, DELETE) are retried on network errors and on the policy's statuses (default
429/500/502/503/504). A POST or PATCH (every send endpoint is a POST) is never
retried after a network error and is retried only on 429 or 503 (when the policy
lists them): a 500/502/504 can arrive after the message was already sent, so
replaying it could send it twice. A 429 whose body has code: "SEND_PACING_LIMITED" is
never retried, whatever the method: its delay is the body's retryAfterSeconds, which can be
hours. Backoff is exponential, Retry-After is honored, and request bodies are safely rewound
on each attempt. A 503 can be WhatsApp throttling a Baileys send, and the default backoff (three
retries from 200ms) replays it within about a second and a half; for sends raise BaseDelay or lower
MaxRetries, or retry the throttled send yourself later.
client, _ := openwa.New(baseURL, apiKey,
openwa.WithRetry(openwa.DefaultRetryPolicy()),
)
Middleware / transport pipeline
Inject cross-cutting concerns (tracing, metrics, custom auth) as Middleware.
The first middleware is the outermost layer. The SDK's own auth, logging, and
retry layers sit inside yours, so every attempt is authenticated and observable.
tracing := func(next http.RoundTripper) http.RoundTripper {
return openwa.RoundTripperFunc(func(req *http.Request) (*http.Response, error) {
// start span, inject headers…
return next.RoundTrip(req)
})
}
client, _ := openwa.New(baseURL, apiKey, openwa.WithMiddleware(tracing))
Dependency injection & testing
Inject a mock http.RoundTripper — no network, no global state:
type mockRT struct{}
func (mockRT) RoundTrip(r *http.Request) (*http.Response, error) {
return &http.Response{
StatusCode: 200,
Body: io.NopCloser(strings.NewReader(`{"messageId":"m1","timestamp":1}`)),
Header: http.Header{},
}, nil
}
client, _ := openwa.New("https://api.test", "key", openwa.WithTransport(mockRT{}))
Escape hatch
For endpoints the typed services don't cover, use client.Do:
var out map[string]any
err := client.Do(ctx, "GET", "/api/some/new/path", nil, nil, &out)
Receiving webhooks
A webhook configured with a secret signs each delivery in its
X-OpenWA-Signature header. Check it with VerifyWebhookSignature against the
raw request body, exactly as received, and decode the JSON only after the check
passes: a re-serialized body can differ byte for byte and will not verify. The
helper returns false for a missing, malformed or non-matching signature.
WebhookDelivery types the decoded body.
http.HandleFunc("/openwa/webhook", func(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(r.Body)
if err != nil {
w.WriteHeader(http.StatusBadRequest)
return
}
if !openwa.VerifyWebhookSignature(body, r.Header.Get("X-OpenWA-Signature"), secret) {
w.WriteHeader(http.StatusUnauthorized)
return
}
var delivery openwa.WebhookDelivery
if err := json.Unmarshal(body, &delivery); err != nil {
w.WriteHeader(http.StatusBadRequest)
return
}
// Process delivery.Event and delivery.Data here.
w.WriteHeader(http.StatusOK)
})
Security & reliability
- Use HTTPS in production. The API key is sent as
X-API-Keyon every request and is bearer-equivalent. Over plaintexthttp://to a non-localhost host the SDK logs a warning (silence it withWithInsecureHTTP). - Redirects are never followed — a
3xxsurfaces as an*APIErrorrather than re-sending the API key to the redirect target. - Path segments (chat/message ids) are percent-encoded; a base-URL path prefix
(e.g. behind a proxy at
/v1) is preserved. - Empty and dot ids are refused. An empty,
.or..id returns an error and nothing is sent, so a proxy that resolves dot segments cannot turn the call into one on the parent resource.Client.Dorefuses a.or..segment the same way but sends an empty one (a trailing slash) as written.
Development
cd sdk/go
go test -race -cover ./...
go vet ./...
The TestRouting table asserts the exact method and path of every service call,
so a wrong path (the historical /messages/text vs /messages/send-text) fails
at test time.
Releasing
There is no publish workflow, and none is possible: Go has no registry to push to. The module proxy serves whatever a repository tag points at, so tagging is the release.
The tag must carry the module's directory prefix, because the module lives in a subdirectory rather than at the repository root:
# Correct — `sdk/go/` prefix, matching `module github.com/rmyndharis/OpenWA/sdk/go`
git tag sdk/go/v0.7.0 && git push origin sdk/go/v0.7.0
A bare v0.7.0 tag is the app version and does nothing for this module.
Without a prefixed tag, go get resolves a pseudo-version
(v0.0.0-<date>-<commit>) — usable, but callers cannot pin a release.
Cutting a release:
- Bump
DefaultUserAgentinoptions.go(it carries the SDK version and is sent on every request, so it drifts silently if only the tag moves). - Land that on
main. - Tag that commit
sdk/go/v<version>and push the tag.
A published version is immutable. Once the module proxy has served
sdk/go/vX.Y.Zit caches it permanently — deleting or moving the tag does not take it back, and the only remedy is to publish a higher version (and, if the bad one must be discouraged, aretractdirective ingo.mod). Tag a commit that is already green onmain.
Send idempotency
The example below requires SDK 0.6.0 or later and OpenWA 0.25.0 or later. SDK 0.5.1 does not expose this per-send key argument.
Supply a unique caller-owned key for one logical send and reuse it when retrying that same call. Keys contain 1-255 visible ASCII characters; unrelated calls must use different keys. The SDK forwards the key without changing its retry policy or generating one automatically. On the twelve routes below net/http may still send a keyed request once more after a dropped keep-alive connection; the gateway deduplicates it, so the call returns the first answer or a 409 IDEMPOTENCY_KEY_IN_PROGRESS to retry later with the same key.
ctx := openwa.WithIdempotencyKey(context.Background(), "order-123")
_, err := client.Messages.SendText(ctx, sessionID, openwa.SendTextRequest{ChatID: "[email protected]", Text: "Hello"})
The gateway supports text, image, video, audio, document, sticker, location, contact, template, poll, reply and forward sends. Completed calls replay their response; a 409 with the error code IDEMPOTENCY_KEY_IN_PROGRESS means the first request is still running, so retry with the same key later; a 409 IDEMPOTENCY_OUTCOME_UNKNOWN means the message may have been sent, so check the chat and, if it did not arrive, send again with a new key (the code tells them apart from the 409 for a session that is not connected). A changed request with the same key returns 422. The gateway retains keys for 24 hours. Bulk, product and button operations have no such guarantee. Omit the key to preserve existing behavior.