📥 Receive messages

We consider that you’ve run docker container and authenticated the session with QR code.

If you haven’t yet - please follow the steps from Quick Start →.

You must use Webhooks to receive messages from WhatsApp to your application.

Start a new session with configured message event in webhooks - call POST /api/sessions/ with the payload:

{
  "name": "default",
  "config": {
    "webhooks": [
      {
        "url": "https://webhook.site/11111111-1111-1111-1111-11111111",
        "events": [
          "message"
        ]
      }
    ]
  }
}

After that WAHA sends events (see below) about new messages to an endpoint you provided.

💡 You can open https://webhook.site and paste UUID from it to url field, and you’ll see all requests immediately in your browser to intercept the webhook’s payload.

Fields

chatId, from, to, participant

You can see some in from, to, and participant fields here’s what they mean:

123123123@c.us Phone numbers accounts - international phone number without + at the start and add @c.us at the end. For phone number 12132132131 the chatId is 12132132131@c.us
123123123@s.whatsapp.net can also appear in internal data for NOWEB, just convert it to @c.us to work with that properly. Kindly don’t use it in chatId when sending messages
12312312123133@g.us - Groups uses random number with @g.us at the end.
123123123@lid - is a hidden user ID, each user has a regular ID along with a hidden one. WhatsApp added that type of ID along with communities functionality.
123123123@newsletter - for 📰 WhatsApp Channels.

replyTo

If you get a message as a reply to another message, you’ll see replyTo field with the message ID that was replied to.

{
  "event": "message",
  "session": "default",
  "payload": {
    "id": "true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "timestamp": 1667561485,
    "from": "11111111111@c.us",
    "body": "Yes!",
    "replyTo": {
      "id": "BBBBBBBBBBBBBBB",
      "participant": "2222222222@c.us",
      "body": "Are you going?"
    }
  }
}

Webhooks

See the list of engines that support the feature ->.

Here’s examples of message-related events. Read Webhooks -> to find how to set them up.

message

Incoming message (text/audio/files)

{
  "event": "message",
  "session": "default",
  "payload": {
    "id": "true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "timestamp": 1667561485,
    "from": "11111111111@c.us",
    "fromMe": true,
    "to": "11111111111@c.us",
    "body": "Hi there!",
    "hasMedia": false,
    "ack": 1,
    "vCards": [],
    "_data": {
      "id": {
        "fromMe": true,
        "remote": "11111111111@c.us",
        "id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
        "_serialized": "true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
      },
      "body": "Hi there!",
      "type": "chat",
      "t": 1667561485,
      "notifyName": "MyName",
      "from": "11111111111@c.us",
      "to": "11111111111@c.us",
      "self": "in",
      "ack": 1,
      "isNewMsg": true,
      "star": false,
      "kicNotified": false,
      "recvFresh": true,
      "isFromTemplate": false,
      "pollInvalidated": false,
      "latestEditMsgKey": null,
      "latestEditSenderTimestampMs": null,
      "broadcast": false,
      "mentionedJidList": [],
      "isVcardOverMmsDocument": false,
      "isForwarded": false,
      "hasReaction": false,
      "ephemeralOutOfSync": false,
      "productHeaderImageRejected": false,
      "lastPlaybackProgress": 0,
      "isDynamicReplyButtonsMsg": false,
      "isMdHistoryMsg": false,
      "stickerSentTs": 0,
      "isAvatar": false,
      "requiresDirectConnection": false,
      "pttForwardedFeaturesEnabled": true,
      "isEphemeral": false,
      "isStatusV3": false,
      "links": []
    }
  }
}

message.any

Fired on all message creations, including your own. The payload is the same as for message event.

{
  "event": "message.any",
  "session": "default",
  "payload": {}
}

message.reaction

Receive events when a message is reacted to by a user (or yourself reacting to a message).

payload.reaction.text - emoji that was used to react to the message. It’ll be an empty string if the reaction was removed.
payload.reaction.messageId - id of the message that was reacted to.

{
    "event": "message.reaction",
    "session": "default",
    "me": {
        "id": "79222222222@c.us",
        "pushName": "WAHA"
    },
    "payload": {
        "id": "false_79111111@c.us_11111111111111111111111111111111",
        "from": "79111111@c.us",
        "fromMe": false,
        "participant": "79111111@c.us",
        "to": "79111111@c.us",
        "timestamp": 1710481111.853,
        "reaction": {
            "text": "🙏",
            "messageId": "true_79111111@c.us_11111111111111111111111111111111"
        }
    },
    "engine": "WEBJS",
    "environment": {
        "version": "2024.3.3",
        "engine": "WEBJS",
        "tier": "PLUS",
        "browser": "/usr/bin/google-chrome-stable"
    }
}

👉

NOWEB engine note - reactions were sent in 'message' and 'message.any' events, not it's available only in 'message.reaction'!

message.ack

Receive events when server or recipient gets the message, read or played it.

See details on Webhooks page ->.

{
  "event": "message.ack",
  "session": "default",
  "payload": {}
}

message.waiting

Happens when you see Waiting for this message. This may take a while. on your phone.

{
  "event": "message.waiting",
  "session": "default",
  "engine": "WEBJS",
  "payload": {
    "id": "true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "timestamp": 1667561485,
    "from": "11111111111@c.us",
    "fromMe": true,
    "to": "11111111111@c.us",
    ...
    "_data": {
      ...
    }
  }
}

message.revoked

See details on Webhooks page ->.

{
  "event": "message.ack",
  "session": "default",
  "payload": {
    "before": {
      "id": "some-id-here",
      "timestamp": "some-timestamp-here",
      "body": "Hi there!"
    },
    "after": {
      "id": "some-id-here",
      "timestamp": "some-timestamp-here",
      "body": ""
    }
  }
}

Files

When people send you media - images, voice messages, and documents - WAHA saves it in the file storage. In your application you must download it and use it as you want to. You can find the URL in media.url field.

For example, you can get the webhook like this with media value (we’ve skipped other fields):

{
  "event": "message",
  "session": "default",
  "payload": {
    "id": "true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "timestamp": 1667561485,
    "body": "Check this out (caption for the media)!",
    "from": "11111111111@c.us",
    "hasMedia": true,
    "media": {
      "url": "http://localhost:3000/api/files/true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.jpg",
      "mimetype": "image/jpeg",
      "filename": null,
      "error": null // if there was an error during file download
    }
  }
}

Then you can use the link to download the file http://localhost:3000/api/files/true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.jpg.

For documents (file attachments) there’s also filename field with the original file name.

{
  "event": "message",
  "session": "default",
  "payload": {
    "id": "true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "timestamp": 1667561485,
    "from": "11111111111@c.us",
    "media": {
      "url": "http://localhost:3000/api/files/true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.pdf",
      "filename": "some-file.pdf",
      "mimetype": "application/pdf",
      "error": null // if there was an error during file download
    }
  }
}

To configure the media.url you can use environment variables:

WHATSAPP_API_SCHEMA=https,
WHATSAPP_API_HOSTNAME=waha.example.com
WHATSAPP_API_PORT=3000

Or define the single

WAHA_BASE_URL=https://waha.example.com (only affects media.url)

By default, WAHA download all files that the account receive. If you want to limit files lifetime, specify file types for download or change directory for files - read more about file storage configuration and variables ->.

Endpoints

See the list of engines that support the feature ->.

Get messages

Read messages from the history - use GET /api/messages endpoint.

Accept the same parameters as 💬 Chats - Get messages from chat endpoint.

👉

We recommend using webhooks instead of constantly calling it to avoid performance issues.

curl -X 'GET' \
  'http://localhost:3000/api/messages?chatId=11111111111%40c.us&limit=1000&session=default' \
  -H 'accept: application/json'

Get message by id

You also can get message by id using 💬 Chats - Get message by id from chat endpoint.

GET /api/{session}/chats/{chatId}/messages/{messageId}?downloadMedia=true

👉

We recommend using webhooks instead to avoid performance issues.

Examples

Here’s few examples of how to receive messages in different languages:

Python guide ->

Do you use another language?

Please create a short guide how to handle webhook and send message after you finish your setup! You can create a pull request with your favorite language in the GitHub, in examples folder ->.

Edit this page on GitHub

📥 Receive messages

Fields #

chatId, from, to, participant #

replyTo #

Webhooks #

message #

message.any #

message.reaction #

message.ack #

message.waiting #

message.revoked #

Files #

Endpoints #

Get messages #

Get message by id #

Examples #