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
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.
- π’ 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
/connectflow, 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.
| Eccos | Managed Cloud-API SaaS | Unofficial (Evolution API, WAHA, wuzapi) |
|
|---|---|---|---|
| WhatsApp API | β Official Cloud API | β Official Cloud API | |
| 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 |
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>/messageswith an account API key β Meta/{phone}/messages. An optionalIdempotency-Keyheader makes a retry safe: within 24 h a repeated key gets the first response back (Meta refusals included) without sending again, or409while it is in flight or its outcome is unknown (a502with"outcome": "unknown": no answer or a 5xx from Meta, so it may have been sent). The same key with a different body gets422 idempotency_key_reused. - Inbound: Meta calls
POST /webhooks/meta; Eccos verifiesX-Hub-Signature-256, normalizes the payload, and forwards{ events: [...] }to the subscriber URL configured for that WABA, signedX-Eccos-Signature: sha256=<hex>when a subscriber secret is configured. Failed forwards retry with exponential backoff. - Templates: Workers use
GET /v1/wabas/<WABA_ID>/templatesto proxy the WABA'smessage_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 |
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;
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 |
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.
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.
bun install
cp .env.example .env # fill in META_* + ECCOS_API_KEY + SUBSCRIBER_*
bun run dev # http://localhost:3000/healthTo 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.
cp .env.example .env # fill in values
docker compose up -dSQLite data is persisted in the eccos-data volume. The bundled .dockerignore keeps your
.env and local data out of the image.
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.jsoncThe 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).
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-contractviaworkspace:*. If Cloudflare's build can't resolve them, point the build's install/root at the repo root (runbun installat the root, deployapps/gateway). - Secrets: the button provisions bindings but not secret values β set the app-level secrets
(listed above) with
wrangler secret putor 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"), setDO_JURISDICTIONon the first deploy, before any production data exists. Changing it later derives a differentDurableObjectIdβ 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, theDurableObjectId/Alarm, and the Embedded Signup OAuth connection are not portable.
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.
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).
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.
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/siteSee 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.
- 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
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.
MIT Β© Santiago GarcΓa Monsalve
