Whatsapp API api

Check whether a number is registered

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:37 +0000

Check whether a number is registered

This command checks whether a number is registered in WhatsApp.

Request command

To check a number, send a POST request to:

https://whatsgate.org/api/v1/check

Request body object

The request body must contain the following object:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "number": "79991112233"
}

WhatsappID - WhatsApp identifier in the system
number - phone number in digits only, including country code, for example 79991112233

Response object

Successful response object

{
  "result": "OK",
  "data": true
}

data - if true, the number is registered in WhatsApp; if false, it is not.

Incoming events processing (events-get)

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:10 +0000

Incoming events processing (events-get)

This command is used to request and retrieve a list of incoming events, such as:

incoming messages (action = message)
message read/update (action = ack)
incoming media file (action = media)
message sent (action = sent) - this event appears only for asynchronous sending
error (action = error)
WhatsApp disconnect and session removal (action = disconnect)

Request command

To retrieve the event list, send a POST request to:

https://whatsgate.org/api/v1/events-get

Request body object

The request body accepts the following object:

{
  "WhatsappID" : "XXXXXXXXXXXXX",
  "date" : "YYYY-MM-DD HH:MM:SS",
  "action" : "message",
  "page_cnt" : "10",
  "page" : "1"
}

All fields in this object are optional, meaning an empty object is enough to get the full list of events. Fields WhatsappID and action are filters, and date limits events by date. The date is typically used like this: after reading events, take the date of the last event and pass it in the next request as date to fetch only newer events.

WhatsappID - filter by WhatsApp identifier; uses exact match and returns events for the specified session. If omitted, the system returns events for all sessions, including deleted ones.
date - limits events by the specified date. A common pattern is to reuse the latest received event date in the next request to get fresh events only.
action - event type filter. Can be one of:
- message - incoming message.
- ack - message status update.
- media - incoming media file.
- sent - message sent (only when sending asynchronously)
- error - error
- disconnect - WhatsApp disconnect and session deletion
- create - outgoing message
page_cnt - maximum number of events per response page. Default is 10, maximum is 100.
page - response page number. Default is 1

Response object

Successful response object

{
  "result": "OK",
  "pages" : 1,
  "elements" : 2,
  "page" : 1,
  "data" : [
     // 
  ]
}

result - contains “OK” when the request succeeds
pages - number of pages for the given filters
elements - number of matching elements (event count)
page - current page number
data - contains an array of objects representing events.

Chat information

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:06 +0000

Chat information

This command returns information about all active chats for the client. The response includes the contact list (including groups) and group participants with their permissions.

Request command

To retrieve chat info, send a POST request to:

https://whatsgate.org/api/v1/get-chats

Request body object

The request body must contain:

{
  "WhatsappID": "YOUR_WHATSAPP_ID"
}

WhatsappID - WhatsApp identifier in the system

Response object

Successful response object

{
  "result": "OK",
  "data": [
    { ... CHAT_CONTACT_OBJECT ... }
    ...
  ]
}

data - contains an array of chat contact objects or chat group objects

Chat contact object

{
  "id" : "79991112233@c.us",
  "name" : "Vasily",
  "isGroup" : false,
  "isReadOnly" : false,
  "unreadCount" : 0,
  "timestamp" : 1662710454,
  "pinned" : false,
  "isMuted" : false,
  "muteExpiration" : 0
}

id - contact identifier
name - contact name
isGroup - whether this is a group; false for contacts
isReadOnly - whether sending messages to this recipient is blocked; true = blocked, false = allowed
unreadCount - number of unread messages in this chat
timestamp - time of last activity in Unix timestamp format
pinned - whether the chat is pinned; true = yes, false = no
isMuted - whether notifications are muted for this chat; true = muted, false = enabled
muteExpiration - number of seconds until notifications are enabled again (if muted)

Chat group object

{
  "id" : "4239048293082@g.us",
  "name" : "Test group",
  "isGroup" : true,
  "isReadOnly" : false,
  "unreadCount" : 0,
  "timestamp" : 1662616476,
  "pinned" : false,
  "isMuted" : false,
  "muteExpiration" : 0
  "groupMetadata" : {... GROUP_METADATA_OBJECT ...}
 }

id - group identifier
name - group name
isGroup - whether this is a group; true for groups
isReadOnly - whether sending messages to this group is blocked; true = blocked, false = allowed
unreadCount - number of unread messages in this group
timestamp - time of last activity in Unix timestamp format
pinned - whether the group is pinned; true = yes, false = no
isMuted - whether notifications are muted for this group; true = muted, false = enabled
muteExpiration - number of seconds until notifications are enabled again (if muted)
groupMetadata - group metadata object

Group metadata object

{
  "id" : "4239048293082@g.us",
  "creation" : 1658328976,
  "owner" : "79991112233@c.us",
  "size" : 3,
  "participants" : [
     { ... PARTICIPANT_OBJECT ...}
     ...
  ]
}

id - group identifier
creation - group creation date in Unix timestamp format
owner - group owner identifier
size - number of group participants
participants - array of participant objects

Group participant object

{
  "id" : "79156666555@c.us",
  "isAdmin" : true,
  "isSuperAdmin" : false
}

id - participant contact identifier
isAdmin - whether this contact is a group admin; true = yes, false = no
isSuperAdmin - whether this contact is a super admin; true = yes, false = no

Full response example

{
  "result":"OK",
  "data" : [
    { 
      "id" : "79999999999@c.us", 
      "name" : "+7 999 999-99-99", 
      "isGroup" : false,
      "isReadOnly" : false,
      "unreadCount" : 0,
      "timestamp" : 1662710454,
      "pinned" : false,
      "isMuted" : false,
      "muteExpiration" : 0
    },
    {
      "id" : "4239048293082@g.us",
      "name" : "Test group",
      "isGroup" : true,
      "isReadOnly" : false,
      "unreadCount" : 0,
      "timestamp" : 1662616476,
      "pinned" : false,
      "isMuted" : false,
      "muteExpiration" : 0,
      "groupMetadata" : {
         "id" : "4239048293082@g.us",
         "creation" : 1658328976,
         "owner" : "79999999999@c.us",
         "size" : 0,
         "participants" : [
           {
             "id" : "79999999999@c.us",
             "isAdmin" : true,
             "isSuperAdmin" : false
           },
           { 
             "id" : "79991112233@c.us",
             "isAdmin" : false,
             "isSuperAdmin":false
           }
        ]
      }
    }
  ]
}

Retrieving chat message history

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:19 +0000

Retrieving chat message history

This command retrieves message history from the specified chat. You can get up to 100 messages, no older than 90 days. The request is synchronous, meaning the response is returned directly to the request, not to a WebHook.

Request command

To retrieve chat history, send a POST request to:

https://whatsgate.org/api/v1/get-history

Request body object

The request body must contain:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "recipient": {
    "id": "79999999999@c.us"
  }
}

WhatsappID - WhatsApp identifier in the system
recipient - points to a chat (or group) whose history should be retrieved. Recipient object description

Response object

Successful response object

{
  "result": "OK"
  "data": [
        {
            "id": "false_79999999999@c.us_17AC61BFA5A561B7EE42F98810EDFFC4",
            "ack": 0,
            "hasMedia": false,
            "mediaKey": "",
            "body": "Hello world!",
            "type": "chat",
            "timestamp": 1667296242,
            "from": "79999999999@c.us",
            "to": "79999999999@c.us",
            "isForwarded": false
        }
    ]
}

result - has value OK on success
data - array of message objects. Detailed message object description.

Working with media files (deprecated)

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:17 +0000

This command is deprecated and will be removed over time.

Use the get-messagemedia method

Working with media files (deprecated)

This command lets you retrieve a media file attached to a received message. If a message contains media, the message field “hasMedia” is set to true, and the “mediaKey” field contains the media identifier used by this command.

Request command

To request media, send a POST request to:

https://whatsgate.org/api/v1/get-media

Request body object

The request body must contain:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "mediaKey": "TuM9wXQZBmERUCzwnIZe80GwZ5lPDIDsNE+vewnAxho="
}

WhatsappID - WhatsApp identifier in the system
mediaKey - media file identifier

Response object

Successful response object

{
  "result": "OK",
  "media": {
    "mimetype": "image/jpeg",
    "filename" : "image.jpg",
    "data": "<base64_encoded_data>"
  }
}

In the response, the “media” field contains a media file object

Working with media files

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:16 +0000

Working with media files

This command lets you get a media file from any message. If a message has media, its “hasMedia” field is set to true, and to fetch the media you must provide the full message id in the format false_79999999999@c.us_17AC61BFA5A561B7EE42F98810EDFFC4.

Request command

To request media, send a POST request to:

https://whatsgate.org/api/v1/get-messagemedia

Request body object

The request body must contain:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "MessageID": "false_79999999999@c.us_17AC61BFA5A561B7EE42F98810EDFFC4"
}

WhatsappID - WhatsApp identifier in the system
MessageID - message identifier

Response object

Successful response object

{
  "result": "OK",
  "media": {
    "mimetype": "image/jpeg",
    "filename" : "image.jpg",
    "data": "<base64_encoded_data>"
  }
}

In the response, the “media” field contains a media file object.

If the message is not found, or if it has no media, an error is returned.

API requests

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:14 +0000

API requests

API requests are sent to:

https://whatsgate.org/api/v1/<command>

List of commands for WhatsApp instance management:

send - send messages
seen - marks latest chat messages as seen for the other participant
typing - sends the “typing” status to the other participant for 15 seconds
get-chats - request chat list
get-media - request media file
check - check whether a number is registered in WhatsApp
events-get - request incoming events to receive incoming messages

List of session management commands:

session-create - create a new WhatsApp session
session-delete - delete a WhatsApp session and log out
sessions-get - retrieve session list
set-name - change session name
set-hook - set a webhook for incoming messages

Request headers

API authorization is done via the X-Api-Key request header. The Content-type: application/json header is also required.

X-Api-Key: YOUR_API_KEY
Content-type: application/json

Request body

A JSON object is sent in the request body, with WhatsappID as a required parameter.

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "number": "79999999999"
}

Response

If everything succeeds, the response code is 200 and the body contains a JSON object. JSON fields depend on the command used.

{
  "result": "OK",
  "data": true
}

On error, the response code is 500. The returned object contains:

name - error name
message - more detailed error information
code - error code

{
  "name": "Unauthorized",
  "message": "Your request was made with invalid credentials.",
  "code": 0
}

Sending seen flag

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:23 +0000

Sending seen flag

The seen flag is sent for a specific contact. After that, the latest messages in the chat sent by that contact are marked as seen.

Request command

To send this request, issue a POST request to:

https://whatsgate.org/api/v1/seen

Request body object

The request body must contain:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "recipient": {
    "id": "79999999999@c.us"
  }
}

WhatsappID - WhatsApp identifier in the system
recipient - recipient object

Response object

Successful response object

{
  "result": "OK"
}

Sending messages

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:34 +0000

Sending messages

Request command

To send a message, send a POST request to:

https://whatsgate.org/api/v1/send

The request body must contain a message send object.

Sending mode

A message can be sent through the API in two modes:

Synchronous: the response is returned only after sending, and includes the sent message object with identifier. In this mode, the webhook does not receive a "Sent" event.
Asynchronous: the API response returns queueing result (usually “OK”), and the sent message object is delivered to webhook (if configured). Event type: "Sent".

The "Ack" event is always sent to webhook, regardless of synchronous or asynchronous mode.

Sending mode depends on the “async” field: if true, sending is asynchronous; otherwise it is synchronous.

Message send object

The message send request body has 4 main fields:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "async": false,
  "recipient": { ... RECIPIENT_OBJECT ... },
  "message": { ... MESSAGE_OBJECT ... }
}

WhatsappID - WhatsApp identifier in the service
async - controls request synchrony
recipient - message recipient object
message - message object

Recipient - message recipient object

A WhatsApp message recipient can be specified in several ways.

1. By WhatsApp identifier. The identifier scheme is simple: for contacts, identifier = phone number + @c.us, for example 79991112233@c.us. For groups, identifier = internal group number + @g.us, for example AA11223344@g.us.

If recipient is provided by identifier, the object looks like this:

//for contact
"recipient" : {
  "id" : "79991112233@c.us"
}

//for group
"recipient" : {
  "id" : "AA11223344@g.us"
}

2. By number and type. Type can be contact or group. Default is contact.

"recipient" : {
  "type" : "contact",
  "number" : "79991112233"
}

//equivalent

"recipient" : {
  "number" : "79991112233"
}

//or for group

"recipient" : {
  "type" : "group",
  "number" : "AA11223344"
}

Message - message object

The message object consists of the following fields:

"message" : {
  "type" : "<string>",
  "body" : "<string>",
  "quote" : "<string>",
  "media" : { ... MEDIA_OBJECT ...}
}

The type field defines message type. Supported message types:

Required fields depend on message type. By default, type is “text”. The quote field is optional and can be used with any message type. It contains the long message identifier returned in synchronous send responses or delivered via webhook for asynchronous sending (or for incoming messages). When set, the sent message is marked as a reply to the referenced message.

"message" : {
  ...
  "quote" : "true_79991112233@c.us_3EB0EBC34954F8976AA6"
  ...
}

Text - text message

A “text” message is a plain text message. Field type is either omitted or set to “text”. Field body is required.

"message" : {
  "body" : "Hello world!"
}

Image, sticker, document, or voice message

When one of the media types is used, body becomes optional and media becomes required. You can still provide body text, which will be shown with the media message.

Media - media file object

The media file object has 3 fields:

"media" : {
  "mimetype" : "<mimetype_list_value>",
  "data" : "<base64_encoded_data>",
  "filename" : "<string>"
}

mimetype - value from the available mimetype list
data - file content encoded in base64
filename - file name as displayed to recipient; used for doc and image types

Voice messages must be in OGG format.

Message send object examples

Text message

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "async": false,
  "recipient": {
    "number" : "79999999999"
  },
  "message": {
    "body" : "Hello, world!"
  }
}

Media message with image

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "async": false,
  "recipient": {
    "type" : "group",
    "number" : "AA11223344"
  },
  "message": {
    "type" : "image",
    "body" : "You received a little bird!",
    "quote" : "true_79991112233@c.us_3EB0EBC34954F8976AA6",
    "media" : {
       "mimetype" : "image/png",
       "data" : "iVBORw0KG....5CYII=",
       "filename" : "bird.png"
    }
  }
}

List of available mimetype

application/ogg
application/pdf
application/zip
application/gzip
application/msword
audio/mp4
audio/aac
audio/mpeg
audio/ogg
audio/webm
image/gif
image/jpeg
image/pjpeg
image/png
image/svg+xml
image/tiff
image/webp
video/mpeg
video/mp4
video/ogg
video/quicktime
video/webm
video/x-ms-wmv
video/x-flv
application/vnd.ms-excel
application/vnd.ms-powerpoint
application/msword

Creating a session via API

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:13:04 +0000

Creating a session via API

This command opens a WhatsApp session to link it to the service. After opening, you must authorize WhatsApp through the mobile app and QR code. If the session is no longer needed, close it using session-delete.

Request command

To create a session, send a POST request to:

https://whatsgate.org/api/v1/session-create

Request body object for QR authorization

The request body must contain:

{
  "name" : "My WhatsApp",
  "callback" : "https://callback.my/script.handler"
}

name - WhatsApp name in the system (for easier identification)
callback - URL of the incoming events handler (optional, can be set later via set-hook)

Request body object for CODE authorization

The request body must contain:

{
  "name" : "My WhatsApp",
  "callback" : "https://callback.my/script.handler",
  "auth_type" : "CODE",
  "number" : "79999999999"
}

name - WhatsApp name in the system (for easier identification)
callback - URL of the incoming events handler (optional, can be set later via set-hook)
auth_type - authorization type set to code. In this mode, phone number becomes required.
number - phone number to connect in 7XXXXXXXXXX format

Response object

Successful response object

{
  "result": "OK",
  "data" : {
     "id": 151,
     "name": "My WhatsApp",
     "unique_id": "6345454545454",
     "status": "PENDING",
     "callback": "https://callback.my/script.handler",
     "date_add": "2022-10-11 19:30:14",
     "qr": null,
     "status_name": "Initialization",
     "pushname": null,
     "wid": null,
     "qr_link": "https://whatsgate.org/qr/6345454545454"
  }
}

result - contains “OK” when the request succeeds.
data - contains created session object including its unique identifier unique_id and QR authorization link qr_link.
qr or code depends on selected authorization type. If code authorization is selected, the code is returned in code. Field qr_link points to the authorization code page.

QR authorization window

The QR authorization window is available at:

https://whatsgate.org/qr/<unique_id>

For convenience, this link is returned in qr_link when creating a session. The QR code in this window is updated periodically and changes to a success or error image after authorization.

Embedding the QR page

This page can be embedded into your app via iframe, and parent page can receive messages from it. Embedding example:

<h1>QR test code</h1>

<iframe src="https://whatsgate.org/qr/6345454545454" width="310" height="310" style="border: none;">

</iframe>

<div class="log" id="log">

</div>

<script>
    window.addEventListener("message", function(event) {

        console.log(event);

        if (event.origin !== 'https://whatsgate.org') {
            // something came from an unknown domain; ignore it
            return;
        }

        if(typeof event.data !== 'object') {
            // message must be an object
            return;
        }

        if(!('module' in event.data) && event.data.module !== 'qr'){
            // object must contain module field with value qr
            return;
        }

        //if we're here, the message is valid; output it
        console.log( "received: " + event.data.message);
        //append message to parent-page log
        document.getElementById('log').append("received: " + event.data.message, document.createElement("br"));
    });
</script>

The message object is in event.data and has this format:

{
  "module" : "qr",
  "message" : "<message>"
}

module - always has value qr, to identify relevant messages
message - can have the following values:
- loading - session initialization and QR code loading; sent at page load start
- qr - QR code has been generated and displayed; sent each time code refreshes
- success - device authorized successfully; QR code is hidden
- error - authorization error occurred; try again
- broken - attempt to open a window with non-existing or closed session identifier

Deleting a session via API

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:32 +0000

Deleting a session via API

Deleting a session means WhatsApp authorization is terminated, all session data is removed from Whatsgate servers, and resources are released (for example, if your plan allows only 1 session, you cannot create a new one until the current session is deleted).

Request command

To send this request, issue a POST request to:

https://whatsgate.org/api/v1/session-delete

Request body object

The request body must contain:

{
  "WhatsappID": "YOUR_WHATSAPP_ID"
}

WhatsappID - WhatsApp identifier in the system

Response object

Successful response object

{
  "result": "OK",
  "data": {
        "id": 456,
        "name": "My Whatsapp",
        "unique_id": "YOUR_WHATSAPP_ID",
        "status": "DESTROYING",
        "callback": null,
        "date_add": "2022-10-12 07:10:49",
        "status_name": "Deleting",
        "pushname": "Vasya",
        "wid": "79991234567@c.us",
    }
}

Getting the session list

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:30 +0000

Getting the session list

This command is used to get the list of sessions for an account.

Request command

To retrieve the session list, send a POST request to:

https://whatsgate.org/api/v1/sessions-get

Request body object

The request body accepts:

{
  "WhatsappID" : "",
  "name" : "",
  "status" : "",
  "page_cnt" : "",
  "page" : ""
}

All fields in this object are optional, so an empty object is enough to get the full list of active sessions. Fields WhatsappID, name, and status are filters.

WhatsappID - filter by WhatsApp identifier, exact match; returns one session with the specified identifier.
name - filter by name, partial match.
status - session status filter. Can be one of:
- AUTH - sessions in authorization status.
- READY - sessions in working state.
- ERROR - sessions in error state.
- CLOSED - closed sessions (due to error or end of paid period)
page_cnt - maximum sessions returned per page. Default is 50, maximum is 100.
page - page number. Default is 1

Response object

Successful response object

{
  "result": "OK",
  "pages" : 1,
  "elements" : 2,
  "page" : 1,
  "data" : [
     {
        "id": 151,
        "name": "My WhatsApp 1",
        "unique_id": "6345454545454",
        "status": "AUTH",
        "callback": "",
        "date_add": "2022-10-11 19:30:14",
        "status_name": "Authorization",
        "pushname": null,
        "wid": null,
        "qr_link": "https://whatsgate.org/qr/6345454545454"
     },
     {
        "id": 152,
        "name": "My WhatsApp 2",
        "unique_id": "6345454545455",
        "status": "READY",
        "callback": "",
        "date_add": "2022-10-12 10:35:01",
        "status_name": "Working",
        "pushname": "Vasya",
        "wid": "79991234567@c.us",
        "qr_link": ""
     },
  ]
}

result - contains “OK” when the request succeeds
pages - number of pages for the selected filters
elements - number of elements in the filtered result (number of WhatsApp sessions returned)
page - current page number
data - contains an array of WhatsApp session objects

Changing session name

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:08 +0000

Changing session name

This command changes the name of the specified WhatsApp session.

Request command

To change a session name, send a POST request to:

https://whatsgate.org/api/v1/set-name

Request body object

The request body must contain:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "name": "new name"
}

WhatsappID - WhatsApp identifier in the system
name - new session name

Response object

Successful response object

{
  "result": "OK",
  "data":  {
     "id": 151,
     "name": "new name",
     "unique_id": "6345454545454",
     "status": "READY",
     "callback": "https://callback.my/script.handler",
     "date_add": "2022-10-11 19:30:14",
     "status_name": "Working",
     "pushname": "Vasya",
     "wid": "79991234567@c.us",
  }
}

data - session object

Sending typing status

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:21 +0000

Sending typing status

Typing status is sent for a specific contact; after that, the recipient will see the “typing” indicator from this number for 15 seconds.

Request command

To send this request, issue a POST request to:

https://whatsgate.org/api/v1/typing

Request body object

The request body must contain:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "recipient": {
    "id": "79999999999@c.us"
  }
}

WhatsappID - WhatsApp identifier in the system
recipient - recipient object

Response object

Successful response object

{
  "result": "OK"
}

Incoming processing (Webhook)

anonymous@undisclosed.example.com (Anonymous) — Wed, 10 Jun 2026 21:12:25 +0000

Incoming processing (Webhook)

Webhook is used to process incoming events, asynchronous request responses, and error information. For example, when an incoming message is received in the messenger, a POST request is sent to the configured webhook:

{
  "id":18,
  "whatsapp_id":"191b80a9238",
  "event_action":"message",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id" : "3EB0436AE1E682FF3A37",
       "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79991112233@c.us",
       "to":"79999999999@c.us",
       "isForwarded":false
    }
  }
}

To confirm successful event receipt, your webhook must return a JSON object containing the incoming event identifier and status OK.

{
  "result" : "OK",
  "id" : 18
}

If the system does not receive a valid response, it retries the request 3 times every 20 seconds.

Webhook setup

Webhook setup in account dashboard

To set a Webhook handler URL, open your account dashboard, choose the linked WhatsApp block, click the 3 dots, then click edit.

In the opened window, specify the URL to your Webhook handler script.

Click “Save”.

Webhook setup via API

To enable or disable WebHook via API, use the set-hook method. Send a POST request to:

https://whatsgate.org/api/v1/set-hook

Request body:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "callback": "https://callback.my/script.handler"
}

WhatsappID - WhatsApp identifier in the system
callback - URL of incoming events handler

Successful response object

{
  "result": "OK"
}

Event types

Ready

This event is sent after authorization, when the client is fully ready to send and receive messages. Session status changes from AUTH to READY. Field event_action contains “ready”. Field event_data contains authorized account data: number and name.

pushname - client's name in messenger
number - authorized phone number
id - WhatsApp identifier in @c.us format

{
  "id":19,
  "whatsapp_id" : "191b80a9238",
  "event_action" : "ready",
  "event_date" : "2023-01-24 18:29:37",
  "status_code" : null,
  "event_data" :
  {
    "pushname": "vasya",
    "number" : "79991234567",
    "id" : "79991234567@c.us"
  }
}

Message

This event is sent for any incoming message in a chat or group. Field event_action contains “message”. Field event_data contains a message object.

{
  "id":18,
  "whatsapp_id":"191b80a9238",
  "event_action":"message",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79991112233@c.us",
       "to":"79999999999@c.us",
       "isForwarded":false
    }
  }
}

Sent

This event is sent after successful message delivery when an asynchronous send command was used.

Field event_action contains “sent”. Field event_data contains the delivered message object.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"sent",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79999999999@c.us",
       "to":"79991112233@c.us",
       "isForwarded":false
    }
  }
}

Ack

This event is sent when a message status changes in a chat or group. Field event_action contains “ack”. Field event_data contains the message object whose status changed. Message status is in message field ack and can be: 1 - sent, 2 - delivered, 3 - read.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"ack",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79999999999@c.us",
       "to":"79991112233@c.us",
       "isForwarded":false
    }
  }
}

Disconnect

This event is sent when the client disconnects and closes. This happens when you remove the client from your account dashboard or revoke the link in the WhatsApp mobile app. Field event_action contains “disconnect”. Field event_data contains an object with field reason describing the disconnect cause.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"disconnect",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "reason": "Client disconnected"
  }
}

Error

This event is sent when any error occurs. For example, when you try to send asynchronously to a number outside your contact list on the Light plan. Field event_action contains “error”. Field event_data contains an object describing the error.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"error",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "error":"Specified number not in your contact list"
  }
}

Create

This event is sent for any outgoing message in a chat or group. It lets you track sent messages via webhook, including messages sent from the mobile client or other linked applications.

Field event_action contains “create”.

Field event_data contains a message object.

{
  "id":18,
  "whatsapp_id":"191b80a9238",
  "event_action":"create",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"true_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79991112233@c.us",
       "to":"79999999999@c.us",
       "isForwarded":false
    }
  }
}

Message object

{
   "_id":"3EB0436AE1E682FF3A37",
   "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
   "ack":1,
   "hasMedia":false,
   "mediaKey":"",
   "body":"212",
   "type":"chat",
   "timestamp":1662575377,
   "from":"79999999999@c.us",
   "to":"79991112233@c.us",
   "isForwarded":false,
   "quoted": {
       "_id": "3EB07621A4D08F9F59E0",
       "from": "79537226631@c.us",
       "type": "chat",
       "body": "Hello!"
   }
}

Message object fields:

_id - message identifier in WhatsApp.
id - WhatsApp message identifier that can be passed in the “quote” field to mark a message as a reply.
ack - (int) status flag showing message state: 1 - sent, 2 - delivered, 3 - read
hasMedia - flag indicating whether message contains a media file
mediaKey - media file key used in get-media to fetch media.
body - message text
type - message type
timestamp - message date in Unix timestamp format
from - sender identifier
to - recipient identifier
isForwarded - indicates whether the message was forwarded from another chat
quoted - if this message quotes (replies to) another message, quoted contains the quoted message object.
- _id - quoted message identifier
- from - quoted message author identifier
- type - quoted message type
- body - quoted message text

PHP code for webhook request handling

<?php
 
//buffer output
ob_start();
 
var_dump('----------------------' . date('d.m.Y H:i:s') . '----------------');
 
//extract request data
$input = file_get_contents('php://input');
$input_data = json_decode($input, true);
 
var_dump($input_data);
 
if($input_data['event_action'] == 'message') {
    //@TODO process incoming message
 
}
 
if($input_data['event_action'] == 'ack') {
 
    //@TODO process delivery or read status
 
    if($input_data['event_data']['message']['ack'] == 2) {
        //@TODO delivered
    }
    if($input_data['event_data']['message']['ack'] == 3) {
        //@TODO read
    }
}
 
//save log
$fo = fopen('webhook.log', 'a');
fwrite($fo, ob_get_clean());
fclose($fo);
 
//build and output response
$answer_data = [
    'id' => $input_data['id'],
    'result' => 'OK'
];
 
echo json_encode($answer_data);
?>