open-wa logoopen-wa

SocketClient

Call methods and listen for messages from another Node.js app, against an Easy API running elsewhere.

SocketClient

Use @open-wa/socket-client when the WhatsApp session runs in an Easy API on another machine or process and your Node.js app wants the same methods and listeners as the SDK. Commands travel as HTTP requests and events arrive over Server-Sent Events (SSE).

Install and connect

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

npm install @open-wa/socket-client
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://localhost:8080', process.env.WA_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 consumer

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.EASY_API_URL;
const apiKey = process.env.WA_API_KEY;
if (!url) throw new Error('Set EASY_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:

EASY_API_URL='http://localhost:8080' npx tsx consumer.ts

EASY_API_URL is this example's own variable. If the Easy API has an API key, also set WA_API_KEY to the same value. 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 events

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 shutdown

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 proxy

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

Versions and security

v4 used socket.io, so v4 SocketClient examples don't work against a v5 Easy API. Install the same version of @open-wa/socket-client as the Easy API you connect to.

The consumer can call Easy API methods and receive session events. It can't reach the browser. Treat the API key as a server secret and restrict network access to the API.

Was this helpful?

Your answer includes the page path and docs version.

On this page