Table of Contents

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:

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

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

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