Socket Client

Use @open-wa/socket-client in a separate Node.js app when Easy API owns the WhatsApp browser session. In the current v5 runtime, commands use HTTP RPC and events use Server-Sent Events (SSE); the package keeps the familiar Client method and listener surface.

Install and connectCopy Anchor Link

Install the client and tsx in the Node.js app that will consume Easy API:

npm install @open-wa/socket-client@5.1.0
npm install --save-dev tsx

Start or locate an Easy API session, then connect using its base URL. Pass the API key when the server requires one:

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

const client = await SocketClient.connect('http://127.0.0.1:8080', process.env.OPENWA_API_KEY);

Keep the key in server-side configuration. The client sends it as X-API-Key on command requests and as api_key on the SSE URL because the standard EventSource API cannot set custom headers.

Run a consumerCopy Anchor Link

Save this as consumer.ts. It logs incoming messages and does not send a WhatsApp message:

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

const url = process.env.OPENWA_API_URL;
const apiKey = process.env.OPENWA_API_KEY;
if (!url) throw new Error('Set OPENWA_API_URL to the Easy API base URL');

const client = await SocketClient.connect(url, apiKey);

client.socket.on('connect', () => console.log('Easy API event stream connected'));
client.socket.on('disconnect', (reason) => console.warn('Event stream disconnected:', reason));
client.socket.on('connect_error', (error) => console.error('Event stream connection failed:', error));

await client.listen('onMessage', (message) => {
  console.log('Incoming message:', message.from, message.body);
});

console.log('Listening for messages; press Ctrl-C to stop');
process.once('SIGTERM', () => {
  client.close();
  process.exit(0);
});

Run it with the address of your Easy API instance:

OPENWA_API_URL='http://127.0.0.1:8080' npx tsx consumer.ts

If Easy API requires an API key, add OPENWA_API_KEY='your-key' to the command. For any example that calls sendText, replace the destination with a chat you control and run it only when you intend to send that message.

Call commands and listen for eventsCopy Anchor Link

The client exposes Easy API methods directly, and ask() is available when you prefer an explicit RPC call:

const result = await client.sendText('447700900123@c.us', 'Hello from SocketClient');
// Equivalent explicit command:
const sameResult = await client.ask('sendText', {
  to: '447700900123@c.us',
  content: 'Hello from SocketClient',
});

onMessage can also be registered through the listener helper:

await client.listen('onMessage', (message) => console.log(message.body));

Use a chat ID for a chat you control before running the send example. The client.socket event hooks report the SSE connection; they do not indicate whether an individual command succeeded.

Reconnect and shutdownCopy Anchor Link

SocketClient.connect() waits for the first SSE connection before resolving. The underlying event source retries a dropped stream; listeners are registered again after it reconnects. HTTP command calls can fail independently, so handle command errors at the call site.

If you need to initiate a reconnect yourself, call reconnect(). Use close() or disconnect() when stopping the consumer:

try {
  await client.reconnect();
} catch (error) {
  console.error('Could not reconnect:', error);
}

client.close();

If the first stream connection fails, connect() rejects with Unable to establish SSE connection. A stopped event stream does not by itself mean the WhatsApp session stopped; check Easy API health before restarting its runtime.

Cloudflare Session ProxyCopy Anchor Link

For remote access without opening an inbound port to Easy API, use the Cloudflare Session Proxy. SocketClient.connect() accepts its cf-proxy:// URL format.

Compatibility and securityCopy Anchor Link

This page covers the v5 HTTP RPC and SSE transport. Older v4 deployments and socket.io examples use a different transport; keep the client package aligned with the Easy API release you operate.

The consumer can call methods exposed by Easy API and receive runtime events. It cannot inspect the browser page or run browser-side code. Treat the API key as a server secret and restrict network access to the API.

RelatedCopy Anchor Link

• Easy API quick start
• Configuration and CLI
• Webhook payloads