Skip to content
santigamoPublic

About

Self-hostable, open-source WhatsApp gateway on the official WhatsApp Business API (Meta Cloud API). Coexistence built in, priced per number, no per-message fees.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

546 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Eccos β€” self-hostable WhatsApp gateway on the official Meta Cloud API

Self-hostable, open-source WhatsApp gateway on the official WhatsApp Business API (Meta Cloud API)

Your app, your token, no message quota β€” running as a single Bun binary or entirely on Cloudflare (Workers + Durable Objects).

eccos.chat Β· EspaΓ±ol Β· English Β· Pricing Β· Coexistence Β· Docs

CI License: MIT Runtime: Bun Edge: Cloudflare Workers TypeScript PRs welcome


Deploy to Cloudflare


Bring your own Meta app + WhatsApp Business Account. Eccos holds the credentials and gives your apps a small, stable HTTP surface: send messages, receive inbound + delivery statuses, and get normalized events forwarded to your backend.

Status: v0 / first customer wave. The Workers target is account-scoped by default: a durable account β†’ WABA β†’ phone registry, hashed account keys, per-WABA credentials, and account-bound Embedded Signup. Each WABA routes to its own Durable Object for data-plane sharding. Eccos Cloud is generally available: a paid subscription per connected number, with a 14-day trial (eccos.chat). The gate it opened on, and the follow-ups still open, are in PRODUCTION-READINESS.md.

✨ Why Eccos

  • 🟒 Official Cloud API β€” built on Meta's WhatsApp Cloud API. No unofficial WhatsApp Web automation, so no fragile sessions and no ban risk.
  • πŸ”“ Self-host & own your token β€” MIT-licensed, runs on your box. Eccos keeps your Meta credentials; your apps just talk to a small HTTP surface.
  • πŸ’Έ No message quota β€” pay Meta directly. Service/inbound and in-window utility messages are free, and nobody meters or marks up your traffic.
  • ⚑ Two runtimes, one core β€” the same pure core ships as a self-hostable Bun binary or on Cloudflare Workers.
  • ☁️ All-in on Cloudflare β€” the Workers target runs the entire gateway on Cloudflare primitives: a Worker + one Durable Object per WABA (SQLite storage + Alarms for retries) and a native cron trigger for provisioning reconciliation. No external database or queue, and a permanent HTTPS webhook URL out of the box. Native Cloudflare Rate Limiting throttles the scoped send API β€” no external infra.
  • πŸ” Reliable forwarding β€” inbound messages and statuses are normalized and forwarded to your app, HMAC-signed and retried with exponential backoff.
  • πŸͺͺ Onboarding + operator console β€” the Workers target ships an Embedded Signup /connect flow, plus a separate operator console Worker (apps/dashboard/) for ops visibility β€” status, the message and event logs, the forwarding queue, the subscriber target and resubscribe β€” reachable only over a private RPC binding, with Better Auth sign-in and one workspace per organization. Per-number GDPR erasure is available through the scoped HTTP/RPC API.

πŸ†š How it compares

Eccos Managed Cloud-API SaaS Unofficial
(Evolution API, WAHA, wuzapi)
WhatsApp API βœ… Official Cloud API βœ… Official Cloud API ⚠️ Unofficial Web
Ban risk βœ… None βœ… None ❌ High
Self-hosted βœ… Yes ❌ SaaS only βœ… Yes
Open source βœ… MIT ❌ Closed βœ… Varies
Message metering βœ… Pay Meta direct ❌ Metered / markup β€”
Cost βœ… Free πŸ’° Paid βœ… Free

🧩 How it works

     your app  ──POST /v1/wabas/<WABA_ID>/messages──▢  Eccos  ──▢  Meta Cloud API  ──▢  WhatsApp
your app  ◀──forward (HMAC)────   Eccos  ◀──  Meta webhook    ◀──  WhatsApp
  • Outbound: Workers use POST /v1/wabas/<WABA_ID>/messages with an account API key β†’ Meta /{phone}/messages. An optional Idempotency-Key header makes a retry safe: within 24 h a repeated key gets the first response back (Meta refusals included) without sending again, or 409 while it is in flight or its outcome is unknown (a 502 with "outcome": "unknown": no answer or a 5xx from Meta, so it may have been sent). The same key with a different body gets 422 idempotency_key_reused.
  • Inbound: Meta calls POST /webhooks/meta; Eccos verifies X-Hub-Signature-256, normalizes the payload, and forwards { events: [...] } to the subscriber URL configured for that WABA, signed X-Eccos-Signature: sha256=<hex> when a subscriber secret is configured. Failed forwards retry with exponential backoff.
  • Templates: Workers use GET /v1/wabas/<WABA_ID>/templates to proxy the WABA's message_templates.

Normalized event shape (WhatsAppCallbackEvent):

| { type: "sent" | "delivered" | "read"; transportMessageId; at; broadcastId?; scheduleKey? }
| { type: "failed"; transportMessageId; at; errorCode?; errorMessage?; broadcastId?; scheduleKey? }
| { type: "reply"; from; fromUserId?; messageId; text; at; profileName?; payload?; replyTo?; broadcastId?; scheduleKey? }
| { type: "echo"; to; toUserId?; messageId; text; at }   // staff reply sent from the WhatsApp app (coexistence)
// Additive: every other message type, inbound and echoed, instead of being dropped
| { type: "message"; from; fromUserId?; messageId; at; profileName?; replyTo?; broadcastId?; scheduleKey? } & MessageContent
| { type: "message_echo"; to; toUserId?; messageId; at; payload? } & MessageContent
// Emitted by Eccos, not Meta: a scheduled send that will not go out (reason: "rejected" | "expired" | "unknown")
| { type: "scheduled_failed"; scheduleKey; to; reason; errorCode?; errorMessage?; at; phoneNumberId? }

reply / echo still carry text, button and interactive replies; payload (on reply, and on message_echo for a button tapped in the Business app) is the quick-reply button payload or the interactive button_reply / list_reply id, absent when there is none. profileName is the sender's WhatsApp profile name, present only when Meta sends one (reply and inbound message only). replyTo (reply and inbound message) is the id of the message the customer replied to: a quoted message, or the template or interactive message whose button they tapped. Absent otherwise. broadcastId (statuses, and reply/message whose replyTo is such a message) names the broadcast that sent the message, and scheduleKey the scheduled send. fromUserId / toUserId is the customer's business-scoped user id (BSUID, e.g. US.13491208655302741918) when Meta sends one. For a username user whose phone number Meta withholds, from / to carries that BSUID instead of a number; otherwise from / to is the phone number as before. A subscriber that validates from / to as E.164 must also accept a BSUID (see CHANGELOG). Everything else arrives as message (inbound) or message_echo (coexistence), with Meta's raw type in messageType and only the fields that type uses (MessageContent in packages/core/src/types.ts):

messageType Fields
image audio video document sticker media: { id; mimeType?; sha256?; caption?; filename? } β€” a Meta media id, never downloaded
location location: { latitude; longitude; name?; address?; url? }
reaction reaction: { messageId; emoji? } (no emoji = reaction removed)
interactive (e.g. nfm_reply) interactive: { type; body?; responseJson? }
contacts / order / system Meta's object verbatim under the same key (system also sets text)
unsupported errorCode?; errorMessage? (e.g. 131060)
edit (echo) originalMessageId plus the new content (text or media)
revoke (echo) originalMessageId
anything else messageType only β€” never dropped

Built entirely on Cloudflare

A WhatsApp gateway usually needs a server, a database, a job queue, a cron, and a public HTTPS endpoint. The Workers target folds all of it into two Cloudflare primitives: a stateless Worker at the edge, and one or more Durable Objects that own built-in SQLite and Alarm-driven retry loops. Each WABA routes to its own versioned object. The Worker keeps no state β€” it hands every message and event to the appropriate object. No external infrastructure at all.

The object name is versioned with the WABA and jurisdiction frozen into the routing key; see the deployment runbook before deploying.

flowchart LR
    meta["Meta Cloud API<br/>πŸ“± WhatsApp"]
    app["Your app<br/>(subscriber)"]

    subgraph cf["Cloudflare"]
        direction TB
        worker["Worker β€” the edge<br/>handles HTTP, checks auth, calls Meta<br/>(keeps no state)"]
        subgraph dobj["Durable Object β€” the memory (one per WABA)"]
            direction LR
            sqlite[("SQLite<br/>stores messages<br/>and events")]
            alarm{{"Alarm<br/>forwards to your app,<br/>retries on failure"}}
        end
        worker ==>|"hands off all state"| dobj
    end

    app -->|"send a message"| worker
    meta <-->|"messages and webhooks"| worker
    alarm -->|"forward events"| app

    classDef ext fill:#eef,stroke:#99a,color:#223;
    classDef edge2 fill:#fde2c6,stroke:#f6821f,color:#7a3e0a;
    classDef stateful fill:#f6821f,stroke:#a85a12,color:#fff;
    class meta,app ext;
    class worker edge2;
    class sqlite,alarm stateful;
Loading

Orange = the stateful Durable Object primitives (SQLite + Alarm); peach = the stateless Worker.

Cloudflare primitive What it does in Eccos Replaces
Worker (apps/gateway/src/worker.ts) Stateless edge HTTP β€” auth, calls the Meta API, hands all state to the Durable Object a web server
Durable Object β€” EccosGateway (apps/gateway/src/gateway.ts) One versioned, single-writer instance per WABA a stateful service + locking
DO SQLite storage Inbound events, outbound log, the delivery queue, onboarding config a database
DO Alarms Wakes the DO to forward events and retry with exponential backoff a job queue + cron
Rate Limiting binding Native throttling on POST /v1/messages (defensive; no-op if unbound) an external rate limiter
workers.dev + TLS A permanent HTTPS URL for Meta's webhook β€” no tunnel, no domain setup a domain, TLS & reverse proxy
Workers Observability Request logs at 100 % head-sampling a logging/metrics stack

🎯 Deployment targets

Eccos ships two targets that share one pure core (packages/core/: parser, signature, send, templates). Pick whichever fits how you want to run it:

Bun (self-host) Cloudflare Workers
Code src/ apps/gateway/
Storage SQLite (bun:sqlite) Durable Object (SQLite)
Forwarding retries in-process loop Durable Object Alarms
Deploy Docker / single process wrangler deploy
Embedded Signup /connect β€” βœ…
Best for owning the box and the token zero-ops + a stable HTTPS webhook URL

The Bun target is the auditable, run-it-anywhere binary. The Workers target trades literal "your box" for zero-ops and a permanent HTTPS URL (no tunnel needed for Meta webhooks), and is where the newer v1 features (/connect, plus the operator console below) live first.

πŸ•ΉοΈ Operator console

The operator console lives in apps/dashboard/ as its own Cloudflare Worker (a TanStack Start / React app) β€” it is not a route on the gateway. It reaches the gateway only over a private RPC service binding (env.GATEWAY, entrypoint GatewayRPC); the gateway itself exposes no public dashboard HTTP surface. Users sign in with Better Auth (email and password, on the console's own D1 database) and only see their organization's numbers; the console answers only the host set in BETTER_AUTH_URL. See apps/dashboard/README.md for setup.

πŸš€ Quickstart β€” local (Bun)

bun install
cp .env.example .env   # fill in META_* + ECCOS_API_KEY + SUBSCRIBER_*
bun run dev            # http://localhost:3000/health

To receive webhooks during development, expose the port (e.g. ngrok http 3000 or cloudflared tunnel --url http://localhost:3000) and set the Meta webhook callback URL to https://<public-host>/webhooks/meta with your META_WEBHOOK_VERIFY_TOKEN. Subscribe the messages field.

🐳 Quickstart β€” self-host (Docker)

cp .env.example .env   # fill in values
docker compose up -d

SQLite data is persisted in the eccos-data volume. The bundled .dockerignore keeps your .env and local data out of the image.

☁️ Quickstart β€” Cloudflare Workers

bun install
bun run cf-types                 # generate worker-configuration.d.ts
# Required app-level secrets:
wrangler secret put META_APP_SECRET
wrangler secret put META_WEBHOOK_VERIFY_TOKEN
wrangler secret put ECCOS_ADMIN_API_KEY
# Optional (Embedded Signup /connect flow):
wrangler secret put META_APP_ID
wrangler secret put META_ES_CONFIG_ID

# Your real config (domains, GATEWAY_PUBLIC_URL) stays out of git:
cp -n apps/gateway/wrangler.jsonc apps/gateway/wrangler.production.jsonc
# Edit that file: add vars.GATEWAY_PUBLIC_URL and your routes before deploying.
bun run deploy                   # wrangler deploy -c wrangler.production.jsonc

The Workers target is account-scoped by default β€” there are no global META_ACCESS_TOKEN / META_WABA_ID / META_PHONE_NUMBER_ID / ECCOS_API_KEY / SUBSCRIBER_* secrets. Per-WABA Meta credentials and subscriber settings live in the control plane / per-WABA Durable Object runtime state: create an account, then register WABAs through the Embedded Signup /connect flow or the admin bootstrap API (see docs/multi-tenancy.md).

One-click deploy

Deploy to Cloudflare

The button deploys the gateway Worker (apps/gateway/); the operator console (apps/dashboard/) is a separate Worker you deploy on its own. Two things to know about the guided flow:

  • Monorepo: Eccos is a Bun workspace and the gateway imports @eccos/core / @eccos/gateway-contract via workspace:*. If Cloudflare's build can't resolve them, point the build's install/root at the repo root (run bun install at the root, deploy apps/gateway).
  • Secrets: the button provisions bindings but not secret values β€” set the app-level secrets (listed above) with wrangler secret put or in the dashboard after the first deploy.

Every deployment is account-scoped by default β€” one-account and multi-account installs follow the same flow. Create accounts and register WABAs through the multi-tenant deployment runbook.

The bun install β†’ wrangler secret put β†’ bun run deploy steps above are the reliable path; see docs/deployment.md for the full env matrix, smoke test, and rollback.

Non-secret vars (META_GRAPH_VERSION, GATEWAY_PUBLIC_URL, FORWARD_MAX_ATTEMPTS, CONTENT_RETENTION_DAYS, DELIVERY_RETENTION_DAYS, and optionally DO_JURISDICTION) live in wrangler.production.jsonc (add GATEWAY_PUBLIC_URL there before connecting numbers). The root bun run deploy reads your own gitignored apps/gateway/wrangler.production.jsonc (see docs/deployment.md). Existing self-hosters keep the same Worker names and Durable Object data. Templates use keep_vars: true and omit installation-specific values, so plain Wrangler deploys preserve those deployed vars. Preserve your populated config when adopting the production-file helpers; see the upgrade note.

Point Meta's webhook at https://<worker>.workers.dev/webhooks/meta β€” or, once you put the Worker on a custom domain under your Meta app's declared application domain, at https://<your-gateway-host>/webhooks/meta; the ordered cutover between the two is in docs/deployment.md. An empty account registry is a healthy gateway: /ready reports the app-level Meta secrets (never values) plus the control plane's liveness, and webhooks/sends become reachable once an account owns a registered WABA.

Data residency: to pin the Durable Object to a Cloudflare jurisdiction (e.g. "eu"), set DO_JURISDICTION on the first deploy, before any production data exists. Changing it later derives a different DurableObjectId β€” a new, empty Durable Object β€” and does not migrate the existing data (messages, delivery queue, connected WABA/phone config). Details in docs/deployment.md.

Moving from Eccos Cloud to a self-host? The migration guide lives at eccos.chat/migrate (source: apps/site/src/page-content/migrate.html). Short version: there is no automatic export β€” you page through the operator RPC reads for what is still within retention, redeploy with your own Meta credentials, re-point the webhook and subscriber, smoke-test, and only then decommission Cloud. Meta tokens, operator secrets, the DurableObjectId/Alarm, and the Embedded Signup OAuth connection are not portable.

πŸ“‘ HTTP API

Integrating with Eccos Cloud? See the API guide (authentication, sending, idempotency, rate limit, webhooks, event reference). The table below is the route overview for both targets.

Method Path Auth Target Purpose
GET /health none both Liveness
GET /webhooks/meta verify token (query) both Meta subscription challenge
POST /webhooks/meta X-Hub-Signature-256 both Inbound messages + delivery statuses
POST /v1/messages Bearer ECCOS_API_KEY Bun Send a message
POST /v1/wabas/<id>/messages Bearer account key Workers Send through a WABA the account owns
GET /v1/templates Bearer ECCOS_API_KEY Bun List message templates
GET /v1/wabas/<id>/templates Bearer account key Workers List templates for an owned WABA
POST /v1/wabas/<id>/privacy/erasure Bearer account key Workers Erase within an owned WABA
GET /v1/wabas/<id>/export Bearer account key Workers Export an owned WABA's retained data
GET /connect account key / Meta OAuth Workers Embedded Signup (coexistence) flow
POST /connect/exchange account key + OAuth state Workers Exchange OAuth code β†’ register WABA/phone

The gateway has no public dashboard route β€” the operator console is a separate Worker; see Operator console above.

Send example

curl -X POST http://localhost:3000/v1/messages \
  -H "authorization: Bearer $ECCOS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "to": "34600000000",
    "type": "template",
    "template": {
      "name": "pre_cita",
      "language": { "code": "es" },
      "components": [
        { "type": "body", "parameters": [
          { "type": "text", "parameter_name": "customer_name", "text": "Ana" }
        ] }
      ]
    }
  }'

The body is a Meta message object minus messaging_product (Eccos injects it). Returns { "ok": true, "messages": [{ "id": "wamid..." }] }. On the Workers target to is a phone number (5-15 digits) or a BSUID such as US.13491208655302741918, which Eccos sends to Meta as recipient. Meta's own recipient field (a BSUID) is accepted when to is absent; if both are sent, to wins. Anything else is a 400. Meta does not deliver one-tap, zero-tap or copy-code authentication templates to a BSUID (error 131062).

βš™οΈ Configuration

See .env.example β€” that file documents the Bun self-host target, which remains single-tenant (META_ACCESS_TOKEN, META_PHONE_NUMBER_ID, META_WABA_ID, META_APP_SECRET, META_WEBHOOK_VERIFY_TOKEN, ECCOS_API_KEY; forwarding via SUBSCRIBER_WEBHOOK_URL / SUBSCRIBER_SECRET is optional β€” without it, inbound events are still stored, just not pushed).

The Workers target is account-scoped by default: on Workers, per-WABA Meta credentials and account keys live in the control plane instead; configure only META_APP_SECRET, META_WEBHOOK_VERIFY_TOKEN, and the admin bootstrap ECCOS_ADMIN_API_KEY, then follow docs/multi-tenancy.md. The Embedded Signup flow additionally uses META_APP_ID, META_ES_CONFIG_ID, and (for the dashboard button) the gateway's public GATEWAY_PUBLIC_URL.

πŸ› οΈ Development

bun run typecheck      # tsc --noEmit
bun run test           # Bun unit tests (parser, signature, connect, config)
bun run test:workers   # vitest-pool-workers integration tests for the Workers target
bun run check:site     # Astro check, static build, and generated-site link check
bun run dev:site       # Astro development server for apps/site

See CONTRIBUTING.md for the repository layout and conventions. If you're making assets or touching eccos.chat (apps/site/), the visual identity lives in docs/BRAND.md and the site's design rules β€” tokens, the two laws, motion, and the legal invariants β€” in docs/DESIGN-SYSTEM.md.

πŸ—ΊοΈ Roadmap

  • Embedded Signup /connect (account-bound coexistence) β€” Workers target
  • Operator console (apps/dashboard/) β€” separate Worker, RPC-only, Better Auth organizations
  • Bun-target parity for /connect (and an operator-console equivalent)
  • Workers account-scoped onboarding and isolation for multiple WABAs and phones β€” the registry/auth/connect foundation and local provisioning reconciliation are landed, but production-shaped two-number acceptance and release evidence remain. Commercial prerequisite: Eccos Cloud must not charge third parties (or start paid trials) before the complete isolation gate (eccos-v80) and its external dependencies are clear; see PRODUCTION-READINESS.md
  • Shard Workers state: one Durable Object per WABA with jurisdiction in the routing key (data-plane sharding; not paid multi-tenancy)
  • Account-key browser handoff for Tech Provider onboarding (connect clients' numbers)
  • Serverless storage path: per-tenant DO SQLite β†’ D1 for cross-tenant SQL (10 GB cap) β†’ Hyperdrive to external Postgres/MySQL only if required
  • Cloudflare Rate Limiting on the scoped Workers send API
  • Cloudflare Queues + dead-letter queue for outbound forwarding
  • R2 for outbound media
  • Outbound media + interactive message helpers

🀝 Contributing

Issues and PRs welcome β€” see CONTRIBUTING.md. For security reports, see SECURITY.md. Brand and asset guidelines live in docs/BRAND.md; the eccos.chat design system in docs/DESIGN-SYSTEM.md.

πŸ“„ License

MIT Β© Santiago GarcΓ­a Monsalve

About

Self-hostable, open-source WhatsApp gateway on the official WhatsApp Business API (Meta Cloud API). Coexistence built in, priced per number, no per-message fees.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages