Webhook

Our service enables users to send WhatsApp messages. However, to receive WhatsApp messages, a webhook is required to send the details of incoming messages to a specified URL. Users can receive WhatsApp messages on their server by entering their webhook address in the user panel.

This documentation explains how to set up a webhook and the format of incoming WhatsApp messages.

The HTTP method for sending webhooks is POST.

Note: The data shown on this page is entirely fictional and provided solely to illustrate the webhook structure.

The webhook structure consists of three parts:

Attribute	Datatype	Description
Sender	String	Sender number with country code, e.g.: 971230001122
receiver	String	Receiver number with country code, e.g.: 971230001122
payload	JSON	Contains the main message content. The internal structure varies depending on the message type (e.g., text, image, etc.).

Sample Webhook (with empty payload):

Sender and Receiver Information:

Sender: The sender’s phone number with country code, e.g., Iran: “971230001122”
Receiver: The recipient’s phone number, e.g., Iran: “971230001122”
Payload: Contains the main message content. The internal structure varies depending on the message type (e.g., text, image, etc.).

				
					{
  "sender": "971230001122",
  "receiver": "971230001122",
  "payload": {....}
}

Payload Structure:

Attribute	Datatype	Description
Type	String	Different message types (e.g., text, image, reaction)
messageContextInfo	JSON	This feature contains information related to the message context or environment, such as the devices between which the message is sent. It has a fixed structure across various message types.

Sample fixed structure of messageContextInfo:

This section contains information about the message context, such as data related to the recipient’s device or other details.

deviceListMetadata:

Contains information about the device to which the message was sent and includes details related to the device list.

senderKeyHash: A hashed value referring to the sender’s device key. This key is used for message security and device validation.
senderTimestamp: The timestamp associated with the sender’s device, stored as a timestamp.
recipientKeyHash: A hashed value referring to the recipient’s device key. This key is used for message security and device validation.
recipientTimestamp: The timestamp associated with the recipient’s device, stored as a timestamp.
deviceListMetadataVersion: The version of deviceListMetadata, set to 2 in this case. This value may be used to ensure compatibility with different protocol versions.

				
					{
  "payload": {
    "conversation": "Hi To You",
    "messageContextInfo": {
      "deviceListMetadata": {
        "senderKeyHash": "Tganvset6wuIkw==",
        "senderTimestamp": "1719631314",
        "recipientKeyHash": "aZ8c13lG1M+F5Q==",
        "recipientTimestamp": "1750189856"
      },
      "deviceListMetadataVersion": 2
    }
  },
  "sender": "971230001122",
  "receiver": "971230001122"
}

Types:

Attribute	Datatype	Description
conversation	String	Text message
extendedTextMessage	JSON	Advanced text message
reactionMessage	JSON	Reaction (feedback) message
imageMessage	JSON	Photo/image message
audioMessage	JSON	Audio message
videoMessage	JSON	Video message
documentMessage	JSON	Document message
protocolMessage	JSON	Special message for managing system events, such as message deletion

Example for conversation (text message):

Conversation:
The text content of the sent message.
messageContextInfo:
As mentioned, it has a fixed structure across all webhooks.

				
					{
  "payload": {
    "conversation": "Hi To You",
    "messageContextInfo": {...}
  },
  "sender": "971230001122",
  "receiver": "971230001122"
}

Example for extendedTextMessage (advanced text message):

This section contains information about a text message accompanied by specific features.

Text:
The main message text, set to “Hi To You” in this case, which specifies the message content.

ContextInfo:
Additional or contextual information about the message, including settings for ephemeral messages and disappearing mode.

EphemeralSettingTimestamp:
A timestamp (in seconds since 1970) indicating when the ephemeral message settings were applied. This shows when the message was set to ephemeral mode.
DisappearingMode:
Specifies the disappearing mode of the message.
Initiator:
Indicates the source or initiator of the disappearing mode. Here, it is set to CHANGED_IN_CHAT, meaning the mode was changed within the chat.

InviteLinkGroupTypeV2:
The type of group invite link, set to “DEFAULT” in this case. This indicates that the group link is of the default type. This feature is typically used for managing group invite links in WhatsApp.

				
					{
  "payload": {
    "extendedTextMessage": {
      "text": "Hi To You",
      "contextInfo": {
        "ephemeralSettingTimestamp": "1718132600",
        "disappearingMode": {
          "initiator": "CHANGED_IN_CHAT"
        }
      },
      "inviteLinkGroupTypeV2": "DEFAULT"
    },
    "messageContextInfo": {...}
  },
  "sender": "971230001122",
  "receiver": "971230001122"
}

Example for reactionMessage (reaction or feedback type):

In this message structure, the message is a Reaction Message, which is a short response (e.g., an emoji) to a previous message.

key:
Key information about the original message being reacted to.

remoteJid: The phone number or identifier of the original message being reacted to (in WhatsApp’s standard format).
fromMe: Indicates whether the message is from the original sender (in this case, the reactor).
id: The identifier of the original message being reacted to.

text:
The emoji sent as the reaction, set to 😂 (Unicode: \ud83d\ude02) in this case.

senderTimestampMs:
The time the reaction was sent, in milliseconds.

				
					{
  "payload": {
    "reactionMessage": {
      "key": {
        "remoteJid": "971230001122@s.whatsapp.net",
        "fromMe": true,
        "id": "8EB021ABC243FDB04B77A0514D4E60T1"
      },
      "text": "😂",
      "senderTimestampMs": "1720173708718"
    },
    "messageContextInfo": {...}
  },
  "sender": "971230001122",
  "receiver": "971230001122"
}

Example for imageMessage (photo/image message):

This structure represents an image message that includes comprehensive details about the image, such as URL, file type, size, and file security settings. It also records information about disappearing message settings and the option for one-time viewing of the image.

imageMessage:
This section contains details related to the image message.

url:
The URL link to the image, provided by WhatsApp’s server for downloading the image.
mimetype:
The file type of the image, set to image/jpeg in this case, indicating the image format (JPEG).
fileSha256:
The SHA-256 hash of the image file. This serves as a unique identifier for the image and ensures file security.
fileLength:
The size of the image file in bytes. In this example, it is 43,809 bytes.
height and width:
The height (476 pixels) and width (638 pixels) of the image, specifying its dimensions.
mediaKey:
The media key used to decrypt the image. This key is attached to the file for security purposes.
fileEncSha256:
The SHA-256 hash of the encrypted file. This is used to validate the encrypted file.
directPath:
The direct path to the file on WhatsApp’s server, used to access the image.
mediaKeyTimestamp:
The timestamp of when the media key was created, in milliseconds.
jpegThumbnail:
A thumbnail image in base64 format, representing a compressed, smaller version of the original image. This thumbnail is useful for quick message previews.
contextInfo:
Contains contextual information for the message.
- ephemeralSettingTimestamp:
  The timestamp of when the auto-disappearing message setting was applied, recorded in milliseconds.
- disappearingMode:
  The disappearing message settings, set to CHANGED_IN_CHAT here, indicating that this setting was activated within the chat.
viewOnce:
If set to true, it indicates that the image can only be viewed once. In this example, it is false, meaning the image can be viewed multiple times.

				
					{
  "payload": {
    "imageMessage": {
      "url": "https:\/\/mmg.whatsapp.net\/o1\/v&_nc_sid=000000&mms3=true",
      "mimetype": "image\/jpeg",
      "fileSha256": "Tpjsk0rX\gS0I\/9KIwKrp0J0=",
      "fileLength": "43809",
      "height": 476,
      "width": 638,
      "mediaKey": "YIgynsDbw6kS96xXsIL5wZR4=",
      "fileEncSha256": "TMtfrreE+2PkzSoanMfRAOWTjPf1Ig=",
      "directPath": "\/o1\/v\/t62.7118-24\/f1\/m269\/up-oil-image-63377&_nc_sid=000000",
      "mediaKeyTimestamp": "1720237239",
      "jpegThumbnail": "\/9j\/4AD\/2wBgMCAgIDAwYEAgGBgUG....",
      "contextInfo": {
        "ephemeralSettingTimestamp": "1718132600",
        "disappearingMode": {
          "initiator": "CHANGED_IN_CHAT"
        }
      },
      "viewOnce": false
    },
    "messageContextInfo": {...}
  },
  "sender": "971230001122",
  "receiver": "971230001122"
}

Example for audioMessage (audio message):

This structure represents an Audio Message in WhatsApp webhook messages, containing details such as the download link, file type, file length, duration, decryption key, and forwarding status.

audioMessage:
This section contains details related to the audio message.

url:
The URL link for downloading the audio file, provided by WhatsApp’s server.
mimetype:
The file type of the audio, set to audio/ogg; codecs=opus in this case, indicating the OGG audio format with the Opus codec.
fileSha256:
The SHA-256 hash of the audio file, used for validation and unique identification of the file.
fileLength:
The size of the audio file in bytes (in this case, 36,459 bytes).
seconds:
The duration of the audio file in seconds (in this case, 15 seconds).
ptt:
Set to false, indicating that this is not a Push-to-Talk (PTT) message but a regular audio message.
mediaKey:
The media key used to decrypt the audio file.
fileEncSha256:
The SHA-256 hash of the encrypted file, used to ensure the integrity of the encrypted file.
directPath:
The direct path to the file on WhatsApp’s server for quick access.
mediaKeyTimestamp:
The timestamp of when the media key was created, in milliseconds since 1970, typically used to reference the file’s sending time.
contextInfo:
Contains contextual information about the message.
- forwardingScore:
  A value of 1 indicates that the message has been forwarded once.
- isForwarded:
  Set to true, indicating that this message was forwarded from elsewhere.
waveform:
A visual representation of the audio file in base64 format, providing a view of the audio’s waveform changes.

				
					{
  "payload": {
    "audioMessage": {
      "url": "https:\/\/mmg.whatsapp.net\/v\VPAV57&oe=66B05AE9&_nc_sid=5e03e0&mms3=true",
      "mimetype": "audio\/ogg; codecs=opus",
      "fileSha256": "VCrwiP3YKAsk5uocT8l7c+vnZYiEvCG4ZncjlSuY7G4=",
      "fileLength": "36459",
      "seconds": 15,
      "ptt": false,
      "mediaKey": "BamF7Hwhvr2IjdjmUpQ8onhCx4=",
      "fileEncSha256": "6z1+zs2RXq8hA6xeu0kklFDNMNQfWdU=",
      "directPath": "\/v\/t62.71442PAV57&oe=66B05AE9&_nc_sid=5e03e0&_nc_hot=1720249773",
      "mediaKeyTimestamp": "1720249701",
      "contextInfo": {
        "forwardingScore": 1,
        "isForwarded": true
      },
      "waveform": "RDRBQRo+Ij89NEM1Jzs5Qk0OkBCIkUuJQ=="
    },
    "messageContextInfo": {....}
  },
  "sender": "971230001122",
  "receiver": "971230001122"
}

Example for videoMessage (video message):

This message structure provides details about a video message, including the download link, file type, video size and duration, decryption key, and disappearing mode settings. It also includes a thumbnail and streaming metadata for video display and playback.

videoMessage:
This section contains details related to the video message.

url:
The URL link for downloading the video file, provided by WhatsApp’s server.
mimetype:
The file type of the video, set to video/mp4 in this case, indicating the MP4 video format.
fileSha256:
The SHA-256 hash of the video file, used for unique identification and file validation.
fileLength:
The size of the video file in bytes, set to 4,656,013 bytes in this example.
seconds:
The duration of the video in seconds, set to 96 seconds in this case.
mediaKey:
The media key used to decrypt the video file.
gifPlayback:
Set to false, indicating that the video is not played as a GIF but as a standard video.
height and width:
The dimensions of the video, with a height of 1,018 pixels and a width of 1,918 pixels.
fileEncSha256:
The SHA-256 hash of the encrypted file, used to ensure the integrity of the encrypted file.
directPath:
The direct path to the file on WhatsApp’s server for quick access.
mediaKeyTimestamp:
The timestamp of when the media key was created, in milliseconds since 1970, typically used to reference the file’s sending time.
jpegThumbnail:
A thumbnail of the video in base64 format, serving as a preview of the video.
contextInfo:
Contains contextual information about the message.
- ephemeralSettingTimestamp:
  The timestamp of when the disappearing message mode was set.
- disappearingMode:
  Indicates that changes to the disappearing message mode occurred within the chat.
streamingSidecar:
Metadata related to video streaming, provided in base64 format, used to facilitate playback of the video during streaming.
viewOnce:
Set to false, indicating that the video is not limited to one-time viewing and can be played multiple times.

				
					{
  "payload": {
    "videoMessage": {
      "url": "https:\/\/mmg.whatsapp.net\/v\/t62.7101SlZ4a&oe=66B080EE&_nc_sid=5e03e0&mms3=true",
      "mimetype": "video\/mp4",
      "fileSha256": "FLR7t9fFIkZrd5Fr4dqkqxqocwVQIyEcqiN6O7s=",
      "fileLength": "4656013",
      "seconds": 96,
      "mediaKey": "AFf+pZPcwLzaD7sbbLkxz9lQaVdsntCCgG06Ak=",
      "gifPlayback": false,
      "height": 1018,
      "width": 1918,
      "fileEncSha256": "cFJI+huvMDTOSi7LKfE\/ewb8MVp2gQ7gg=",
      "directPath": "\/v\/t62.7161-24\/3a&oe=66B080EE&_nc_sid=5e03e0",
      "mediaKeyTimestamp": "1720262804",
      "jpegThumbnail": "\/9j\/4AAQSkZJTEUAAQEAAAAQwAABtb....",
      "contextInfo": {
        "ephemeralSettingTimestamp": "1708263184",
        "disappearingMode": {
          "initiator": "CHANGED_IN_CHAT"
        }
      },
      "streamingSidecar": "U2EL3rLHbarq\/++Zpes7b7sWpCeQdp....",
      "viewOnce": false
    },
    "messageContextInfo": {....}
  },
  "sender": "971230001122",
  "receiver": "971230001122"
}

Example for documentMessage (document message):

This document message structure contains comprehensive information about a PDF file, including the download link, file type, title, size, page count, decryption details, and thumbnail data.

documentMessage:
Contains details of the sent document (PDF file).

url:
The link to download the document file from WhatsApp’s server.
mimetype:
The file type of the document, set to application/pdf, indicating that it is a PDF file.
title:
The title of the file, set to “ASNA K”.
fileSha256:
The SHA-256 hash of the file, used to ensure file integrity and authenticity.
fileLength:
The size of the file in bytes, set to 7,872,857 bytes (approximately 7.8 MB).
pageCount:
The number of pages in the PDF file, set to 113 pages.
mediaKey:
The media key used to decrypt the document file.
fileName:
The name of the file including its extension, set to “ASNA K.pdf”.
fileEncSha256:
The SHA-256 hash of the encrypted file, used to verify the integrity of the encrypted file.
directPath:
The direct path to the file on WhatsApp’s server for faster access.
mediaKeyTimestamp:
The timestamp of when the media key was created, in milliseconds since 1970.
thumbnailDirectPath, thumbnailSha256, and thumbnailEncSha256:
These fields are used to manage the thumbnail of the PDF file.
- thumbnailDirectPath: The direct path to the thumbnail image.
- thumbnailSha256: The SHA-256 hash of the thumbnail image.
- thumbnailEncSha256: The SHA-256 hash of the encrypted thumbnail image.
jpegThumbnail:
A preview of the PDF file’s thumbnail in base64 format, used to display a small image of the file.
contextInfo:
Contains contextual information about the message.
- forwardingScore: Indicates the number of times the message has been forwarded.
- isForwarded: Indicates that the message was forwarded from another sender.
thumbnailHeight and thumbnailWidth:
The dimensions of the thumbnail image, set to 51 pixels (height) and 72 pixels (width).

				
					{
  "payload": {
    "documentMessage": {
      "url": "https:\/\/mmg.whatsapp.net\/v\/t62.7106D7D&_nc_sid=5e03e0&mms3=true",
      "mimetype": "application\/pdf",
      "title": "ASNA K",
      "fileSha256": "CggKx3vfgYhRKMoY7akSSgHAlXwhTxLcREuiHOEsf00=",
      "fileLength": "7872857",
      "pageCount": 113,
      "mediaKey": "A9Ny5kV\/TbNh5nMTclqOCMYG9uUyp\/iTnNAcVlc\/KD8=",
      "fileName": "ASNA K.pdf",
      "fileEncSha256": "O93zqESwsBjyL86tDebNrxmdenXOFZ7ahQAPNPtXH9s=",
      "directPath": "\/v\/t62.7119-24\/13156835_827471092681780_49707794700778200....",
      "mediaKeyTimestamp": "1720259645",
      "thumbnailDirectPath": "\/v\/t62.36145-24\/18899962_351461741132911_7....",
      "thumbnailSha256": "2DTGGM43NK6yE1g9YzYGvhXG0OG\/ZKZnMQC4RFzARqI=",
      "thumbnailEncSha256": "9+X+Tubhk3rFu4GB20p79VHWdOlsbsO68qMiUTCLGjs=",
      "jpegThumbnail": "\/9j\/4AAQSkZJRgABAQAAAQABAAD\/2wCEABERERESERMVFRM....",
      "contextInfo": {
        "forwardingScore": 1,
        "isForwarded": true
      },
      "thumbnailHeight": 51,
      "thumbnailWidth": 72
    },
    "messageContextInfo": {....}
  },
  "sender": "971230001122",
  "receiver": "971230001122"
}

Example of a protocolMessage: (a special type of message for managing system events like message deletion)

In this JSON structure, a Protocol Message with the type REVOKE is shown, which is used to revoke or delete a specific message in WhatsApp.

protocolMessage:

This section indicates that the message is of the protocol type and performs a specific operation on another message.

key:

Contains information that identifies the target message for revocation.

remoteJid: The unique identifier related to the recipient or group, which in this case is “[نشانی ایمیل برداشته شد]”.
fromMe: If true, it indicates that the message was sent by the original sender (the user themselves).
id: The unique identifier of the message that is to be revoked, “42BB799986C8D653735C048BE9E4CD36”.

type:

The type of the protocol message, which in this case is “REVOKE” and indicates that the specified message should be revoked or deleted.

				
					{
  "payload": {
    "protocolMessage": {
      "key": {
        "remoteJid": "971230001122@s.whatsapp.net",
        "fromMe": true,
        "id": "42BB788986C1D653732C048BC9E4CD36"
      },
      "type": "REVOKE"
    },
    "messageContextInfo": {....}
  },
  "sender": "971230001122",
  "receiver": "971230001122"
}