open-wa logoopen-wa

Receive messages

Choose how your code hears about incoming WhatsApp messages, with onMessage, the event stream or a webhook, and set it up.

Receive messages

There are three ways to hear about incoming messages. Pick by where your code runs:

Your codeUseWhy
Runs in Node.js and starts the session with create()client.onMessageThe handler runs in the same process, with no network hop and nothing to secure.
Runs anywhere and keeps a connection open to the Easy APIThe event stream, GET /api/eventsOne long-lived HTTP request; nothing has to be reachable from the internet.
Is a backend, CRM or no-code tool that receives HTTP requestsA webhookopen-wa calls your URL, with retries and optional durable delivery.

All three deliver the same message object: from is the chat to reply to, body is the text (or caption for media), id identifies the message, and fromMe is true for messages the linked account sent. See data models for every field.

In Node.js: onMessage

bot.mts
import { create } from '@open-wa/wa-automate';

const client = await create({ sessionId: 'support' });

client.onMessage(async (message) => {
  if (message.isGroupMsg) return;
  console.log(`${message.from}: ${message.body}`);
  if (message.body?.toLowerCase() === 'hours') {
    await client.reply(message.from, 'We are open 9am to 5pm, Monday to Friday.', message.id);
  }
});

onMessage fires for messages other people send you. Use onAnyMessage when you also want the ones the linked account sends, and onAck to follow delivery and read receipts. Each listener returns a handle with off() to stop it. Listeners accept queue options such as { concurrency: 1 } when you need to handle messages one at a time; see best practices.

For a complete bot, see run a support bot. A Node.js app that talks to a remote Easy API can use the same listener names through SocketClient.

Over HTTP: the event stream

The Easy API streams events as server-sent events. Pick the events you want with topics:

curl --no-buffer "http://127.0.0.1:8080/api/events?topics=message.received,ack.changed" \
  -H "X-API-Key: $WA_API_KEY"

Each event arrives as one frame:

id: 42
event: message.received
data: {"id":"42","event":"message.received","payload":{"message":{"id":"false_447700900123@c.us_3EB0C7D5E4A1B2","from":"447700900123@c.us","body":"hours","fromMe":false}},"ts":1763560000123,"sessionId":"support"}

The message is at payload.message. Leave out topics to receive every event. The stream doesn't replay events you missed while disconnected, so reconnect promptly and use a webhook with durability when you can't afford gaps. Most languages have an SSE client; in the browser, EventSource can't send headers, so add ?api_key= to the URL instead, and only from a trusted page.

To reply, call the HTTP API with the sender's chat ID:

curl http://127.0.0.1:8080/api/messages/sendText \
  -H "X-API-Key: $WA_API_KEY" -H 'Content-Type: application/json' \
  --data '{"to":"447700900123@c.us","content":"We are open 9am to 5pm."}'

To your backend: a webhook

Load the webhook plugin in wa.config.js and open-wa will POST each event to your URL:

wa.config.js
export default {
  plugins: ['@open-wa/integration-webhook'],
  pluginConfig: {
    webhook: {
      url: 'https://receiver.example/webhooks/open-wa',
      events: ['message.received'],
      headers: { 'X-Webhook-Secret': process.env.WEBHOOK_SECRET },
    },
  },
};

Receive webhooks covers the envelope, a receiver that stores each event once, and retries. The Python bot shows a full webhook bot.

Was this helpful?

Your answer includes the page path and docs version.

On this page