WAZZUP Help

Integration by API

Wazzup API integration provides a set of methods developed to send messages, work with user, channel, contact, and deal entities, receive web hooks events.

API V2 (beta) allows you to easily embed an additional interface containing Wazzup Chats into any CRM system and use the unanswered messages counter.

Unanswered messages counter and Chats window

Obtaining an API Key

  1. Go to “Integrations” in your personal account settings.
  2. Click .
  3. Select “Integration by API”.
  4. Done — now you can copy your API key.

Opening the Chats window

To open the Chats window, send a POST request to https://api.wazzup24.com/v2/iframe:

1. Specify the API key in the “Authorization” request header.

Headers-example

Request parameters

ParameterTypeDescription
userObjectAn object containing user information
user.idInteger/StringAn identifier of a user opening the Chats window within a CRM system
user.nameStringUser name. Used later as a sender's name
scopeStringA context wherein the window is opened;
"global" for the global chat
or
"card" for a chat within an entity card
filterObject (Array)An array containing chat objects for display. Mandatory when scope = card
filter.chatTypeStringMessenger chat type. Possible values: “whatsapp”, “instagram”
filter.chatIdStringChat id (contact's account in a messenger):
for whatsapp, numbers only, no whitespaces or special characters
for instagram, the account without the @ in the beginning
filter.nameStringOptional parameter containing the contact's name
activeChatObjectChat active when you open Iframe
activeChat.chatTypeStringMessenger chat type. Possible values: “whatsapp”, “instagram”
activeChat.chatId Integer/StringChat id (contact's account in a messenger):
for whatsapp, numbers only, no whitespaces or special characters
for instagram, the account without the @ in the beginning

If the contact with the specified chatType and chatId does not exist in the Wazzup database, it will be created when opening it in the CRM contact card. In this case, the name value will be used for the name – or the chatId value if the former is not present.

Request body example

Unanswered messages counter

To use the unanswered messages counter, connect to the web socket at https://api-ws.wazzup24.com.

When connecting, generate the apiV2IframeConnecting event and send an object containing the user’s API key and id:

After that, when the unanswered messages counter changes, the corresponding data will be transmitted in a apiV2Notify event as the following object:

An example using socket.io:

Available API methods

Sending messages

POST https://api.wazzup24.com/v2/send_message

Request parameters

ParameterTypeDescription
channelIdStringThe id (uuidv4) of the channel that you need to send a message through
chatTypeStringAddressee messenger chat type. Possible values: “whatsapp”, “instagram”
chatIdStringChat id (contact's account in a messenger):
for whatsapp, numbers only, no whitespaces or special characters
for instagram, the account without the @ in the beginning
textStringMessage text (up to 10,000 symbols)
Mandatory if the content parameter is not specified
contentStringA link to the file to send.
Mandatory if the text parameter is not specified
refMessageIdStringThe id of the message to quote.
Optional parameter

Request body example

Request result

HTTP/1.1 201 OK

Obtaining the channel list

GET https://api.wazzup24.com/v2/channels

Request result

In the reply, an array will be transmitted containing information about the channels specified in your Wazzup personal account’s “Integrations” section:

HTTP/1.1 200 OK

Request result data

ParameterTypeDescription
channelIdStringChannel id (uuidv4)
transportStringChannel type (messenger). Possible values:
whatsapp
instagram
plainIdStringPhone number or instagram channel account
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

Enabling web hooks and obtaining the current url value

PUT https://api.wazzup24.com/v2/webhooks

Request body example

In the url, specify the address to receive web hooks to – or null to disable web hooks.

During this process, a test request will be sent to the specified url. When web hooks have been enabled successfully, the server must return the 200 HTTP code.

The reply will contain a newly established address for web hooks and information telling you whether the previous url was different from the one transmitted (in the value of the webhooksUrlChanged key).

HTTP/1.1 200 OK

Verifying the address for web hooks

GET https://api.wazzup24.com/v2/webhooks

HTTP/1.1 200 OK

Webhooks

Wazzup sends three types of web hooks.

New messages

A web hook will send you a JSON object with the messages key; its value contains an array of objects with the following parameters:

ParameterTypeDescription
messageIdStringMessage UUID
channelIdStringChannel id
chatTypeStringAddressee messenger chat type. Possible values: “whatsapp”, “instagram”
chatIdStringChat id (contact's account in a messenger):
for whatsapp, numbers only, no whitespaces or special characters
for instagram, the account without the @ in the beginning
dateTimeNumberMessage timestamp (unix time milliseconds)
typeNumberMessage type:
0 – a message of an unsupported type
1 – text
2 – image
3 – audio
4 – video
5 – document
statusNumberA successful transmission status or an error:
2 – received (analogous to two gray ticks)
3 – read (analogous to two blue ticks)
13 — for whatsapp: the client who the message is addressed to has not installed the app or has linked it to another number
13 — for instagram: there is no such Instagram account. Possibly, the client has changed their profile name.
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 transmission has been interrupted. There were too many messages sent from the account.
21 – The file content does not satisfy Instagram's requirements.
66 – An error occurred. The information has already been directed to Wazzup developers.
99 – An incoming message
textStringMessage text
contentStringMessage content link (optional)
authorTypeNumberSender type:
0 – phone
1 – Wazzup interface
2 – Wazzup API
3 – amoCRM
4 – planfix
5 – bitrix24
6 — Zoho CRM
7 — Salesforce
8 — Hubspot
99 — Incoming message from client
refMessageIdStringQuoted 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.
authorNameStringSender's name in whatsapp, if present.
instPostObjectInstagram post information object
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:

Outgoing message status update

A web hook will send you a JSON object with the statuses key; its value will contain an array of objects with the following parameters:

ParameterTypeDescription
messageIdStringThe id (uuidv4) of the channel that you need to send a message through
statusStringMessage status:
0 – The 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 — for whatsapp: the client who the message is addressed to has not installed the app or has linked it to another number
13 — for instagram: there is no such Instagram account. Possibly, the client has changed their profile name.
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 transmission has been interrupted. There were too many messages sent from the account.
21 – The file content does not satisfy Instagram's requirements.
66 – An error occurred. The information has already been directed to Wazzup developers.

Channel status update

A web hook will send you a JSON object with the channels key; its value contains an array of objects with the following parameters:

ParameterTypeDescription
channelIdStringChannel id (uuidv4)
transportStringChannel type (messenger). Possible values:
whatsapp
instagram
plainIdStringPhone number or instagram channel account
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

Changing the channels list in the integration (a new channels list is sent)

A web hook will send you a JSON object with the channelsList key; its value contains an array of objects with the following parameters:

ParameterTypeDescription
channelIdStringChannel id (uuidv4)
transportStringChannel type (messenger). Possible values:
whatsapp
instagram
plainIdStringPhone number or instagram channel account
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

Working with the user entity

Obtaining the user list

To obtain a list of users in the integration, send a GET request to https://api.wazzup24.com/v2/users.

Request result example

Obtaining information about a specific user

To obtain information about a specific user in the integration, send a GET request to https://api.wazzup24.com/v2/users/{user id}.

Request result example

Updating the user list

To add a new user or change the name of an already existing one, there is a route available to update the list of users in the integration.

Send a PATCH request to https://api.wazzup24.com/v2/users

The request body must contain an array of user details. We match users by their id. If there is no such user in Wazzup, we will add them; if there is such a user, we will update their details.

Request parameters

ParameterTypeDescription
idanyUser identifier A string up to 64 characters long or an integer
nameStringUser name. A string up to 150 characters

Request body example

Replacing the user list

To completely replace the list of users in the integration, send a PUT request to  https://api.wazzup24.com/v2/users

The request body must contain an array of user details. The existing user information will be deleted, and the newly received data will be used instead.

Request parameters

ParameterTypeDescription
idanyUser identifier A string up to 64 characters long or an integer
nameStringUser name. A string up to 150 characters

Request body example

Deleting a user

To delete a user from the integration, send a DELETE request to https://api.wazzup24.com/v2/users/{user id}.

Working with contacts

Obtaining the contact list

To obtain the contact list, send a GET request to

https://api.wazzup24.com/v2/contacts. You can get up to 100 entries with one request.

Additional request parameters

ParameterTypeDescription
offsetNumberPagination offset; a non-negative integer. The default is 0
orderByStringSorting field. The default is id; you can also sort by name, or responsibleUserId
orderDirectionStringSorting direction, asc (default) or desc

Request result data

The reply will contain an array of objects with the following parameters:

ParameterTypeDescription
idanyContact id. String or number
responsibleUserIdanyId of the responsible user. String or number.
nameStringContact name
chatsObjectAn array of objects with details for a contact containing:
chatType – string
chatId – string or number
dealsObjectAn array of deals related to the contact. A deal id can be a string or number

Obtaining information about a specific contact

To obtain information about a specific contact in the integration, send a GET request to https://api.wazzup24.com/v2/contacts/{contact id}.

Request result data

The reply will contain an object with the following parameters:

ParameterTypeDescription
idanyContact id. String or number
responsibleUserIdanyId of the responsible user. String or number.
nameStringContact name
chatsObjectAn array of objects with details for a contact containing:
chatType – string
chatId – string or number
dealsObjectAn array of deals related to the contact. A deal id can be a string or number

Updating the contact list

To update the contact list, send a PATCH request to https://api.wazzup24.com/v2/contacts.

The request body must contain an array of contact details. Contacts are matched by their id. If there is no such contact in Wazzup, we will add them; if there is such a contact, we will update their details.

Request parameters

ParameterTypeDescription
idanyContact id. String or number
responsibleUserIdanyId of the responsible user. String or number. Fill in this field to display the dialog in the Wazzup chat window for the contact person. Works when setting p.3 "Only your dialogues and dialogues from your queues" is used.
nameStringContact name
chatsObjectAn array of objects with details for a contact containing:
chatType – string
chatId – string or number
dealsObjectAn array of deals related to the contact. A deal id can be a string or number

Deleting a contact

To delete a contact, send a DELETE request to https://api.wazzup24.com/v2/contacts/{contact id}.

Working with a deal list

Obtaining a deal list

To obtain a deal list, send a GET request to

https://api.wazzup24.com/v2/deals. You can get up to 100 entries with one request.

Additionally, you can send the following parameters in the query string:

ParameterTypeDescription
offsetNumberPagination offset; a non-negative integer. The default is 0
orderByStringSorting field. The default is id; you can also sort by name, or responsibleUserId
orderDirectionStringSorting direction, asc (default) or desc

Request result data

The reply will contain an array of objects with the following parameters:

ParameterTypeDescription
idNumberDeal id. A Mandatory field
responsibleUserIdanyResponsible user id. String or number
nameStringDeal name
closedBooleanA flag marking closed deals
contactsObjectAn array with IDs of contacts related to the deal. A contact ID can be a string or number

Obtaining information about a specific deal

To obtain information about a specific deal, send a GET request to https://api.wazzup24.com/v2/deals/{deal id}.

Request result data

The reply will contain an object with the following parameters:

ParameterTypeDescription
idNumberDeal id. A Mandatory field
responsibleUserIdanyResponsible user id. String or number
nameStringDeal name
closedBooleanA flag marking closed deals
contactsObjectAn array with IDs of contacts related to the deal. A contact ID can be a string or number

Updating a deal list

To update a deal list, send a PATCH request to https://api.wazzup24.com/v2/deals.

The request body will contain an array of deal details. Deals are matched by their id. If there is no such deal in Wazzup, we will add it; if there is such a deal, we will update its details.

Request parameters

ParameterTypeDescription
idNumberDeal id. A Mandatory field
responsibleUserIdanyResponsible user id. String or number. Fill in this field so that dialogs with contacts associated with the deal are displayed in the Wazzup chat window for the lead manager. Works when setting p. 3 "Only your dialogues and dialogues from your queues" is used.
nameStringDeal name
closedBooleanA flag marking closed deals
contactsObjectAn array with IDs of contacts related to the deal. A contact ID can be a string or number

Deleting a deal

To delete a deal, send a DELETE request to

https://api.wazzup24.com/v2/deals/{deal id}.