Sending WHATSAPP

To have an opportunity to send WHATSAPP messages, please contact your manager.

Messages are sent in chat mode:

• if the chat is initiated by a client, the first message must match the registered template. Each time the subscriber replies, a 24-hour window will open to send messages with arbitrary content. If the subscriber does not reply, the client can send messages to the user outside the 24-hour window using pre-registered message templates;

• if the chat is initiated by the subscriber, during the 24-hour window the client can send messages with arbitrary content.

Sending WHATSAPP

POST https://direct.revicom.ltd/api/v1/message

The method allows for sending an array of single messages (1 to 1,000)

Headers

Name	Type	Description
Authorization*	string	Basic {TOKEN_1}
Content-Type*	string	application/json

Request Body

Name	Type	Description
channelType*	string	Sending channel (SMS)
senderName*	string	Sender name. WHATSAPP-names with the status “Approved” are allowed, with the start date not later than the request time
destination*	string	Subscriber number
content*	object	Message content. Below are the possible contents
tags	array	Message tags (array of strings). Each tag must match the expression ^\w+$ (any case letters, numbers and underscore "_" are allowed)
useLocalTime	boolean	Flag responsible for the time zone in which the message will be sent: true – sending in the subscriber time zone false – sending by Moscow time By default, true
localSendTime	string	Low bound for the allowed time to send a message (subject to useLocalTime) Date in the format 'YYYY-MM-DD hh:mm:ss' in the range from (current UTC time – 12 hours) to (current UTC time + 7 days) By default the message will be sent immediately
localCompletionTime	string	Upper bound for the allowed time to send a message (subject to useLocalTime) in the range from localSendTime to (current UTC time + 70 days)
ttl	integer	Message lifetime in seconds. After the ttl expires, the final status is set to the message 60 ≤ ttl ≤ 86400
hours	array	Valid sending hours (array of numbers). Integers from 0 to 23 can be transmitted in the array, each corresponding to the hour interval allowed for sending, subject to useLocalTime; the values must be unique.
days	array	Valid sending days (array of numbers). Integers from 1 (Mon) to 7 (Sun) can be transmitted in the array, each corresponding to the week day allowed for sending; the values must be unique.
shortUrl	boolean	Flag responsible for shortening links in the message: true- links in the text of the message will be shortened By default, false
callbackUrl	string	Address to send callback
callbackEvents	array	Events to send callback (an array of strings). If there is callbackUrl and no callbackEvents in the request, a callback will be sent on the event delivered

200

If the request is successful, a response is returned that lists the message IDs and result codes. With errors = false, all submitted messages are guaranteed to have been successfully generated.

{
  "errors": false,
  "items": [
    {
      "messageUuid": "063474ec-a34f-4558-90c5-984395000004",
      "code": 201
    },
    {
      "messageUuid": "063564ec-a34f-4558-90c5-984395000005",
      "code": 201
    }
  ]
}

401

Invalid token used/authorization header missing.

4012

{
    "error": {
        "code": 4012,
        "msg": "Bad credentials"
    }
}

4010

{
    "error": {
        "code": 4010,
        "msg": "Not Authenticated"
    }
}

403

Token of wrong type used.

{
    "error": {
        "code": 4030,
        "msg": "Access Denied"
    }
}

422

The request body contains invalid parameters or the maximum number of objects is exceeded.

{
    "error": {
        "code": 4220,
        "msg": "Max count of messages is 1000"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local send time is less than minimal {minLocalSendTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local send time is greater than minimal {maxLocalSendTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local completion time is less than minimal {minLocalCompletionTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local completion time is greater than maximal {maxLocalCompletionTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "No active sender name: ({channelType}, {senderName})"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid msisdn"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Blank content"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid tags: {tags}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid TTL {ttl}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4222,
        "msg": "Invalid hours: {hours}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4223,
        "msg": "Invalid days: {days}"
    }
}

503

{
    "error": {
        "code": 5030,
        "msg": "Url shortener is unavailable"
    }
}

Recommended minimum timeout: 70 seconds

To set up custom domain for the link shortening functionality, please contact customer support

Enumerations:

Parameter	Allowed values
callbackEvents	Callback Events

Text message

In addition to text, a WHATSAPP text message may contain a header, footer, and buttons. To send a text WHATSAPP message, use the following object content:

{
  "contentType": "text",
  "text": "whatsapp message text",
  "header": {
    "text": "message header"
  },
  "footer": {
    "text": "message footer"
  },
  "buttons": [
    {
      "text": "button text 1",
      "url": "https://revicom.ltd"
    },
    {
      "text": "button text 2",
      "phone": "14085553911"
    }
  ]
}

Parameter	Type	Description
contentType	string required	Content type (text)
text	string required	Message text; UTF-8 encoded string without Byte Order Mark 1 to 1,000 characters
header	object optional	Message header
header.text	string optonal	Header text Any string 1 to 60 characters
header.documentUrl	string optional	Link to the document for the header
header.documentName	string optional	Title of the document for the header; may only be present if documentUrl
header.imageUrl	string optional	Link to the image for the header
footer	object optional	Message footer
footer.text	string optional	Footer text Any string 1 to 60 characters
buttons	array (objects) optional	Array with button objects
buttons.text	string optonal	Button text Any string 1 to 20 characters
buttons.url	string optional	The link to which the button is clicked Any string 1 to 1,000 characters Must begin with http
buttons.phone	string optional	Phone number to which you are prompted to make a call when you press the button Any string 1 to 1,000 characters
buttons.payload	string optional	Hidden text that will be sent in the incoming message if the user clicks on the button Any string 1 to 1,000 mcharacters

Message header

• in the header object, only one of the following can be used:

• text

• documentUrl и documentName

• imageUrl

Message buttons

• in the buttons array, 1 to 3 objects are allowed

• any object must have text

• there are two types of the buttons:

  • link button: contains text and url or text and phone

  • text button: contains text and payloa

  • ❗ Transmission of payload alongside with url or phone is not allowed
• one message may transmit one-type buttons only

• one message may have only one button with parameter url

• one message may have only one button with parameter phone

• when transmitting buttons with text, no more than three objects in the array are allowed

• when passing buttons with a link, no more than two objects in the array are allowed

• buttons in the message do not affect a header or footer

Objects examples

Text

{
  "contentType": "text",
  "text": "message text"
}

With header

{
  "contentType": "text",
  "text": "message text",
  "header": {
    "documentUrl": "https://example.com/document.pdf",
    "documentName": "document.pdf"
  }
}

With header and footer

{
  "contentType": "text",
  "text": "message text",
  "header": {
    "imageUrl": "https://example.com/image.png"
  },
  "footer": {
  "text": "message footer"
  }
}

With text buttons

{
  "contentType": "text",
  "text": "message text",
  "buttons": [
    {
      "text": "button text 1",
      "payload": "id=1"
    },
    {
      "text": "button text 2",
      "payload": "id=2"
    }
  ]
}

With link buttons

{
  "contentType": "text",
  "text": "message text",
  "buttons": [
    {
      "text": "button text 1",
      "url": "https://i-dgtl.ru/"
    },
    {
      "text": "button text 2",
      "phone": "78124269988"
    }
  ]
}

Message with image

To send WHATSAPP message with an image attached, use the following object content:

{
  "contentType": "image",
  "imageUrl": "https://image.png",
  "imageName": "Image",
  "header": {
    "text": "message header"
  },
  "footer": {
    "text": "message footer"
  },
  "buttons": [
    {
      "text": "button text 1",
      "url": "https://i-dgtl.ru/"
    },
    {
      "text": "button text 2",
      "phone": "14085553911"
    }
  ]
}

Parameter	Type	Description
contentType	string required	Content Type (image)
imageUrl	string required	Link to the image
imageName	string required	Image name

Header, footer and buttons are validated according to the same rules as for a text message

Message with document

To send WHATSAPP message with an image attached, use the following object content:

{
  "contentType": "document",
  "documentUrl": "https://document.pdf",
  "documentName": "Document",
  "header": {
    "text": "header text"
  },
  "footer": {
    "text": "footer text"
  },
  "buttons": [
    {
      "text": "button text 1",
      "url": "https://revicom.ltd"
    },
    {
      "text": "button text 2",
      "phone": "78124269988"
    }
  ]
}

Parameter	Type	Description
contentType	string required	Content Type (document)
documentUrl	string required	Link to the document
documentName	string required	Name of the document

Header, footer and buttons are validated according to the same rules as for a text message

Request example

JSON

POST https://direct.revicom.ltd/api/v1/message
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
[
  {
    "senderName": "SENDER",
    "channelType": "WHATSAPP",
    "content": {
      "contentType": "text",
      "text": "Message text",
      "header": {
        "imageUrl": "https://example.com/image.png"
      },
      "footer": {
        "text": "Message footer"
      },
      "buttons": [
        {
          "text": "button text 1",
          "url": "https://revicom.ltd"
        },
        {
          "text": "button text 2",
          "phone": "14085553912"
        }
      ]
    },
    "destination": "14085553911",
    "localSendTime": "2022-06-15 18:00:00",
    "localCompletionTime": "2022-06-16 21:00:00",
    "shortUrl": true,
    "callbackUrl": "https://company.com/callback",
    "callbackEvents": [
      "delivered",
      "read",
      "click"
    ],
    "useLocalTime": true,
    "ttl": 43200,
    "hours": [
      12,
      13,
      14,
      15,
      16,
      17,
      18,
      19
    ],
    "days": [
      1,
      2,
      3,
      4,
      5,
      6,
      7
    ],
    "tags": [
      "tag1",
      "tag2"
    ]
  }
]

cURL

curl -X POST 'https://direct.revicom.ltd/api/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-d '[{"senderName":"SENDER","channelType":"VIBER","content":{"contentType":"text","text":"message text https://domain.com"},"destination":"7818242882","localSendTime":"2022-06-15 18:00:00","localCompletionTime":"2022-06-16 21:00:00","shortUrl":true,"callbackUrl":"https://company.com/callback","callbackEvents":["delivered","read","click"],"useLocalTime":true,"ttl":43200,"hours":[12,13,14,15,16,17,18,19],"days":[1,2,3,4,5,6,7],"tags":["tag1","tag2"]},{"senderName":"SENDER","channelType":"VIBER","destination":"7818242882","callbackUrl":"https://company.com/callback","callbackEvents":["delivered","read"],"content":{"contentType":"button","text":"message text","caption":"button text","action":"<button link>","imageUrl":"<image link>"},"localSendTime":"2022-06-15 18:00:00","localCompletionTime":"2022-06-16 21:00:00","useLocalTime":true,"ttl":43200,"hours":[12,13,14,15,16,17,18,19],"days":[1,2,3,4,5,6,7],"tags":["tag1","tag2"]},{"senderName":"SENDER","channelType":"VIBER","callbackUrl":"https://company.com/callback","callbackEvents":["delivered","read"],"destination":"7818242882","content":{"contentType":"image","imageUrl":"<image link>"},"localSendTime":"2022-06-15 18:00:00","localCompletionTime":"2022-06-16 21:00:00","useLocalTime":true,"ttl":43200,"hours":[12,13,14,15,16,17,18,19],"days":[1,2,3,4,5,6,7],"tags":["tag1","tag2"]}]'