@open-wa/integration-cloudflare

Source: integrations/cloudflare/README.md

@open-wa/cf-proxy is the Cloudflare Worker reverse tunnel for open-wa Easy API sessions. The local runtime opens an outbound WebSocket to the Worker, so the local machine does not need an inbound port. The Worker remains a remotely reachable authenticated entry point.

The package is private to the open-wa monorepo. It is not an npm consumer package, so deployment starts from this repository's packages/cf-proxy entrypoint.

Topology and authenticationCopy Anchor Link

Remote consumer --HTTPS/WebSocket--> Cloudflare Worker --Durable Object--> local TunnelClient --HTTP--> Easy API

The Worker uses two independent secrets:

• UPSTREAM_TOKEN authenticates the local runtime at /sessions/:sessionId/upstream.
• CONSUMER_TOKEN authenticates remote callers on other session paths.

The Worker routes each session ID to a Durable Object. An absent upstream returns 503 Session offline; a request that waits more than 30 seconds returns 504 Gateway Timeout from session upstream. Hibernation can reduce active Durable Object compute while the connection is idle, but it does not make Worker requests, storage, egress, domains, or account-plan charges free. Check Cloudflare Workers pricing for the account and plan in use.

Deploy the WorkerCopy Anchor Link

From a clean checkout:

git clone https://github.com/open-wa/wa-automate-nodejs.git
cd wa-automate-nodejs
corepack enable
pnpm install
cd packages/cf-proxy
pnpm exec wrangler login
pnpm exec wrangler whoami

wrangler.jsonc binds the SESSION_TUNNEL Durable Object to SessionTunnel. Set the secret values through Wrangler without committing them:

export OPENWA_PROXY_UPSTREAM_TOKEN="$(openssl rand -hex 32)"
export OPENWA_PROXY_CONSUMER_TOKEN="$(openssl rand -hex 32)"
printf '%s' "$OPENWA_PROXY_UPSTREAM_TOKEN" | pnpm exec wrangler secret put UPSTREAM_TOKEN
printf '%s' "$OPENWA_PROXY_CONSUMER_TOKEN" | pnpm exec wrangler secret put CONSUMER_TOKEN
pnpm exec wrangler deploy

Record the deployed hostname as OPENWA_PROXY_HOST, for example https://open-wa-proxy.<account>.workers.dev. The local runtime needs the upstream value; remote callers need the consumer value.

Contributors with an existing checkout can run pnpm install from the repository root and use pnpm --filter @open-wa/cf-proxy exec wrangler whoami followed by pnpm --filter @open-wa/cf-proxy exec wrangler deploy. Run secret put again only when rotating a value.

Attach a local sessionCopy Anchor Link

Run the CLI on the machine that owns the WhatsApp browser session:

export OPENWA_PROXY_HOST='https://open-wa-proxy.<account>.workers.dev'
npx @open-wa/wa-automate@5.1.0 \
  --session-id sales \
  --port 8080 \
  --proxy-host "$OPENWA_PROXY_HOST" \
  --proxy-token "$OPENWA_PROXY_UPSTREAM_TOKEN"

The CLI converts the HTTPS host to a WebSocket host and connects to /sessions/sales/upstream. WhatsApp Web and Easy API stay on the local machine; the Worker does not run the browser or change session readiness.

Consume a sessionCopy Anchor Link

Use the consumer token in an Authorization: Bearer header rather than a URL query when making HTTP calls:

curl -i \
  "$OPENWA_PROXY_HOST/sessions/sales/api/getHostNumber" \
  -H "Authorization: Bearer $OPENWA_PROXY_CONSUMER_TOKEN"

For a command that is protected by the local Easy API key, send both credentials:

curl -i -X POST \
  "$OPENWA_PROXY_HOST/sessions/sales/api/sendText" \
  -H "Authorization: Bearer $OPENWA_PROXY_CONSUMER_TOKEN" \
  -H "X-API-Key: $OPENWA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"args":["1234567890@c.us","Hello through Cloudflare"]}'

Node clients can use the compatibility URL. The client converts it to the tunnel WebSocket and sends the consumer token to /sessions/<sessionId>/connect:

import { SocketClient } from '@open-wa/socket-client';

const client = await SocketClient.connect(
  `cf-proxy://open-wa-proxy.<account>.workers.dev?sessionId=sales&token=${encodeURIComponent(process.env.OPENWA_PROXY_CONSUMER_TOKEN)}`,
);
console.log(await client.getHostNumber());

The remote caller still receives the local Easy API's authentication or readiness response. A valid consumer token does not replace the local X-API-Key.

TroubleshootingCopy Anchor Link

DevelopmentCopy Anchor Link

pnpm --filter @open-wa/cf-proxy dev

The Worker entrypoint is packages/cf-proxy/src/index.ts; the Durable Object is src/tunnel-do.ts.

DocumentationCopy Anchor Link

See the Cloudflare Session Proxy guide.

LicenseCopy Anchor Link

H-DNH 1.1 - Hippocratic + Do Not Harm