📥 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/start 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.

Some IDS

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 (@s.whatsapp.net can also appear in internal data, simply convert it to @g.us).
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.

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.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
    }
  }
}

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"
    }
  }
}

To configure the url you can use environment variables WHATSAPP_API_HOSTNAME and WHATSAPP_API_PORT.

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.

You also can get messages for chats by using Get messages from chat -> endpoint.

👉

We do not recommend using this method in production, consider using webhooks instead!

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

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

Some IDS #

Webhooks #

message #

message.any #

message.reaction #

message.ack #

message.revoked #

Files #

Endpoints #

Get messages #

Examples #