Message Event

Triggered when a new message is received on your WhatsApp instance. This includes all message types: text, media, polls, calls, reactions, and more.

Event Type

message

Payload Structure

{
  "event": "message",
  "instanceId": "instance-uuid",
  "data": {
    "id": "message-db-id",
    "messageId": "whatsapp-message-id",
    "messageType": "text",
    "instanceId": "instance-uuid",
    "connectedNumber": "5511999999999",
    "timestamp": 1702500000,
    "fromMe": false,
    "viewOnce": false,
    "status": "RECEIVED",
    "chat": {
      "id": "chat-id",
      "jid": "[email protected]",
      "lid": null,
      "profilePictureUrl": "https://...",
      "name": "John Doe",
      "isGroup": false,
      "isLid": false
    },
    "sender": {
      "id": "sender-id",
      "jid": "[email protected]",
      "lid": null,
      "name": "John Doe",
      "profilePictureUrl": "https://..."
    },
    // Message type specific fields...
  }
}

Base Message Fields

All message types include these base fields:

Field	Type	Description
id	string	Internal database message ID
messageId	string	WhatsApp message ID
messageType	string	Type of message (see Message Types)
instanceId	string	Instance that received the message
connectedNumber	string	Phone number connected to the instance
timestamp	number	Unix timestamp (seconds)
fromMe	boolean	Whether the message was sent by the connected number
viewOnce	boolean | null	Whether this is a view-once message
status	string	Message status (see Status Values)
chat	object	Chat information
sender	object	Sender information
quotedMessage	object | undefined	Quoted/replied message (if any)

Chat Object

Field	Type	Description
id	string	Internal chat ID
jid	string | null	WhatsApp JID ([email protected])
lid	string | null	WhatsApp LID (local identifier)
profilePictureUrl	string | null	Profile picture URL
name	string | null	Chat name
isGroup	boolean	Whether this is a group chat
isLid	boolean	Whether using LID identifier

Sender Object

Field	Type	Description
id	string	Internal sender ID
jid	string | null	WhatsApp JID
lid	string | null	WhatsApp LID
name	string | null	Sender name
profilePictureUrl	string | null	Profile picture URL

Status Values

Status	Description
UNKNOWN	Status unknown
ERROR	Message failed to send
PENDING	Message is pending
SENT	Message sent to server
RECEIVED	Message delivered to recipient
READ	Message read by recipient
PLAYED	Audio/video played by recipient

---

Message Types

Text Message

{
  "messageType": "text",
  "text": "Hello, world!"
}

Field	Type	Description
text	string	Message text content

---

Image Message

{
  "messageType": "image",
  "mediaUrl": "https://storage.example.com/image.jpg",
  "thumbnailUrl": "https://storage.example.com/thumb.jpg",
  "mimetype": "image/jpeg",
  "filename": "photo.jpg",
  "fileSize": 102400,
  "caption": "Check this out!",
  "width": 1920,
  "height": 1080
}

Field	Type	Description
mediaUrl	string | null	URL to download the media
thumbnailUrl	string | null	URL to thumbnail image
mimetype	string	MIME type of the file
filename	string | null	Original filename
fileSize	number | null	File size in bytes
caption	string | null	Image caption
width	number | null	Image width in pixels
height	number | null	Image height in pixels

---

Video Message

{
  "messageType": "video",
  "mediaUrl": "https://storage.example.com/video.mp4",
  "thumbnailUrl": "https://storage.example.com/thumb.jpg",
  "mimetype": "video/mp4",
  "filename": "video.mp4",
  "fileSize": 5242880,
  "duration": 30,
  "caption": "Watch this!",
  "width": 1280,
  "height": 720,
  "gifPlayback": false
}

Field	Type	Description
mediaUrl	string | null	URL to download the video
thumbnailUrl	string | null	URL to thumbnail image
mimetype	string	MIME type
filename	string | null	Original filename
fileSize	number | null	File size in bytes
duration	number | null	Duration in seconds
caption	string | null	Video caption
width	number | null	Video width in pixels
height	number | null	Video height in pixels
gifPlayback	boolean | null	Whether to play as GIF

---

Audio Message

{
  "messageType": "audio",
  "mediaUrl": "https://storage.example.com/audio.ogg",
  "mimetype": "audio/ogg; codecs=opus",
  "fileSize": 51200,
  "duration": 15,
  "voiceNote": true
}

Field	Type	Description
mediaUrl	string | null	URL to download the audio
mimetype	string	MIME type
fileSize	number | null	File size in bytes
duration	number | null	Duration in seconds
voiceNote	boolean | null	Whether this is a voice note (PTT)

---

Document Message

{
  "messageType": "document",
  "mediaUrl": "https://storage.example.com/document.pdf",
  "thumbnailUrl": "https://storage.example.com/thumb.jpg",
  "mimetype": "application/pdf",
  "filename": "report.pdf",
  "fileSize": 1048576,
  "caption": "Here's the report",
  "pageCount": 10
}

Field	Type	Description
mediaUrl	string | null	URL to download the document
thumbnailUrl	string | null	URL to thumbnail
mimetype	string	MIME type
filename	string | null	Original filename
fileSize	number | null	File size in bytes
caption	string | null	Document caption
pageCount	number | null	Number of pages (PDF)

---

Sticker Message

{
  "messageType": "sticker",
  "mediaUrl": "https://storage.example.com/sticker.webp",
  "mimetype": "image/webp",
  "fileSize": 20480,
  "width": 512,
  "height": 512
}

Field	Type	Description
mediaUrl	string | null	URL to download the sticker
mimetype	string	MIME type
fileSize	number | null	File size in bytes
width	number | null	Sticker width in pixels
height	number | null	Sticker height in pixels

---

Location Message

{
  "messageType": "location",
  "latitude": -23.550520,
  "longitude": -46.633308,
  "name": "São Paulo",
  "address": "São Paulo, SP, Brazil",
  "thumbnailUrl": "https://..."
}

Field	Type	Description
latitude	number	Latitude coordinate
longitude	number	Longitude coordinate
name	string | null	Location name
address	string | null	Location address
thumbnailUrl	string | null	Map thumbnail URL

---

Live Location Message

{
  "messageType": "live_location",
  "latitude": -23.550520,
  "longitude": -46.633308,
  "accuracy": 10,
  "speed": 5.5,
  "degrees": 180,
  "caption": "On my way!",
  "sequenceNumber": 1,
  "timeOffset": 3600
}

Field	Type	Description
latitude	number	Latitude coordinate
longitude	number	Longitude coordinate
accuracy	number | null	Accuracy in meters
speed	number | null	Speed in m/s
degrees	number | null	Heading in degrees
caption	string | null	Location caption
sequenceNumber	number | null	Update sequence number
timeOffset	number | null	Seconds remaining for live location

---

Contact Message

{
  "messageType": "contact",
  "contacts": [
    {
      "name": "John Doe",
      "number": "5511999999999",
      "vcard": "BEGIN:VCARD..."
    }
  ]
}

Field	Type	Description
contacts	array	Array of contact objects
contacts[].name	string	Contact name
contacts[].number	string	Phone number
contacts[].vcard	string | null	Full vCard data

---

Reaction Message

{
  "messageType": "reaction",
  "reaction": "👍",
  "targetMessageId": "3EB0..."
}

Field	Type	Description
reaction	string	Emoji reaction (empty string to remove)
targetMessageId	string	ID of the message being reacted to

---

Edited Message

{
  "messageType": "edited",
  "editedContent": "Updated message text",
  "originalMessageId": "3EB0..."
}

Field	Type	Description
editedContent	string | null	New message content
originalMessageId	string | null	ID of the original message

---

Deleted Message

{
  "messageType": "deleted",
  "originalMessageId": "3EB0..."
}

Field	Type	Description
originalMessageId	string	ID of the deleted message

---

Poll Message

{
  "messageType": "poll",
  "pollName": "What's your favorite color?",
  "options": [
    { "id": "opt1", "name": "Red" },
    { "id": "opt2", "name": "Blue" },
    { "id": "opt3", "name": "Green" }
  ],
  "selectableCount": 1
}

Field	Type	Description
pollName	string	Poll question
options	array	Array of poll options
options[].id	string	Option ID
options[].name	string	Option text
selectableCount	number	Max selections (0 = unlimited, 1 = single choice)
messageSecret	string | undefined	Base64 encoded secret for vote decryption

---

Poll Vote Message

{
  "messageType": "poll_vote",
  "pollMessageId": "3EB0...",
  "pollChatJid": "[email protected]",
  "voterJid": "[email protected]",
  "selectedOptions": ["Red", "Blue"],
  "previousSelectedOptions": ["Green"]
}

Field	Type	Description
pollMessageId	string	ID of the poll message
pollChatJid	string	JID of the chat containing the poll
voterJid	string	JID of the voter
selectedOptions	string[]	Currently selected option names
previousSelectedOptions	string[] | undefined	Previous selections (for vote changes)

---

Call Message

{
  "messageType": "call",
  "callId": "call-uuid",
  "callStatus": "missed",
  "isVideo": false,
  "isGroupCall": false,
  "duration": 0
}

Field	Type	Description
callId	string	Unique call identifier
callStatus	string	Call status: offer, ringing, reject, accept, timeout, missed
isVideo	boolean	Whether this is a video call
isGroupCall	boolean	Whether this is a group call
duration	number | undefined	Call duration in seconds

---

Unsupported Message

{
  "messageType": "unsupported",
  "originalType": "protocolMessage",
  "reason": "Message type not supported"
}

Field	Type	Description
originalType	string	Original WhatsApp message type
reason	string	Reason why it's unsupported

---

Quoted Messages

When a message is a reply to another message, the quotedMessage field is included:

{
  "quotedMessage": {
    "id": "quoted-message-id",
    "sender": {
      "id": "sender-id",
      "jid": "[email protected]",
      "lid": null,
      "name": "Jane Doe",
      "profilePictureUrl": "https://..."
    },
    "message": {
      // Full message object of the quoted message
    }
  }
}