WAZZUP Help

Integration by API (outdated)

To simplify the Wazzup integration, we limited the API to a single method and webhooks. Channel addition can be done from the Wazzup interface.

Sending messages

Headers

Request and reply body in JSON format.

In request headers, you need to specify “Content-type” = “application/json”, as well as the API key in the “Authorization” header.

To obtain the key, go to your Wazzup personal account and add the API integration: Settings → Integrations → Add → API.

Headers-example

Request parameters

ParameterTypeDescription
transportStringThe transport used for sending (either "whatsapp" or "instagram")
fromStringThe phone number of the channel to send the message from (in the international format without any special characters) – or the Instagram account (the one you specified when connecting the channel)
toStringThe recipient's phone number in the international format without any special characters – or the recipient's Instagram account's name
textStringMessage text (up to 10,000 symbols)
contentStringContent link (e.g. "https://picrutre-hoster.com/pic123.jpg")
refIdGUIDMessage ID when quoting for whatsapp – or Instagram post ID when answering in a comment

Body-example

Request result

In case of a successful request, the HTTP/1.1 201 OK result and the created message’s guid will be sent.

HTTP/1.1 201 OK

In case of an invalid token, the HTTP/1.1 401 Unauthorized result will be sent.

In case of a server failure, one of the HTTP/1.1 5xx results will be sent; you can try again.

In case of an incorrect request, the HTTP/1.1 400 Bad request result will be sent.

HTTP/1.1 404 Bad request

Error codeDescription
MESSAGE_TEXT_TO_LONGThe message text is too long
MESSAGE_CHANNEL_NOT_FOUNDThe channel with this number cannot be found in the account
MESSAGE_INCORRECT_PHONEIncorrect recipient phone number or incorrect Instagram account name
MESSAGE_ONLY_TEXT_OR_CONTENTOnly text or content can be filled in
MESSAGE_NOTHING_TO_SENDNeither text nor content has been filled in
MESSAGE_CHANNEL_DISABLEDThe channel to send the message is disabled
MESSAGE_WRONG_TRANSPORTIncorrect transport type
MESSAGE_CHANNEL_TARIFF_IS_NOT_ENOUGHYou cannot be the first to write and send content when using the "Start" price plan
MESSAGE_DOWNLOAD_CONTENT_ERRORCould not download content
MESSAGE_WRONG_CONTENT_TYPEContent type is not supported
MESSAGES_CONTENT_CAN_NOT_BE_BLANKContent file cannot be blank, i.e. the file size should be greater than zero
MESSAGES_TEXT_CAN_NOT_BE_BLANKText message cannot be blank
MESSAGES_CONTENT_SIZE_EXCEEDEDMaximum file size exceeded for the content to send (the limit is 50 MB)

Service content requirements

WhatsApp Business

Type of file

Documents

Images

Audio

Voice messages

Video

Supported media formats

*.pdf, .do*, .xl, .ppt, .sx*, .od*

.jpeg, .jpg, .png

*.acc, .mp4, .mp4a, .amr, .mpeg, .ogg

.ogg

*.mp4, .3gp, *.3g2

Max size

100MB

16MB

16MB

16MB

5M

Instagram

Type of file Images Video
Supported media formats .jpg, .jpeg .mp4
Max size 30 MB 50 MB

Webhooks

We keep sending webhooks to the URL you specified until we receive the HTTP/1.1 200 OK or the number of retries is exhausted. The webhooks’ URL can be set in your personal account when adding the integration. If you have already set the API integration, delete it and add it again:

A window will appear. Choose the “Integration by API (outdated)” option:

 

Then enter the URL to receive webhooks at:

Resending is done according to the following rule:

  1. Immediately when an event occurs
  2. After 1 second
  3. After 3 seconds
  4. After 5 seconds
  5. After 10 seconds
  6. After 30 seconds
  7. After 60 seconds
  8. 3 attempts with an interval of 5 minutes
  9. 3 attempts with an interval of 1 hour
  10. 30 attempts with an interval of 24 hours

Webhooks are sent in JSON format, and each of them can contain up to 3 update datasets.

1. New messages (messages)

New messages are not limited to just incoming messages from your clients: these can also be outgoing messages sent from a handset, another interaction, or from the Wazzup interface.

FieldTypeDescription
guidStringMessage guide
channelStringChannel phone number
phoneStringContact's phone number or Instagram account
dateTimeNumberMessage timestamp (unix time milliseconds)
typeNumberMessage type:
0 – a message of an unsupported type
1 – text
2 – image
3 – audio
4 – video
5 – document
21 – missed voice call notification
22 – missed video call notification
statusNumberMessage status. 99 – incoming message; the statuses for outgoing messages can be found in the table below
textStringMessage text
contentStringMessage content link (optional)
senderTypeNumberSender type (optional):
0 – phone
1 – Wazzup interface
2 – Wazzup API
3 – amoCRM
4 – planfix
5 – bitrix24
refIdStringQuoted message Id. For Instagram, the presence of this field means that this is a message in the comment section, and its absence means that this is a direct message.
usernameStringsender's name in whatsapp, if present.
instPostObjectObject with information about the Instagram post.

Presence of the “instPost” field signifies that the incoming message is in fact a comment to an Instagram post. WhatsApp and Instagram Direct messages do not have this field. Instagram post information object format:

2. Outgoing message statuses updates (statuses)

All statuses updates (“enqueued”, “sent” etc.) are sent into the API using webhooks. The rest depends on the developer.

Usually, the statuses follow the sequence of sent → received → read. However, sometimes, problems occur.

Important: 13 – the client does not have WhatsApp or Instagram; nowhere to send.

If after the 1, the 2 and the 3 are taking too long, possibly, you need to contact the client using different means because the client has stopped using WhatsApp or Instagram or does not have Internet connection.

If, while sending a message, the channel’s status changed to “Disabled”, “Deleted” or “Not paid”, the messages are enqueued for sending and are not sent to the client. In this case, the API receives an error message. It is important to process this message correctly and warn the user that the message has not been sent.

FieldTypeDescription
messageIdStringMessage guid
statusNumberMessage status:
0 – message is being processed
1 – sent (analogous to one gray tick)
2 – received (analogous to two gray ticks)
3 – read (analogous to two blue ticks)
13 – the message will not be sent because this phone number does not have a WhatsApp account
14 – the message text is too long
15 – Instagram filters do not allow the message because of the link
17 – the file size should not be more than 50 MB
18 – the message was not sent due to suspected spam
19 – the sending has been interrupted. There were too many messages sent from the account
21 – the file does not satisfy the service's requirements
66 – an error occurred. The information has already been directed to Wazzup developers

For a detailed description of the message statuses and recommendations for correcting them, read here.

3. Channel statuses updates (channels)

For different reasons, channel statuses can change with time. “Active” is a good status, the other ones – not so much, meaning that you need to do something about them.

All the channel statuses updates are sent to the API, as are the messages statuses. The developer must make sure that their system processes these and displays all necessary information to the users.

You can find out more about the channel statuses, their features and meaning here.

You will receive a webhook following any status change.

FieldTypeDescription
channelStringChannel's phone number or channel's Instagram account's name
stateStringChannel status:
active — the channel is active; everything is fine
disabled — the channel is disabled
phoneUnavailable — no connection with the phone
qr — you need to scan the QR code
openElsewhere — the app has been open somewhere else
notEnoughMoney — the channel is not paid for