Receive messages
Choose how your code hears about incoming WhatsApp messages, with onMessage, the event stream or a webhook, and set it up.
There are three ways to hear about incoming messages. Pick by where your code runs:
| Your code | Use | Why |
|---|---|---|
Runs in Node.js and starts the session with create() | client.onMessage | The handler runs in the same process, with no network hop and nothing to secure. |
| Runs anywhere and keeps a connection open to the Easy API | The event stream, GET /api/events | One long-lived HTTP request; nothing has to be reachable from the internet. |
| Is a backend, CRM or no-code tool that receives HTTP requests | A webhook | open-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
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:
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.
Related
- Messages for replies, mentions and acknowledgements
- Groups and direct messages for filtering group chats
- Chat IDs for the
@c.us,@g.usand@lidformats
Was this helpful?
Your answer includes the page path and docs version.
