Integration by API

Contents

API entities and terminology

Integration schemes

Connection methods

Authorization

Sending messages

Working with channels

Working with the user entity

Working with contacts

Working with a list of deals

Loading sales funnels

Webhooks

Chat window (iFrame)

Common errors

WAuth

Migration of API v2 users to API v3

API entities and terminology

Channel

A channel is a customized way of communicating with customers, such as WhatsApp or Telegram. You need to understand that the type of channel and the channel are different things. A channel refers to a specific messenger account in which work is being done: a specific WhatsApp account, a specific bot in Telegram, a specific group in VK.

By “type of channel” is meant a specific messenger (WhatsApp, Instagram, Telegram, etc.). So you can have several channels for each “channel type”.

For example:

  • WhatsApp Support channel
  • WhatsApp channel “Support USA +1”
  • Sales channel on Instagram.
Users

Users are profiles created in the CRM. These are not your customers who write to the chat, but, for example, managers or support employees who respond to requests.

Contact

Contact is an entity that connects the user and the customer who has written. In other words, it is a kind of “contact card” where the client’s contact information (phone number to contact in WhatsApp, id in telegram, username in instagram) and the manager responsible for him are stored.

Deal

A deal is an entity combining one or more contacts, which has a responsible user. In CRM terminology, this entity is most often represented as an “order” or the same “deal”.

Example: the same customer is communicating about the purchase of new doors and floor coverings, thus the customer is trying to close two different tasks and needs two different managers to consult, therefore two different transactions with the same contact but different responsible managers should be created.

Roles

Roles. In order for users to see incoming messages from WhatsApp channels and correspond from those channels, they need to be granted access.

The level of access is set when selecting an employee’s role from the Wazzup interface in the integration settings. Currently there are 3 roles available:

  • Quality Control — sees all managers’ correspondence, but cannot write anything.
  • Sales rep — can write only to those customers for whom he/she is responsible in the CRM. Does not see correspondence of other managers.
  • Manager — sees correspondence of all managers and can write to any client.

Understanding the role model can play an important role in creating integrations. For example, you may notice that the “sales rep” role sees dialogs with constraints, we regulate them with the “contact” and “deal” entities.

Suitcase

Suitcase is a tool in the chat window with a contact that performs the following functions:

  • allows the user to view a list of open and closed deals with the selected contact in which they are responsible and go to their pages in the CRM.
  • allows the user to quickly go to the deal creation page in the CRM.

The suitcase allows the sales rep to quickly obtain information about existing deals and, if necessary, create a new one, which saves him time.

Rules for working with new clients
  1. When a client who is not in CRM writes, it is necessary to set the algorithm of distribution of such appeals and to set the rules for choosing the funnel, in which the deal will be created.
  2. Funnel selection

The Wazzup interface has a setting with an option to select a funnel and a stage for that funnel. Funnels and stages are loaded from the CRM.

  1. Selecting the algorithm for distributing appeals from new customers. There is a setting in the Wazzup interface that allows you to set how appeals from new customers will be distributed to users.
  1. Every new client is assigned to the first respondent — when a new client writes, all users with the role of “sales rep” who have access to Wazzup dialogs (setting item #2) will see this request. As soon as one of the managers responds, the others will lose this chat. The person who responded will become responsible in the CRM.
  2. Sales reps are assigned new clients in turn — all users with the role of “sales rep” who have access to Wazzup dialogs (setting item #2) receive dialogs equally. When a new client writes, only one manager will see the notification and he will be assigned to be responsible in CRM for the client in CRM.

Integration schemes

We have published a set of API methods that can be used to create integrations. We can distinguish two types of integrations:

  1. Public integrations — integrations that are made according to our prepared “schemes” and published in the marketplace of Wazzup integrations. The creator of the integration, who makes it to the publishing stage, can be given the status of a “technical partner,” which gives you a percentage of sales from that integration.
  2. Non-public integrations — integrations that are not published on the integration marketplace. Often made for individual use.

If you want to create a public integration, here are two important conditions:

  • You have to make the integration according to our integration schemes.
  • You have to go through a review.
And here are the schemes

An integration schema is a prepared integration concept that serves two main functions:

  • Maximizes the value to the user from future integration.
  • Simplifies the integration development process, through top-level step-by-step instructions.

To choose the most effective integration scheme for you, you need to first understand the target audience of your CRM or chat platform. This question is primary. It is the answer to it that will allow you to make the right choice that maximizes the benefits of our two products.

Integration with Wazzup can be accomplished through different approaches:

  • Using Wazzup chat interfaces: Wazzup embedded chats (iFrame) or “manager’s personal account”.
  • Using your own interfaces for handling chats. Wazzup acts as a channel provider or “transport” in this case.

We recommend using our chat interfaces for integrations, because:

  • You don’t need to develop/refine/maintain your own interfaces to handle conversations.
  • We are constantly improving our interfaces, making them more usable and valuable to the user, because this is our core product.
  • Technical partners who use the option to integrate using our interfaces can get up to 50% commission, while integrating Wazzup only through API you can only claim up to 25%.
Integration scheme with customer management

This integration scheme is suitable for CRMs whose CA has a long customer record, including transferring it from the sales manager to the account manager.

This scheme is the “classic” and most complete. We recommend taking it as the basis for any integration with us.

Implementation with iFrame
What Why
Set up synchronization of user accounts of your CRM and Wazzup This will help Wazzup have an up-to-date list of your users who will work with Wazzup chats, handling incoming dialogs.
Learn how to open a chat window 1. “Global Chat Window” (“scope”: “global”) — a window with all chats available to the user.

> Global chat window — the place where all chats will be received, which will be seen by all users who have access to Wazzup chats. The icon, on clicking on which, will open the global chat window is recommended to place in a prominent place.

2. “Chat window in contact card” (“scope”: “card”) — a chat window with a specific list of contacts, for example, from a relevant contact card.

> “Chat window in contact card” — a way to quickly open a chat with a specific user. We recommend placing an icon which, when clicked, will open a chat window with a specific user recommended to place in the essence of the contact and deal.

Set up synchronization of your CRM contacts with Wazzup This is necessary in order to:

1. Show dialogs to sales reps who are specified as responsible for the contact

2. Quickly get to the contact card in CRM

3. Initiate a chat from the contact card with contacts who were created in CRM before connecting to Wazzup

Set up synchronization of deals from your CRM with Wazzup This is necessary in order to:

1. Show dialogs to sales reps who are specified as responsible for the transaction

2. A sales rep could see the list of open and closed deals for this contact and be able to quickly get to the deal card in CRM

Set the unanswered counter Gives you an indication that there are unanswered messages. We recommend placing it on the icon that opens the global chat when you click on it
Learn how to receive and process webhooks 1. Webhook on Creating a new contact and deal

2. Receive new messages —> for use in your notification system

3. Channel status update (optional)

Load the funnels with stages This will allow us to send a webhook about the creation of a new contact and deal when a new customer writes
Debug the suitcase tool 1. Check if the links in PATCH /v3/contacts are transferred correctly to display a link button to the contact page in CRM

2. Check the correctness of transferring links in PATCH /v3/deals to display links to existing deals with this contact

3. Learn how to handle webhook Create new deal, when user clicks on “+” from suitcase tool

Set up WAuth 1. Learn how to get state from authRedirectUri

2. Learn how to send POST /connect

Apply for a listing on the Wazzup Integration Marketplace
Integration scheme without client maintenance

This integration scheme is suitable for:

  • CRMs whose target audience does not lead long term customers, but make quick sales, advise users on order status or stock availability
  • CRM or communication platforms with small contact center users up to four people

Peculiarity of the realization scheme:

For this target audience, there is no need for the essence of the transaction, so chat accesses can be regulated at the contact level or, conventionally, not regulated at all: most such companies assign all users the “administrator” role, thereby implementing the “everyone sees everything” scenario.

Implementation with iFrame
What Why
Set up synchronization of user accounts of your CRM and Wazzup This will help Wazzup have an up-to-date list of your users who will work with Wazzup chats, handling incoming dialogs.
Learn how to open a chat window 1. “Global Chat Window” (“scope”: “global”) — a window with all chats available to the user.

> Global chat window — the place where all chats will be received, which will be seen by all users who have access to Wazzup chats. The icon, on clicking on which, will open the global chat window is recommended to place in a prominent place.

2. “Chat window in contact card” (“scope”: “card”) — a chat window with a specific list of contacts, for example, from a relevant contact card.

> “Chat window in contact card” — a way to quickly open a chat with a specific user. We recommend placing an icon which, when clicked, will open a chat window with a specific user recommended to place in the essence of the contact and deal.

Set up synchronization of your CRM contacts with Wazzup This is necessary in order to:

1. Quickly get to the contact card in CRM

2. Ability to initiate a chat from the contact card with contacts who were created in CRM before connecting to Wazzup

Set the unanswered counter Gives you an indication that there are unanswered messages. We recommend placing it on the icon that opens the global chat when you click on it
Learn how to receive and process webhooks 1. Webhook on Creating a new contact and deal

2. Receive new messages —> for use in your notification system

3. Channel status update (optional)

Debug the suitcase tool With the suitcase, a manager can quickly switch between the Wazzup and CRM chat interfaces.

1. Check the correctness of transferring links in PATCH /v3/contacts to display the link button to the contact page in CRM

Set up WAuth 1. Learn how to get state from authRedirectUri

2. Learn how to send POST /connect

Apply for a listing on the Wazzup Integration Marketplace

Connection methods

There are three ways to interact with the Wazzup API:

1. API KEY.

API KEY should be used for debugging integrations before publishing to the integration store or for non-public integrations. The API KEY can be obtained independently from the Wazzup private office.

  1. To get the API KEY you need to:
  2. Register at https://app.wazzup24.com/signup
  3. Add a Channel
  4. Go to the “Integrations” section in your personal cabinet settings.
  5. Choose “API integration”.
  6. Copy the API KEY.
2. wAuth

The system is inspired by OAuth2.0, but technically it is not. This connection method should be used by every technical partner who wants to publish to our integration store. Informally Wauth is needed not to make the user copy and paste API keys, but to connect the integration “on the button”. Read more here.

3. sidecar API KEY

Sidecar API KEY is an API KEY that is generated when you create an integration with Amo and Bitrix. This key can be used if there is a need to refine our existing integration. For example, you can connect Wazzup to your notification system or CDP to implement triggered mailings, while using an AMO or Bitrix integration.

The Sidecar API KEY only works in those routers:

— GET /channels — get channel list;

— POST /sendMessage — sending messages. In this case, in the chats in the personal cabinet the message will look like sent from the “mother” PSA;

— GET /webhooks — get the set address for the webhook;

— PATCH /webhooks — set address for the webhook.

If you set the address for webhooks they will come as described in the instructions. If we observe errors when sending webhooks, after some attempts we will disable webhooks for specific API integration, “mother” integration with Bitrix/AMO will continue to work.

Authorization

In general, for authorization you need API KEY, it can be obtained as follows:

  1. Register at https://app.wazzup24.com/signup
  2. Add a Channel
  3. Go to the “Integrations” section in your personal cabinet settings.
  4. Choose “API integration”.
  5. Copy the API KEY.

To apply the key, specify it as a header value:

 Authorization: Bearer 33a817cbc1504bd5885574d8f0290cd3

Sending messages

To send messages it is necessary to call:

 POST https://api.wazzup24.com/v3/message

In the message body you should pass the parameters of the message with the authorization data in the header.

Request Parameters
Parameter Type Description
channelId String Id of the channel (uuidv4) through which to send the message
chatType String Channel Type. Available values:

INSTAGRAM: ‘instagram’,

TELEGRAM: ‘telegram’,

Telegram group chat: ‘telegroup’,

WHATSAPP: ‘whatsapp’,

WhatsApp group chat: ‘whatsgroup’

chatId String Chat Id (contact’s account in messenger):

  1. for whatsapp — only numbers, without spaces and special characters in the format 79011112233
  2. for instagram — an account without “@” in the beginning
  3. for WhatsApp group chat (‘whatsgroup’) — comes in webhooks of incoming messages
text String Message text. Obligatory if contentUri is not specified. Both text and contentUri cannot be sent at the same time.Both text and contentUri cannot be sent at the same time. For WhatsApp up to 10 000 characters, For Instagram up to 1000 characters
contentUri String A link to the file to send. Required if text is not specified. The content must be downloaded via a link without redirects. An attempt to download content will be made as soon as the request is received, i.e. short-lived links can be made. There may be restrictions on the type and size of content, specific to each messenger. Both text and contentUri cannot be transmitted at the same time.
refMessageId String Id of the message to cite. Optional parameter
crmUserId String CRM user id specified with CRUD users. Not required. If specified, and if such a user already exists, we will save his id and name as when sending via iframe
crmMessageId String Message identifier on the CRM side. Needed to make the routing idempotent. Not required.
username String Optional. For Telegram only.
The username of the Telegram contact, with no “@” at the beginning. Can be used when sending messages via Telegram if chatId is not known
phone String Optional. For Telegram only.
Contact’s phone number in international format, without “+” and other symbols, only numbers, with the correct country code. Can be used when sending messages via Telegram if the chatId is not known

Root is not idempotent! Repeated requests with the same content will result in sending several identical messages. To protect against possible duplicate messages, you can add the crmMessageId property unique to the message. If it was sent, then if another request with the same crmMessageId is received, the message will not be sent, the error 400 Bad Request, { error: ‘repeatedCrmMessageId’, description: ‘You have already sent message with the same crmMessageId’ } will be returned.

Important: In order to send WABA templates in the “text” field you must pass the “template code”, which you can obtain from support. If there are variables in the template, you should replace them with the necessary values at the moment of sending. You can read more about how to add a template and examples of how to use it in the article.

Request example
 curl --location --request POST 'https://api.wazzup24.com/v3/message' \

--header 'Authorization: Bearer c8cf90444023482f909520d454368d27' \

--header 'Content-Type: application/json' \

--data-raw '{

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

"chatType": "whatsapp",

"chatId": "79998887766",

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

}

'
Response
Parameter Type Description
messageId String Message identifier

Specified only when code=OK

Response example

HTTP/1.1 201 OK

 HTTP/1.1 200 OK

{

"messageId": "e0629e11-0f67-4567-92a9-2237e91ec1b9"

}
Errors when sending messages
Error code Description
MESSAGE_WRONG_CONTENT_TYPE Invalid content type. Appears if the content type could not be detected or is not supported.
MESSAGE_ONLY_TEXT_OR_CONTENT The message can contain text or content. You can’t send text and content to WhatsApp and Instagram at the same time.
MESSAGE_NOTHING_TO_SEND No message text was found.
MESSAGE_TEXT_TOO_LONG The length of the text message exceeds 10,000 characters.
MESSAGE_CONTENT_CAN_NOT_BE_BLANK A file with 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 allowable size of 10 MB.
MESSAGE_TEXT_CAN_NOT_BE_BLANK The text message cannot be empty.
CHANNEL_NOT_FOUND The channel through which the message is sent is 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 if you send an outgoing message to a messenger not included in the [INSTAGRAM, WHATSAPP, VK, TELEGRAM] list.

CHAT_MISSING_CHAT_TYPE chatType is not transmitted.

Select the chat type from the [INSTAGRAM, WHATSAPP, VK, TELEGRAM] list.

CHAT_INCORRECT_CHAT_ID_WHATSAPP Incorrect WhatsApp number.

Phone number must be in international format: contain from 9 to 16 digits, for Russian numbers start with 7.

CHAT_MISSING_CHAT_ID chatId is not transmitted.
VALIDATION_ERROR Validation error of the parameter passed to the query.
ACCOUNT_NOT_FOUND Account not found in integration.
CONTACT_NOT_FOUND The contact is not found among the account’s contacts — there is no chat with this phone number.
CHANNEL_NO_MONEY The channel is not paid and has the status of “Not Paid”.
MESSAGE_CHANNEL_UNAVAILABLE The channel from which the message is sent is not available.

The channel has the status “Phone Unavailable” 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 try 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 an Instagram channel to a WhatsApp channel.

MESSAGES_CAN_NOT_ADD The message has not been sent. An unexpected server error occurred.
REFERENCE_MESSAGE_NOT_FOUND An error occurs when quoting if the message to which the quote is attached cannot be found.

Check that the message identifier received from Wazzup is passed as the refId.

UNKNOWN_ERROR Unknown error.

Contact support.

Working with channels

A channel is understood as a specific account in a messenger in which the work is done. By “channel type” we mean messenger (WhatsApp, Instagram, Telegram, etc.). So you can have multiple channels for each “channel type”.

For example, you can have the following list of channels at the same time:

  • “Support” channel in the WhatsApp messenger
  • The “Support USA +1” channel in the WhatsApp messenger
  • The “Sales” channel in Instagram.
Getting the channel list

In order to get a list of channels that are added to work in Wazzup, you must call:

 GET https://api.wazzup24.com/v3/channels
Request example
 curl --location --request GET 'https://api.wazzup24.com/v3/channels' \

--header 'Authorization: Bearer c8cf90444023482f909520d454368d27'

Response example

HTTP/1.1 200 OK

 [

{

"channelId": string,

"transport": "whatsapp",

"plainId": "79865784457",

"state": "active"

}

]
Response parameters
Parameter Type Description
channelId String Channel Id (uuidv4)
transport String Channel type (messenger). Available values: whatsapp instagram
plainId String Phone number or instagram channel account
state String Channel status:

active — channel is active

init — channel is starting

disabled — the channel is turned off

phoneUnavailable — no connection to the phone

qr — qr code must be scanned

openElsewhere — the channel is open in another place

notEnoughMoney — the channel is not paid

foreignphone — channel QR was scanned by another phone number

unauthorized — not authorized (instagram, vk, facebook)

waitForPassword — channel is waiting for a password for two-factor authentication

Working with the user entity

Users are the profiles you create in CRM for your employees. These are not your customers, but your managers or support staff.

The set of methods below will help you set up synchronization of user accounts in your CRM with Wazzup.

Getting a list of users

To get a list of active Wazzup users, you need to call:

 GET https://api.wazzup24.com/v3/users?offset=

This method returns users in pages of 100, taking into account offset, sorted by name.

Request example
 curl --location --request GET 'https://api.wazzup24.com/v3/users' \

--header 'Authorization: Bearer c8cf90444442348we909520d454368d27'
Response

Request result example

 {

 

“count”: “1”,

“data”: [

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

 

"name": "User Name"}                           // user name

 

]

}
Retrieving single user data

To retrieve data on a specific user, you need to call

 GET https://api.wazzup24.com/v3/users/:id

The response will be a JSON like this

{

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

"name": "User Name"} ,

"phone": "79332345432 //user name

]

}
Adding users

To add a new user you need to call

 POST https://api.wazzup24.com/v3/users

In the request body you should pass an array with data about users (not more than 100 in one request). Users are compared by their id: if the user does not yet exist in Wazzup, he will be added, if he exists, his data will be updated.

Parameter Type Description
id* String User identifier. Up to 200 characters
name* String User name. A string of up to 200 characters
phone String The phone number is in international format “79261234567”. If the phone number does not pass the formal validation, there will be no error and the property phone will simply be deleted.

The “phone” field is specified only for the ability to add a user to the mobile application.

Request example
 curl --location --request POST 'https://api.wazzup24.com/v3/users' \

--header 'Authorization: Bearer c8cf90444023482f909520d454368d27' \

--header 'Content-Type: application/json' \

--data-raw '[

{

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

"name": "Alex Salesman",

"phone": "79263334567"

},

{

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

"name": "Kate Supportics",

"phone": "79261234567"

}

]'
Error
Error Description
INVALID_USERS_DATA The body of the request is empty or some of the passed fields are invalid.
TOO_MACH_ENTITIES Entity limit per request exceeded
USER_LIMIT_EXCEEDED Entity limit exceeded

 HTTP/1.1 400 Bad Request
{
"error": "INVALID_USERS_DATA",
"description": "One or more of provided users identifiers are not valid."
"data": [
{
index: 12,
fields: [
"id",
"name"
]
}
]
}

 HTTP/1.1 400 Bad Request
{
"error": "TOO_MACH_ENTITIES",
"description": "Too mach entities per request.",
"data": {
"count": 123,
"limit": 100
}
}

 HTTP/1.1 400 Bad Request
{
"error": "USER_LIMIT_EXCEEDED",
"description": "User limit exceeded.",
"data": {
"limit": 1000,
}
}
Deleting a user

To delete a user, you need to call

 DELETE https://api.wazzup24.com/v3/users/{contact id}
Request example
 curl --location --request DELETE 'https://api.wazzup24.com/v3/users/111-2e0df379-0e3c-470f-9b36' \

--header 'Authorization: Bearer c8cf90444023482f909520d454368d27'

Mass user removal

To delete the list of users, it is necessary to call

 PATCH https://api.wazzup24.com/v3/users/bulk_delete

In the body of the request you must pass an array of IDs of users you want to remove. If the deletion is successful, 200 OK and an empty array will be returned. If the deletion request specified users, some of which are absent in Wazzup, their IDs will be returned as an array in the response.

Working with contacts

Contact is an entity that connects the user and the customer who wrote. This is a kind of “contact card”, where the client’s contact information (phone number to contact in WhatsApp, id in telegram, username in instagram) and the sales rep responsible for him are stored.

Adding and updating the contact list

To add a contact list or change existing ones, send a request

 POST https://api.wazzup24.com/v3/contacts
Parameter Type Description
id* String Contact Id in the CRM system. No more than 100 characters
responsibleUserId* String The Id of the responsible user. No more than 100 characters Fill in this field to have the dialog displayed in the Wazzup chat window of the person responsible for the contact.
name* String Contact Name. No more than 200 characters
contactData* Array An array of objects with contact data that contains:

chatType — string

chatId — string

contactData.chatType* String Messenger type
contactData.chatId* String Chat identifier. Mandatory for all messengers except Telegram. Mandatory for Telegram if no username or phone value is passed.
contactData.username String For Telegram only.
username of a Telegram contact, with no “@” at the beginning. Can be used when sending messages via Telegram if chatId is not known. Obligatory for Telegram if no chatId or phone value is passed.
contactData.phone String For Telegram only.
Contact’s phone number in international format, without “+” and other symbols, only numbers, with the correct country code. Can be used when sending messages via Telegram if the chatId is not known.
Obligatory for Telegram if no chatId or username value is passed.
uri String A link to the contact in the CRM. Not more than 200 characters. If specified, in the “suitcase” tool, the user will be able to see a button leading to the contact’s page in the CRM.
Request example
 curl --location --request POST 'https://api.wazzup24.com/v3/contacts' \

--header 'Authorization: Bearer c8cf90444023482f909520d454368d27' \

--header 'Content-Type: application/json' \

--data-raw '[

{

"id": "1",

"responsibleUserId": "id007",

"name": "Alex New",

 

"uri": "https://link-to-contact-in-crm.com"

},

 

{

"id": "contact-id",

"responsibleUserId": "user-id",

"name": "Supervisor",

"contactData": [

{

"chatType": "whatsapp",

"chatId": "79998881234"

}

]

}

]

'
Errors

In addition to the common errors for all roots, in this one it is still possible:

Error Description
INVALID_CONTACTS_DATA The body of the request is empty or some of the passed fields are invalid.
TOO_MACH_ENTITIES Entity limit per request exceeded

 HTTP/1.1 400 Bad Request
{
"error": "INVALID_CONTACTS_DATA",
"description": "One or more of provided contacts data are not valid."
"data": [
{
index: 12,
fields: [
"responsibleUserId",
]
}
]
}

 HTTP/1.1 400 Bad Request
{
"error": "TOO_MACH_ENTITIES",
"description": "Too mach entities per request.",
"data": {
"count": 123,
"limit": 100,
}
}
Obtaining the contact list

To get the list of contacts it is necessary to call

 GET https://api.wazzup24.com/v3/contacts?offset=

You can get up to 100 records in one query, including offset, sorted by ascending id (ASC).

offset — pagination offset, non-negative integer.

Response

The data from the query result will come in an array of objects with the following parameters:

Parameter Type Description
count Number Total number of contacts
data Object Array with data about the contact
data.id String Contact Id in the CRM system. No more than 100 characters
data.responsibleUserId String Id of the responsible user. No more than 100 characters
data.name String Contact name. No more than 200 characters
data.contactData Object An array of objects with contact data that contains: chatType — string chatId — string
data.uri String A link to the contact in the CRM. Not more than 200 characters. If specified, in the “suitcase” tool, the user will be able to see a button leading to the contact’s page in the CRM.
Getting information about an individual contact

To get information about a single contact uploaded from CRM to Wazzup you need to call

 GET https://api.wazzup24.com/v3/contacts/{contact id}
Request example
 curl --location --request GET 'https://api.wazzup24.com/v3/contacts/111-2e0df379-0e3c-470f-9b36' \

--header 'Authorization: Bearer c8cf904467023482f909520d454368d27'
Response

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

Параметр Тип Описание
id String Contact Id in the CRM system. No more than 100 characters
responsibleUserId String Id of the responsible user. No more than 100 characters
name String Contact name. No more than 200 characters
contactData Object An array of objects with contact data that contains: chatType — string chatId — string
uri String A link to the contact in the CRM. Not more than 200 characters. If specified, in the “suitcase” tool, the user will be able to see a button leading to the contact’s page in the CRM.
Deleting a contact

To delete a contact, call:

 DELETE https://api.wazzup24.com/v3/contacts/{contact id}

If there is a dialog with this contact in the general chat, it will remain there.

Request example
 curl --location --request DELETE 'https://api.wazzup24.com/v3/contacts/111-2e0df379-0e3c-470f-9b36' \

--header 'Authorization: Basic c8cf90444023482f909520d454368d27'
Errors
  • common to all routes
  • 404 Not found if no such contact exists
Deleting multiple contacts

To delete the list of contacts, you need to call

 PATCH https://api.wazzup24.com/v3/contacts/bulk_delete

In the body of the request you must pass an array of id of contacts to be deleted. If the deletion is successful, 200 OK and an empty array will be returned. If you specified contacts in the deletion request, some of which are absent in Wazzup, their IDs will be returned as an array in the response.

Working with a list of deals

A deal is an entity that combines one or more contacts and has a responsible user. In CRM terminology, this entity is most often represented as an “order” or the same “deal”.

Uploading the deals list

To upload a list of deals from CRM to Wazzup, send a request

 POST https://api.wazzup24.com/v3/deals

In the request body you need to send an array with data about deals. Deals are compared by their id, if there is no such deal in Wazzup then it will be added, if there is, then data for it will be updated. You can upload not more than 100 deals in one query.

Request parameters
Parameter Type Description
id Number Deal id. Required field, no more than 100 characters.
responsibleUserId String id of the responsible user. Fill in this field so that the responsible sales rep will have a dialog with the contact from the deal in the Wazzup chat window.
name String Name of the deal, no more than 200 characters
uri string The link to the deal in the CRM. If specified, in the “suitcase” tool, the user will be able to see a list of deals with the contact, in which he/she is responsible and go to their page in the CRM. Optional field, no more than 200 characters
contacts Object An array with the id of the contacts associated with the deal. The id of the contacts can be string
closed Boolean Flag marking closed deals
Request example
 curl --location --request POST 'https://api.wazzup24.com/v3/deals' \

--header 'Authorization: Basic c8cf90444023482f909520d454368d27' \

--header 'Content-Type: application/json' \

--data-raw '[

{

"id": "1",

"responsibleUserId": "id007",

"name": "Daily Deal Test",

"Closed": "False",

"contacts": [

"id":"111-2e0df379-0e3c-470f-9b36"

],

"link": "https://link-to-deal-in-crm.com"

}

]

'

Obtaining the list of deals

To get the list of deals send a GET request to

https://api.wazzup24.com/v3/deals. You can get up to 100 records in one request.

 GET https://api.wazzup24.com/v3/deals?offset=
Request example
 curl --location --request GET 'https://api.wazzup24.com/v3/deals' \

--header 'Authorization: Bearer c8cf90474023482f909520d45f368d27'
Response

The result data will come as an array of objects with the following parameters:

Parameter Type Description
count Number Number of contacts in the response
data Object Array with contact data
data.id String Deal id. No more than 100 characters
data.responsibleUserId String Id of the responsible user. No more than 100 characters. Needed to display a dialog with a contact from a deal to a responsible user in Wazzup chats.
data.name String Contact name. No more than 200 characters
data.contacts Object Array id of contacts with which the transaction is connected, there should be no more than 10
data.uri String A link to the contact in the CRM. Not more than 200 characters. If specified, in the “suitcase” tool, the user will be able to see a button leading to the contact’s page in the CRM.
Getting information on an individual deal

To get information about an individual transaction you need to call:

 GET https://api.wazzup24.com/v3/deals/{deal id}
Response

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

Parameter Type Description
id Number Deal id. Required field, not more than 100 characters.
responsibleUserId String Id of the responsible user. Needed to display a dialog with a contact from a deal to a responsible user in Wazzup chats.
name String Name of the deal, no more than 200 characters
uri string The link to the deal in the CRM. If specified, in the “suitcase” tool, the user will be able to see a list of deals with the contact, in which he/she is responsible and go to their page in the CRM. Optional field, no more than 200 characters
contacts Object An array with the id of the contacts associated with the deal. The id of the contacts can be string
closed Boolean Flag marking closed deals
Deleting a deal

To delete a specific deal, call:

 DELETE https://api.wazzup24.com/v3/deals/{deal id}
Request example
 curl --location --request DELETE 'https://api.wazzup24.com/v3/deals/101' \

--header 'Authorization: Bearer c8cf97644023482f909520d454368d27'
Errors
  • common to all routes
  • 404 Not found if no such deal exists
Deleting multiple deals

To delete a list of contacts you need to call:

 PATCH https://api.wazzup24.com/v3/deals/bulk_delete

In the body of the request you must pass an array of the id of deals you want to delete. If the deletion is successful it will return 200 OK and an empty array. If the deletion request specified deals, some of which are absent in Wazzup, their IDs will be returned as an array in the response.

Loading sales funnels

When writing to a client that is not in the CRM, it is necessary to set the rules for selecting the funnel in which the deal will be created.

To download or update sales funnels with stages, you need to call:

 POST https://api.wazzup24.com/v3/pipelines
Request parameters
Parameter Type Description
id any Id funnel, no more than 100 characters
name string Funnel name, which will be displayed in the integration settings, no more than 100 characters
stages object Array with funnel stages
stages.id string Funnel stage identifier, max 100 characters
stages.name string Name of the funnel stage, no more than 100 characters

If there are no stages in the CRM, but there are several “funnels”, the stages property should be absent.

If stages exists, but equals an empty array, an error will occur.
Request example
 curl --location --request POST

'https://api.wazzup24.com/v3/salesfunnel

' \

--header 'Authorization: Basic c8cf90444023482f909520d454368d27 \

--header 'Content-Type: application/json' \

--data-raw '[

{

{ "id": "3455",

{ "name": "main sales funnel",

{ "stages": [

{

"id": "1",

{ "name": "entered the site",

},

{

{ "id": "2",

{ "name": "registered",

},

{

{ "id": "3",

{ "name": "bought the full version"

}

]

}

]'
Obtaining the list of loaded funnels

To retrieve the list of loaded funnels you need to call:

 GET https://api.wazzup24.com/v3/pipelines
Request example
 curl --location --request DELETE

"https://api.wazzup24.com/v3/pipelines" \

--header 'Authorization: Basic c8cf90444023482f909520d454368d27

Webhooks

Webhooks are sent by us to the URI specified with the corresponding router. This can include a query string.

If crmKey is provided, we add an Authorization: Bearer ${crmKey} header. If not provided, we do not add the Authorization header at all.

Webhooks are always sent by POST and contain JSON in the body (and the corresponding Content-Type: application/json; charset-utf-8 header). An object containing properties corresponding to webhook types is encoded in JSON.

One webhook can contain types “messages” and “statuses” at the same time. Webhooks of types createContact and createDeal always contain only one type.

It is always expected that the request will be completed with code 200 OK. In some cases, described below, we expect certain information in the body of the response. The standard timeout is 30 s.

Connecting

To subscribe to webhooks, you must invoke:

 PATCH https://api.wazzup24.com/v3/webhooks

The body must contain JSON

 {

"webhooksUri": "https://someuri.com/", // length not more than 200 characters

{ "subscriptions": { // no similar to “false”

"messagesAndStatuses": true, // subscribe to webhooks about messages and their statuses, may not be required if CRM integration is used

"contactsAndDealsCreation": true // subscribe to webhooks about creating entities

}

}

In the “url” value, specify the address to receive webhooks.

When connecting to the specified url, a POST test request {test: true } will be sent, in reply to which the server should return 200 if webhooks are successfully connected, otherwise a :”Webhooks request not valid. Response status must be 200″.

Request example
 curl --location --request PATCH 'https://api.wazzup24.com/v3/webhooks' \

--header 'Authorization: Bearer w11cf3444405648267f900520d454368d27' \

--header 'Content-Type: application/json' \

--data-raw '{

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

 

“subscriptions”: {

 

“messagesAndStatuses”: true,

 

“contactsAndDealsCreation”: true

 

}

}'

Response example
 {

 

ok

 

}
Errors
Error Description
400 Bad Request, { error: ‘uriNotValid’, description: ‘Provided URI is not valid URI’ } If the URI is incorrect according to the formal characteristics
400 Bad Request, { error: ‘testPostNotPassed’, description: ‘URI does not return 200 OK on test request’, data: { ‘${код ответа}’ } } If there was an error when sending a test request to the specified URL
Common errors for all routes
Checking the address for receiving webhooks

To check the currently set callback URL, call

 GET https://api.wazzup24.com/v3/webhooks
Response example
 HTTP/1.1 200 OK

``json

{

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

 

{ "subscriptions": {

 

{ "messagesAndStatuses": { "true",

 

{ "contactsAndDealsCreation": "true"

 

}

 

}

``

New messages

The webhook will send a JSON object with the messages key, the value of which is an array of objects with the following parameters:

Parameter Type Description
messageId String (uuid4) guid Wazzup messages
channelId String (uuid4) Channel id
chatType String The chat type of the recipient’s messenger. Available values “whatsapp”, “instagram”, “telegram”, “vk”
chatId String Chat Id (contact’s account in messenger):

  1. for whatsapp – only numbers, without spaces and special characters in the format 79011112233
  2. for instagram – an account without “@” at the beginning
  3. for WhatsApp group chat (‘whatsgroup’) – it comes in webhooks of incoming messages
  4. for Telegram – telegram GUID, username and phone number, if any, are sent to contact.phone and contact.username
dateTime String the message sending time specified by the messenger in the format yyyy-mm-ddThh:mm:ss.ms
type String Message type:

text‘— text

image‘ — image

audio‘ — audio

video‘ — video

document‘ — document

‘vcard’ — contact card

‘geo‘ — geolocation

‘wapi_template’ — WABA template

‘unsupported’ — unsupported type

‘missing_call‘ — missed call

Otherwise — ‘unknown‘ — unknown error

status String Message status exists only if isEcho == true.

Contains only value from ENUM of webhook “statuses”:

‘sent’ — sent (same as one gray check mark)

‘delivered’ — delivered (same as two gray check marks)

‘read’ — read (same as two blue check mark)

Otherwise — “error

Error types:

BAD_CONTACT’ — for instagram: such an Instagram account does not exist. The client may have changed the profile name

‘TOO_LONG_TEXT’ — message text is too long

BAD_LINK’ — Instagram filters don’t let a post through because of a link

‘TOO_BIG_CONTENT’ — file size should not exceed 50 Mb

‘SPAM’ — the message was not sent due to a suspicion of spam

‘TOO_MANY_EXT_REQS’ — sending was interrupted. Too many messages from the account

‘WRONG_CONTENT’ — the content of the file does not fit the Instagram parameters

‘MESSAGE_CANCELLED’ — message sending stopped

’24_HOURS_EXCEEDED’ — the 24-hour dialog box is closed [WABA]

‘COMMENT_DELETED’ — comment was deleted [inst]

‘MENTION_FORBIDDEN’ — the tagged user (mentioned) in the message cannot be tagged

‘CONTENT_CONVERSION_ERROR’ — content could not be converted

‘MESSAGE_DELETED’ — the message was deleted by the sender

‘CHATID_IGSID_MISMATCH’ — failed to match ChatId with IGSID [inst]

‘7_DAYS_EXCEEDED’ — the 7-day dialog box was closed [inst]

‘COMMENT_ALREADY_PRIVATE_REPLIED’ – this comment has already been answered in direct [inst]

‘COMMENT_INVALID_FOR_PRIVATE_REPLY’ — it is impossible to reply to this comment in direct [inst]

‘COMMENT_CAN_BE_TEXT_ONLY’ — you can only reply to comments in text format [inst]

‘CANNOT_REPLY_TO_DELETED’ — you can’t reply to a message because the user deleted it

‘GENERAL_ERROR’ — There was an error. Information has already been sent to the Wazzup developers

‘UNKNOWN_ERROR’ — an unknown error has occurred. Please try again later.

inbound — incoming message

text String Message text. May not be present if the message has content
contentUri String Link to message content (may not exist if the message does not contain content)
authorName String The sender’s name, if there is one. Only present in messages isEcho == true
isEcho Boolean If the message is incoming — false, if it is outgoing, sent not from this API (from a phone or iframe) — true
instPost Object Information about the post from Instagram. Applied when the post is an Instagram comment
contact.name String Contact name
contact.avatarUri String The URI of the contact’s avatar. Applied if an avatar is in Wazzup
contact.username String For Telegram only.
username of a Telegram contact, with no “@” at the beginning.
contact.phone String Telegram only.
Contact phone number in international format.
quotedMessage Object Contains an object with the parameters of the quoted message.

A view of the object with information about the Instagram post

 {

id: '2430659146657243411_41370968890',

src: 'https://www.instagram.com/p/CG7b52ejyET',

sha1: 'dc8c036b4a0122bb238fc38dcb0391c125e916f2',

likes: 0,

author: 'wztestdlv',

comments: 22,

timestamp: 1603977171000,

updatedAt: 1608905897958,

authorName: '',

description: 'Beauty',

previewSha1: '3a55c2920912de4b6a66d24568470dd4ad367c34',

imageSrc: 'https://store.dev-wazzup24.com/dc8c036b4a0122bb238fc38dcb0391c125e916f2',

previewSrc: 'https://store.dev-wazzup24.com/3a55c2920912de4b6a66d24568470dd4ad367c34'

}

Updating the status of outgoing messages

The webhook will send a JSON object with the statuses key, the value of which will contain an array of objects with the following parameters:

Parameter Type Description
messageId String Id of the channel (uuidv4) through which to send the message
timestamp Number UNIX timestamp — the time of receiving status update information
status String the status of the message that was updated: ENUM (‘sent’|’received’|’read’|’error’)
[error] Object Optional, comes only when “status’:”error”

error.error — error code

error.description — error description

error.[data] — more information about the error

  statuses: [

{

"messageId": "00010203-0405-0607-0809-0a0b0c0d0e0f", // guid of the message whose status update we are notifying

"timestamp": "2021-12-14T20:00:05+00:00", // UNIX timestamp is the time of receiving status update information

"status":read"

}

]

Webhooks createContact, createDeal

Sent when a contact or transaction needs to be created in the integrated SRM. This can happen in two cases:

Case 1: writes a new customer, Wazzup sends a webhook about creating a new contact and deal if there are stage funnels loaded from the CRM.

Case 2: When you click on the deal creation button in the suitcase tool, inside the Wazzup chats.

 {

createContact: {

responsibleUserId: '1', // id of the user who was selected in turn or was the first to respond

name: 'contacts.name', // contact name from the contacts table

contactData: [{ chatType, chatId }],

source: 'auto'|'byUser', // auto - on incoming, byUser - by button

},

}

 {

createDeal: {

responsibleUserId: '1', // the id of the user who was selected in turn or was the first to respond

contacts: ['1'] // link of the deal with a newly created contact

source: 'auto'|'byUser', // auto - on incoming, byUser - by the button in the suitcase

},

}

When receiving this webhook, CRM should create a contact or deal, and return a 200 OK JSON in the response body with the created entity’s object corresponding to the signature of the object adopted for CRUD contacts and deals routes. If a contact or deal already exists in CRM and CRM thinks that a new entity should not be created, it is necessary to send an object of an already existing contact or deal.

Chat window (iFrame)

In this section, we’ll look at how you can implement the Wazzup chat window in your CRM or other third-party system.

To open the chat window, you need to call

 POST https://api.wazzup24.com/v3/iframe
Request parameters
Parameter Type Description
user Object The object that contains information about the user
user.id String Id of the user in the CRM system that opens the chat window
user.name String User name. Further used as the sender’s name
scope String The context in which the window opens where:

“global” for general chat

“card” for the chat in the entity card

filter Object (Array) An array of objects with chats to show. Obligatory when scope = card
filter.chatType String The chat type of the messenger. Available values “whatsapp”, “instagram”, “telegram”, “vk”
filter.username String For Telegram only.
The username of a Telegram contact, without the “@” at the beginning. Can be used for Telegram if no chatId is known
filter.chatId String Chat Id (contact’s messenger account):

for whatsapp — only numbers, no spaces or special characters

for instagram — account without “@” in the beginning

filter.name String Optional parameter that contains the name of the contact
activeChat Object Chat, active on opening Iframe
activeChat.channelId String Identifier of the channel in which you want to open an active chat when you open iFrame
activeChat.chatType String The chat type of the messenger. Available values “whatsapp”, “instagram”, “telegram”, “vk”
activeChat.chatId String Chat Id (contact’s messenger account):

for whatsapp — only numbers, no spaces or special characters)

for instagram — account without “@” in the beginning

If a contact with the specified chatType and chatId is not in the Wazzup database, when you open it in the contact card of the CRM system, it will be created. The name will be used as the name, or the chatId if the former is missing.

Request example
 curl --location --request POST 'https://api.wazzup24.com/v3/iframe' \

--header 'Authorization: Bearer c8cf90554027882f912520f454468d27' \

--header 'Content-Type: application/json' \

--data-raw '

{

"user": {

"id": "222555",

"name": "User Name"

},

"scope": "card",

"filter": [

{

"chatType": "whatsapp",

"chatId": "79998887766"

}

],

"activeChat": {

"chatType": "whatsapp",

"chatId": "79998887766"

}

}

'
Response

The response will come with a json with a link to open the chat window.

Response example
{

"url": "https://12345678.wazzup24.com/chat/0e812899-e25b-4a18-a3e4-d1f5890f9de7?token=${token}"

}

 

In case of an error, the response will receive a json containing the error property, or an http code 500.

Error response example
 { "error": { "code": "NO_SUCH_ACCOUNT" }

If you open the link in an iframe, add the allow=”microphone *” attribute to the tag so you can record voice messages from the chat window. If the attribute is not added, the user will see an error when clicking on the microphone icon to record.

 <iframe src="link" allow="microphone *"></iframe>
Unanswered counter

To use the unanswered counter, you must connect to the web socket by url, which must be obtained by calling

 GET https://integrations.wazzup24.com/counters/ws_host/api_v3/:apiKey

where apiKey is the API key of your integration.

In response you will receive a json, where the host field will contain the address to connect to.

Example
 ```

{

 

"host": "ws-counters2.wazzup24.com"

 

}

```
Use the socket.io library, version 4.1.3 to connect.
Connection example
  // The address obtained by accessing `https://integrations.wazzup24.com/counters/ws_host/api_v3/:apiKey`

 

const wsHost = 'ws-counters2.wazzup24.com';

 

// Connection options

 

const connectOptions = {

 

path: '/ws-counters/',

 

transports: ['websocket', 'polling']

 

};

 

// Connection

 

const client = io(`https://${wsHost}`, connectOptions);

Next, generate a counterConnecting event and send an object containing the type, apiKey, and userId fields to complete the connection:

{

 

"type": "api_v3", // Constant value

 

"apiKey": "32a817cbc1594bd5885574d8f0290cd3", // API integration key

 

"userId": "2e0df379" // User Id in CRM

 

}

After successful connection in case of changes in the number of unanswered messages the data will arrive in the counterUpdate event as a { counter: number} object.

Please note that if no role is selected for an employee in point 1 of the integration settings, the counter will come with 0 and the unanswered counter will show nothing. If the employee in step 1 of integration settings has the “Sales rep” role selected, the counter will display unanswered only for those deals and contacts for which the manager was assigned responsible in the CRM. Accordingly, for Wazzup to display unanswered correctly, you need information about the deal, contact and person responsible.

For the counter to show unanswered for all deals, select the “Manager” role for the employee in step 1 of the integration settings.

Full example of connecting to the notification service and getting the unanswered counter:
 <!-- index.html -->

<!-- Connecting library socket.io version 4.1.3 -->

<script src="https://cdn.socket.io/4.1.3/socket.io.min.js"></script>

 

<div id="counter"></div>

// apiKey of integration obtained from the Wazzup personal account

 

const apiKey = '420dadbdd4570844bf3b22629е71';

 

// id of the sales rep from your CRM

 

const userId = 'user1';

 

// Options for connecting to the notification service

 

const connectOptions = {

 

path: '/ws-counters/',

 

transports: ['websocket', 'polling']

 

};

 

// Getting the url to connect to the notification service

 

fetch(`https://integrations.wazzup24.com/counters/ws_host/api_v3/${apiKey}`)

 

.then((response) => response.json())

 

.then((data) => {

 

const { host } = data;

 

// Connecting with socket.io

 

const client = io(`https://${host}`, connectOptions);

 

// Listening to the event 'connect'

 

client.on('connect', () => {

 

// Completing the connection: broadcasting the event 'counterConnecting',

 

// in which we send the customer data

 

client.emit('counterConnecting', {

 

type: 'api_v3',

 

apiKey,

 

userId

 

});

 

});

 

// Connection confirmation

 

client.on('counterConnected', () => console.log('Connected to Wazzup notifications!'));

 

// Updating the unanswered counter

 

client.on('counterUpdate', (data) => {

 

const { counter } = data;

 

document.getElementById('counter').innerHTML = counter;

 

});

 

})

 

.catch((error) => {

 

console.log('Connection error', error);

 

});

Common errors

  • 429 Too Many Requests: if the limit of 1000 requests per minute is exceeded. The counter is reset every minute.
  • 401 Unauthorized
  • 500 Internal server error
  • 403 Forbidden: Requests for routers which are not allowed to use sidecar API KEY can lead to errors

Routes POST /contacts, POST /deals, PATCH /contacts/bulk_delete, PATCH /deals/bulk_delete have a limit on number of entities sent for processing: 100 at a time

Format

When an error occurs, the 4X status code will be returned, and the response body will either be empty or contain JSON of the form:

{

error: 'ERROR CODE',

description: 'CHANNEL_BLOCKED', // a short description of the error in English

[data]: {} // object with additional information. Not obligatory. It is intended to be analyzed by developers to determine the cause of the error.

}

WAuth

The system is inspired by OAuth2.0, but technically it is not. This connection method should be used by every technical partner who wants to publish to our integration store.

Informally Wauth is needed not to force the user to copy and paste API keys, but to connect the integration, as they call it, “on the button”.

Target case from a CRM user who wants to connect Wazzup CRM X:

  1. The user finds CRM X inside the Wazzup integration store;
  2. User clicks “Connect CRM X”;
  3. User is redirected to CRM X;
  4. The user logs in to CRM X and confirms the intent to create the integration;

>>> integration between Wazzup and CRM X is connected

Preparatory steps

Technical partner developers:

  1. Register with Wazzup.
  2. Go to the “integrations” section.
  3. Create integration with API type
  4. Get API KEY -> can start debugging basic integration scenarios (all except WAuth)
  5. When it’s time to work on WAuth, call POST v3/marketplace to pass field values:
  • crmCode — a string of Latin letters, numbers (you can use hyphens and underscores). Serves for internal CRM identification. Unique within Wazzup.
  • authRedirectUri — the address of the page to which the client who set up the integration will be redirected to confirm authorization
  • secret — the key (token), which is used to confirm the installation of integration. Participates only in the “server – server” requests, is never sent to the client

>>> You can start working with Wauth

Description of the WAuth process
  1. The user in the Wazzup LC clicks the “add” integration button.

At this moment:

  • state is generated, in which crmCode and accountId are encoded (which the tech partner passed with POST v3/marketplace)
  • in the query string authRedirectUri, add the state and transfer the user to this link. (authRedirectUri tech.partner also passed via POST v3/marketplace)
  1. The client clicks on the link, performs the authorization process on the CRM side.
  2. If authorization is successful, CRM makes a POST v3/connect request (more about the request). To debug this point, you need to use POST /v3/wauth, which simulates the installation of customer integration.
  3. Upon receiving the request, Wazzup saves the crmKey, generates an apiKey and gives it in the body of the response if all is successful
  4. CRM loads information about users, deals, contacts, funnels with stages and sets URLs for webhooks

>>>> integration is successfully connected

Important: At any stage, a technical partner can ask for test channels to debug the integration. We issue free subscriptions to several channels of different types, so that it is possible to handle all cases, including multichannel.
Publishing in the Wazzup Integration Marketplace

In order to publish, you must:

  1. Implement integration scenarios
  2. Set up authorization with Wauth
  3. Set the CRM name and logo with PATCH v3/marketplace
  4. Write to Wazzup support asking them to publish the integration module. Wazzup technical support will forward the ticket to a reviewer who will verify that the integration works and meets requirements. If everything is OK, the integration will be published, otherwise the module will be returned to the developer for revision and he will receive a notification about it in the chat in which the request for publication was sent.
Connecting the integration hosted in the Marketplace via WAuth

If the user clicked “connect integration”, was successfully navigated to the given link and logged into the CRM, the CRM should make a request for

 POST https://api.wazzup24.com/v3/connect/
This method has a non-standard authorization. The user is identified by the secret property, placed in the request body.

The request body must contain JSON with the values of the following parameters:

Parameter Type Description
state String generated and signed on the Wazzup side of the key, received by the integrator in the first stage of connecting CRM
secret String the secret entered by the administrator of the marketplace CRM
wazzupKey Srting generated by the tech partner, which will come in the header { Authorization: “Bearer {wazzupKey}” } when you send webhooks
 curl --location --request POST 'https://api.wazzup24.comi/v3/connect' \

--header 'Content-Type: application/json' \

--data-raw '

{

"state": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2Vy....",

"secret": "61e5a375-1760-452f-ad73-5318844ffc4f",

"crmKey": "e0629e11-0f67-4567-92a9-2237e91ec1b9",

"name": "Any integration name"

}

'
Response

200 ok

apikey — the key to use * in the Authorization: Bearer {apiKey} header when making requests to Wazzup

Loading Wauth parameters

To update crmCode, authRedirectUri, secret you need to call

 POST https://api.wazzup24.com/v3/marketplace

The request body should contain JSON with the values of the following parameters:

Parameter Type Description
crmCode String A string of Latin letters, numbers (you can use hyphens and underscores). Used for internal CRM identification. Unique within Wazzup. No more than 50 characters.
authRedirectUri String The address of the page to which the user who sets up the integration will be redirected to confirm authorization.
secret String The key (token) that is used to confirm the installation of the integration. Participates only in server-to-server queries.
Request example
 curl --location --request POST 'https://api.wazzup24.com/v3/marketplace' \

--header 'Authorization: Bearer 4a0с541451244aa9a281fba4716da40d' \

--header 'Content-Type: application/json' \

--data-raw '{

"crmCode": "BestCrmInTheWorld",

"secret": "our-secret",

"authRedirectUri": "http://redirect.uri"

}'
Simulation of client integration installation (Wauth test)

To simulate the installation of the integration by the client, you need to call:

 POST https://api.wazzup24.com/v3/wauth

The request body should contain JSON with the values of the following parameters:

Parameter Type Description
type String crmCode specified by the integrator at the moment of POST /v3/marketplace call
Uploading the integration name and logo

To change the logo and the public name of the integration module, you need to call:

 PATCH https://api.wazzup24.com/v3/marketplace

The request body should contain JSON with the values of the following parameters:

Parameter Type Description
crmName String The public name of CRM in English, which will be displayed in the Wazzup Personal Area
logo Object Объект с данными логотипа:

— Transparent or white background

— SVG format

— No internal indentation in the logo

— Company name on the logo in English

logo.name String Logo file name
logo.content String base64-encoded file with the logo
This method can only be invoked when the integration module is under development, i.e. has not yet been reviewed and published in the Wazzup Marketplace. If you need to change the crmName or logo after the module has been published, contact support.
Request example
 curl --location --request PATCH 'https://api.wazzup24.com/v3/marketplace' \

--header 'Authorization: Bearer 4a0b541a61244aa9a281fba4816da48d' \

--header 'Content-Type: application/json' \

--data-raw '{

"crmName": "The Cool CRM",

"logo": {

"name": "the-cool-crm.svg",

"content": "YmFzZTY0LWVuY29kZWQtbG9nby1maWxlLWNvbnRlbnQK"

 

}

}'

Migration of API v2 users to API v3

For technical partners who have clients using API v2 integration, it is necessary to migrate such clients to API v3-supported integration.

Main migration pipeline:

  1. You need to have a working integration on API v3 that is published in the Wazzup Marketplace
  2. When ready to migrate, you need to use POST https://api.wazzup24.com/v3/migration to switch webhooks in users using API v2
  3. Start using API v3 methods for the selected users, instead of API v2 methods. In this case you need to use the same KEY client API that was used to send requests to API v2 for authorization
Method for switching webhooks API v2 to v3

To switch webhooks from API v2 to API v3 at a particular client, you need to call:

 POST https://api.wazzup24.com/v3/migration

In the header you need to pass API KEY technical partner

The body of the request must contain JSON with the values of the following parameters:

Parameter Type Description
clientApiKey String API key of the selected client, which was used to send API v2 requests
webhooksUri String URL, to which webhooks will be sent
subscriptions Object An object with subscriptions to two types of webhooks. Absence is similar to False
subscriptions.messagesAndStatuses Boolean Subscribing to webhooks about messages and their statuses
subscriptions.contactsAndDealsCreation Boolean Subscribing to webhooks about creating entities

You may notice that only one client can be migrated per query —> if the technical partner has N clients, you need to make N queries