Integration by API – WAZZUP Help

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.

This manual describes all available methods for interacting with Wazzup via API. If this instruction does not contain information about a function, then it is not implemented in Wazzup.

Table of contents

Unanswered messages counter and Chats window

Obtaining an API Key

Go to “Integrations” in your personal account settings.
Click .
Select “Integration by API”.
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

Authorization: Basic 32a817cbc1594bd5885574d8f0290cd3

Request parameters

Parameter	Type	Description
user	Object	An object containing user information
user.id	Integer/String	An identifier of a user opening the Chats window within a CRM system
user.name	String	User name. Used later as a sender's name
scope	String	A context wherein the window is opened; "global" for the global chat or "card" for a chat within an entity card
filter	Object (Array)	An array containing chat objects for display. Mandatory when scope = card
filter.chatType	String	Messenger chat type. Possible values: “whatsapp”, “instagram”, “telegram”, “vk”
filter.chatId	String	Chat 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.name	String	Optional parameter containing the contact's name
activeChat	Object	Chat active when you open Iframe
activeChat.chatType	String	Messenger chat type. Possible values: “whatsapp”, “instagram”, “telegram”, “vk”
activeChat.chatId	Integer/String	Chat 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

```json

"user": {
 
    "id": "222555",
 
    "name": "User Name"
 
  },
 
  "scope": "card",
 
  "filter": [
 
    {
 
      "chatType": "whatsapp",
 
      "chatId": "79998887766"
 
    },
   "activeChat": [
 
    {
 
      "chatType": "whatsapp",
 
      "chatId": "79998887766"
 
    },

```

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:

```

"apiKey": "32a817cbc1594bd5885574d8f0290cd3",
"userId": "2e0df379-0e3c-470f-9b36-06b9e34c3bdb"
}

```

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

`{ counter: number }`

An example using `socket.io`:

```js

const socket = io.connect(`https://https://api-ws.wazzup24.com`);

socket.on('connect', () => {
  socket.emit('apiV2IframeConnecting', { apiKey, userId });
});

socket.on('apiV2Notify', (data) => {
  console.log('apiV2Notify', data);
  count.innerHTML = data.counter;
});

```

Available API methods

Sending messages

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

Request parameters

Parameter	Type	Description
channelId	String	The id (uuidv4) of the channel that you need to send a message through
chatType	String	Addressee messenger chat type. Possible values: “whatsapp”, “instagram”, “telegram”, “vk”
chatId	String	Chat 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
text	String	Message text (up to 10,000 symbols) Mandatory if the content parameter is not specified
content	String	A link to the file to send. Mandatory if the text parameter is not specified
refMessageId	String	The id of the message to quote. Optional parameter

Request body example

```json

{

  "channelId": "3376e1c3-26a6-478b-b964-72bf01cc22cb",

  "chatType": "whatsapp",

  "chatId": "79998887766",

  "content": "https://example.com/images/img_01.png"

}

```

Request result

HTTP/1.1 201 OK

```json

{ "messageId": "10d90130-38f6-421c-ada9-951f82884056" }

```

An example of sending a message in PHP:

<?php
$apiKey = '6073085ffa3f410d9e27fb2b6592d325'; // API Integration Authorization Key
$defaultChannelId = '654bae5f-2981-41e1-8279-4cd6898511da';
$url = 'https://api.wazzup24.com/v2/send_message';
 
$curl = curl_init(); // Using curl for request for Wazzup API
 
// If the channel is not specified in the request body, then use the default
$channelId  = (empty($_POST['channel'])) ?  $defaultChannelId : $_POST['channel'];
$channelId  = $_POST['channel'];
$chatId = $_POST['contact'];
$chatType = $_POST['messenger_type'];
$text = $_POST['text'];
 
/**
* There may be a code for writing a message to the database
*/
 
// Forming the request body
$post_data = json_encode(array(
   'channelId'=>$channelId,
   'chatId'=>$chatId,
   'chatType'=>$chatType,
   'text'=>$text
));
 
// Sending request to Wazzup
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
 'Authorization: Basic '. $apiKey,
 'Content-Type:application/json'
));
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS,$post_data);
 
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
 
$server_response = curl_exec($curl);
$http_response_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
 
// Парсим ответ
$header_size = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
$header = substr($server_response, 0, $header_size);
 
if ($http_response_code != 201) {
 error_log($header);
} else {
 // If everything is ok, then the guid of the sent message will be returned
 $res = json_decode($header);
 $msg_guid = $res->messageId;
}
 
curl_close ($curl);
?>

Error sending messages

Error code	Description
MESSAGE_WRONG_CONTENT_TYPE	Invalid content type. Occurs when the content type could not be determined or is not supported.
MESSAGE_ONLY_TEXT_OR_CONTENT	The message can contain text or content. You cannot send text and content to WhatsApp and Instagram at the same time.
MESSAGE_NOTHING_TO_SEND	Message text not found.
MESSAGE_TEXT_TOO_LONG	The text message is longer than 10,000 characters.
MESSAGE_CONTENT_CAN_NOT_BE_BLANK	File content cannot be empty. Occurs when sending a non-text message to which no content has been attached.
MESSAGE_CONTENT_SIZE_EXCEEDED	Content exceeds the size allowed for WhatsApp.
MESSAGE_TEXT_CAN_NOT_BE_BLANK	Text message cannot be empty.
CHANNEL_NOT_FOUND	The channel through which the message is sent was not found in the integration.
CHANNEL_BLOCKED	The channel through which the message is sent is off.
MESSAGE_DOWNLOAD_CONTENT_ERROR	Failed to download content from the specified link.
MESSAGES_NOT_TEXT_FIRST	On the "Start" tariff you cannot write first.
MESSAGES_IS_SPAM	Wazzup rated this message as spam.
CHAT_WRONG_CHAT_TYPE	Invalid chat type. Occurs when you send an outgoing message to a messenger that is not included in the [INSTAGRAM, WHATSAPP, VK, TELEGRAM] list.
CHAT_MISSING_CHAT_TYPE	chatType not passed. Select the type of chat from the [INSTAGRAM, WHATSAPP, VK, TELEGRAM] list.
CHAT_INCORRECT_CHAT_ID_WHATSAPP	Invalid WhatsApp number. The phone number must be in international format: contain from 9 to 16 digits, for Russian numbers start with 7.
CHAT_MISSING_CHAT_ID	Chat ID not transmitted.
VALIDATION_ERROR	Validation error for the parameter passed to the request.
ACCOUNT_NOT_FOUND	Account not found in integration.
CONTACT_NOT_FOUND The	contact was not found among the account contacts - there is no chat with this phone number.
CHANNEL_NO_MONEY	The channel is not paid and has the status "Not paid".
MESSAGE_CHANNEL_UNAVAILABLE	The channel from which the message is sent is not available. Channel has status "Phone not available" or "Wait a minute".
CONTACT_DETAIL_NOT_FOUND	No contact information.
MESSAGES_ABNORMAL_SEND	The chat type does not match the source of the contact. For example, this error can occur if you are trying to send a message from the WhatsApp channel to the Instagram channel.
MESSAGES_INVALID_CONTACT_TYPE	The chat type does not match the Instagram contact source. For example, this error can occur if you are trying to send a message from the Instagram channel to the WhatsApp channel.
MESSAGES_CAN_NOT_ADD	The message was not sent. An unexpected server error has occurred.
REFERENCE_MESSAGE_NOT_FOUND	An error occurs during quoting if the message to which the quotation is attached could not be found. Verify that the refId is the message ID received from Wazzup.
UNKNOWN_ERROR	Unknown error. Contact support.

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

```

[

  {

    "channelId": string,

    "transport": "whatsapp",

    "plainId": "79865784457",

    "state": "active"

  }

]

```

Request result data

Parameter	Type	Description
channelId	String	Channel id (uuidv4)
transport	String	Channel type (messenger). Possible values: whatsapp instagram
plainId	String	Phone number or instagram channel account
state	String	Channel 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

```json

{

  "url": "https://example.com/webhooks"

}

```

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

```json

{

  "webhooksUrl": "https://example.com/webhooks",

  "webhooksUrlChanged": true

}

```

Verifying the address for web hooks

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

HTTP/1.1 200 OK

```json

{

  "webhooksUrl": "https://example.com/webhooks"

}

```

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:

Parameter	Type	Description
messageId	String	Message UUID
channelId	String	Channel id
chatType	String	Addressee messenger chat type. Possible values: “whatsapp”, “whatsgroup”, “instagram”, “telegram”, “vk”
chatId	String	Chat id (contact's account in a messenger): for whatsapp, only numbers, no spaces and special characters, for example "79124698489" for whatsapp group chats, the phone number and group id (10 digits) separated by a hyphen, for example "79124698489-1611143663". for instagram account without "@" in the beginning, for example "wazzuptest"
dateTime	Number	Message timestamp (unix time milliseconds)
type	Number	Message type: 0 – a message of an unsupported type 1 – text 2 – image 3 – audio 4 – video 5 – document 21 – missed call from client
status	Number	A successful transmission status or an error: 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. 99 – An incoming message
text	String	Message text
content	String	Message content link (optional)
authorType	Number	Sender type: 0 – phone 1 – Wazzup interface 3 – amoCRM 4 – planfix 5 – bitrix24 6 — Zoho CRM 7 — Salesforce 8 — Hubspot 9 – Wazzup API 99 — Incoming message from client
authorName	String	Sender's name in whatsapp, if present.
instPost	Object	Instagram post information object
imageSrc	String	Link to full size image
previewSrc	String	Link to image preview

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:

```

{
  id: '2430659146657243411_41370968890',
  src: 'https://www.instagram.com/p/CG7b52ejyET',
  sha1: 'dc8c036b4a0122bb238fc38dcb0391c125e916f2',
  likes: 0,
  author: 'wztestdlv',
  comments: 22,
  timestamp: 1603977171000,
  updatedAt: 1608905897958,
  authorName: '',
  description: 'Красота',
  previewSha1: '3a55c2920912de4b6a66d24568470dd4ad367c34',
  imageSrc: 'https://store.dev-wazzup24.com/dc8c036b4a0122bb238fc38dcb0391c125e916f2',
  previewSrc: 'https://store.dev-wazzup24.com/3a55c2920912de4b6a66d24568470dd4ad367c34'
}

```

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:

Parameter	Type	Description
messageId	String	The id (uuidv4) of the channel that you need to send a message through
status	String	Message 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:

Parameter	Type	Description
channelId	String	Channel id (uuidv4)
transport	String	Channel type (messenger). Possible values: whatsapp instagram
plainId	String	Phone number or instagram channel account
state	String	Channel 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

An example of processing data in PHP received in webhooks

<?php
// Webhooks come in json, convert it
$hook = json_decode(file_get_contents('php://input'));
 
// Channel statuses
if (isset($hook->channels)) {
 foreach ($hook->channels as $channel) {
   // Enumeration of object fields. Here you can do something with the data - for example, put it in the database
   foreach ($channel as $key => $value) {
     error_log("$key : $value");
   }
 }
}
 
// Messages
if (isset($hook->messages)) {
 foreach ($hook->messages as $message) {
   // Enumeration of object fields. Here you can do something with the data - for example, put it in the database
   foreach ($message as $key => $value) {
     error_log("$key : $value");
   }
 }
}
 
// Message statuses
if (isset($hook->statuses)) {
 foreach ($hook->statuses as $status) {
   // Enumeration of object fields. Here you can do something with the data - for example, put it in the database
   foreach ($status as $key => $value) {
     error_log("$key : $value");
   }
 }
}
 
?>

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:

Parameter	Type	Description
channelId	String	Channel id (uuidv4)
transport	String	Channel type (messenger). Possible values: whatsapp instagram
plainId	String	Phone number or instagram channel account
state	String	Channel 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

Users are profiles that you create in CRM for your employees. These are not your clients, but your managers, support staff, accountants, etc.
To get a list of users in the integration, send a GET request to https://api.wazzup24.com/v2/users.

Request result example

```json

[

{

  "id": "2e0df379-0e3c-470f-9b36-06b9e34c3bdb", // id пользователя

  "name": "User Name"                           // имя пользователя

},

...

]

```

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

```json

{

  "id": "2e0df379-0e3c-470f-9b36-06b9e34c3bdb", // id пользователя

  "name": "User Name"                           // имя пользователя

}

```

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

Parameter	Type	Description
id	any	User identifier A string up to 64 characters long or an integer
name	String	User name. A string up to 150 characters

Request body example

```json

[

  {

    "id": "2e0df379-0e3c-470f-9b36-06b9e34c3bdb",

    "name": "User Name"

  },

  ...

]

```

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

Parameter	Type	Description
id	any	User identifier A string up to 64 characters long or an integer
name	String	User name. A string up to 150 characters

Request body example

```json

[

  {

    "id": "2e0df379-0e3c-470f-9b36-06b9e34c3bdb",

    "name": "User Name"

  },

  ...

]

```

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

Adding and updating the contact list

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

When adding a contact list, contact information from CRM will be loaded into Wazzup. This will not create dialogues in the general chat. The dialog will be created when you send an outgoing message, receive an incoming message, or when you open a chat in CRM from a contact or deal card.

When updating the contact list, an array with contact data is loaded and the contacts are compared by id. If contact information is not in Wazzup, it will be added. If there is information about the contact, the data for the contact will be updated.

Parameter	Type	Description
id	any	Contact id in the CRM. String or number
responsibleUserId	any	Id 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.
name	String	Contact name
chats	Object	An array of objects with details for a contact containing: chatType – string chatId – string or number
deals	Object	An array of deals related to the contact. A deal id can be a string or number

Obtaining the contact list

To get a list of contacts for which information was uploaded from CRM to Wazzup, send a GET request to https://api.wazzup24.com/v2/contacts. Up to 100 records can be retrieved in one request.

Additional request parameters

Parameter	Type	Description
offset	Number	Pagination offset; a non-negative integer. The default is 0
orderBy	String	Sorting field. The default is id; you can also sort by name, or responsibleUserId
orderDirection	String	Sorting direction, asc (default) or desc

Request result data

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

Parameter	Type	Description
id	any	Contact id in the CRM. String or number
responsibleUserId	any	Id of the responsible user. String or number.
name	String	Contact name
chats	Object	An array of objects with details for a contact containing: chatType – string chatId – string or number
deals	Object	An array of deals related to the contact. A deal id can be a string or number

Obtaining information about a specific contact

To receive information about a separate contact downloaded from CRM to Wazzup, send a GET request to https://api.wazzup24.com/v2/contacts/{contact id}.

The query result data will come in the form of an object with the following parameters:

Parameter	Type	Description
id	any	Contact id in the CRM. String or number
responsibleUserId	any	Id of the responsible user. String or number.
name	String	Contact name
chats	Object	An array of objects with details for a contact containing: chatType – string chatId – string or number
deals	Object	An array of deals related to the contact. A deal id can be a string or number

Deleting a contact

To delete contact information from Wazzup, send a DELETE request to https://api.wazzup24.com/v2/contacts/{contact id}. If there is a dialogue with this contact in the general chat, it will remain there.

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:

Parameter	Type	Description
offset	Number	Pagination offset; a non-negative integer. The default is 0
orderBy	String	Sorting field. The default is id; you can also sort by name, or responsibleUserId
orderDirection	String	Sorting direction, asc (default) or desc

Request result data

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

Parameter	Type	Description
id	Number	Deal id. A Mandatory field
responsibleUserId	any	Responsible user id. String or number
name	String	Deal name
closed	Boolean	A flag marking closed deals
contacts	Object	An 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:

Parameter	Type	Description
id	Number	Deal id. A Mandatory field
responsibleUserId	any	Responsible user id. String or number
name	String	Deal name
closed	Boolean	A flag marking closed deals
contacts	Object	An 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

Parameter	Type	Description
id	Number	Deal id. A Mandatory field
responsibleUserId	any	Responsible 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.
name	String	Deal name
closed	Boolean	A flag marking closed deals
contacts	Object	An 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}.

Wazzup Help

Unanswered messages counter and Chats window

Obtaining an API Key

Opening the Chats window

Unanswered messages counter

Available API methods

Sending messages

Obtaining the channel list

Enabling web hooks and obtaining the current url value

Verifying the address for web hooks

Webhooks

New messages

Outgoing message status update

Channel status update

An example of processing data in PHP received in webhooks

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

Working with the user entity

Obtaining the user list

Obtaining information about a specific user

Updating the user list

Replacing the user list

Deleting a user

Working with contacts

Adding and updating the contact list

Obtaining the contact list

Obtaining information about a specific contact

Deleting a contact

Working with a deal list

Obtaining a deal list

Obtaining information about a specific deal

Updating a deal list

Deleting a deal