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

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": {
      ...
    }
  }
}

Fields:

• hasMedia: true | false - indicates if the message has media attached
• media.url: http://localhost:8000/... - the URL to download the media
• _data - internal engine data, can be different for each engine

It’s possible to have hasMedia: true, but media: null - it means WAHA didn’t download media due to configuration.

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

message.ack#

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

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

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

Fields:

• hasMedia: true | false - indicates if the message has media attached
• media.url: http://localhost:8000/... - the URL to download the media

It’s possible to have hasMedia: true, but media: null - it means WAHA didn’t download media due to configuration.

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:

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

Or define

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

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 ⚙️ Configuration.

Endpoints#

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

Get messages#

Read messages from the history use API:

GET /api/messages

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

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

Examples#

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

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