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.


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




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



"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 Contains only value from ENUM of webhook “statuses”:

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

‘delivered’ — delivered (same as two grey 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 dialogue box is closed [WABA]

‘COMMENT_DELETED’ — the 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 dialogue 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.

‘CHANNEL_REJECTED’ — the message was not sent, because the channel is rejected.

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 guid Wazzup messages
timestamp String 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", // is the time of receiving status update information




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.