Webhooks

In this article, we tell you how to connect webhooks, in what form we send them, and what we expect in response.

How we send webhooks and what we expect in return

We send webhooks using the POST method to the specified URI. It may include a query “string”.

If we have your crmKey, we add the Authorization: Bearer ${crmKey} header. If not, we don’t add the Authorization header at all.

Webhooks contain JSON in the body and the corresponding header Content-Type: application/json; charset-utf-8. An object is encoded in JSON with properties that correspond to webhook types.

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

In response, we expect the code 200 OK. In some cases, we wait for certain information in the body of the response. Timeout — 30 s.

How to enable webhooks

To subscribe to webhooks, you must invoke:

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

The body must contain JSON with parameters:

Parameter Type Description
webhooksUri String Address to receive webhooks. No more than 200 characters
subscriptions Object Webhook settings
subscriptions.messagesAndStatuses Boolean Webhook on new messages and webhook on outgoing status changes.

If the webhook is required, specify “true”. If not, specify “false”.

subscriptions.contactsAndDealsCreation Boolean Webhook about creating a new contact or deal.

If the webhook is required, specify “true”. If not, specify “false”.

subscriptions.channelsUpdates Boolean Webhook about changing the status of the channel.

If the webhook is required, specify “true”. If not, specify “false”.

subscriptions.templateStatus Boolean Webhook about the change in moderation status of the WABA template.

If the webhook is required, specify “true”. If not, specify “false”.

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

In addition to common errors for all routes, there can be:

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

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"
}
}
``

Webhook about 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 Available values:

  • WhatsApp: “whatsapp”,
  • Viber: “viber”,
  • WhatsApp group chat: “whatsgroup”,
  • Instagram: “instagram”,
  • Telegram: “telegram”.
chatId String Chat Id (contact’s account in messenger):

  • for whatsapp and viber — only numbers, without spaces and special characters in the format 79011112233;
  • for instagram — an account without @ at the beginning;
  • for WhatsApp group chat (‘whatsgroup’) — it comes in webhooks of incoming messages;
  • 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,
  • ‘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),
  • ‘error’,
  • ‘inbound’ — incoming message.
error Object Comes if ‘status: error’
error.error String Error types:

  • ‘BAD_CONTACT’ — for WhatsApp and Telegram: the account with this chatId does not exist;
  • ‘CHATID_IGSID_MISMATCH’ — for Instagram: the Instagram account with this chatId 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 WABA dialogue is closed;
  • ‘COMMENT_DELETED’ — the comment on Instagram was deleted;
  • ‘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’ — for Instagram: failed to match ChatId with IGSID;
  • ‘7_DAYS_EXCEEDED’ — the 7-day dialogue on Instagram was closed;
  • ‘COMMENT_ALREADY_PRIVATE_REPLIED’ — this comment on Instagram has already been answered in direct;
  • ‘COMMENT_INVALID_FOR_PRIVATE_REPLY’ — it is impossible to reply to this comment on Instagram in direct;
  • ‘COMMENT_CAN_BE_TEXT_ONLY’ — you can only reply to comments on Instagram by comments only in text format;
  • ‘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.
error.description String Error description
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
authorId String User ID in your CRM
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 Object Information about contact
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
interactive Interactive Array of objects with Salesbot amoCRM buttons attached to the message
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: '',
authorId: '798633247',
description: 'Beauty',
previewSha1: '3a55c2920912de4b6a66d24568470dd4ad367c34',
imageSrc: 'https://store.dev-wazzup24.com/dc8c036b4a0122bb238fc38dcb0391c125e916f2',
previewSrc: 'https://store.dev-wazzup24.com/3a55c2920912de4b6a66d24568470dd4ad367c34'
}

Webhook about 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 String Error code
error.description String Error description
error.[data] String 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
"status":read"
}
]

Webhooks about creating a new contact, deal

Send when you need to create a contact or transaction in CRM. This happens in 3 cases:

Case 1: in item 3 of the integration settings “Every new client is assigned to the first respondent” is selected.

A new client writes. An employee replies to them. Wazzup sends a webhook about new contact and deal creation if funnels with stages are loaded from CRM.

We send the webhook only if we have received the id of the employee who replied to the new customer’s message.
.

Case 2: “Sales reps are assigned new clients in turn” is selected in item 3 of the integration settings.

A new client writes. Wazzup sends a webhook about creating a new contact and deal if funnels with stages are loaded from CRM.

In order for webhooks to come in these two cases, you need to add employees to the personal account and enable one of them in the integration settings to turn on the “Gets new clients” slider.

Case 3: When you click on the deal creation button in the “Deals” dropdown, 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 or outgoing message, 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 or outgoing message, byUser - by the button in the "Deals" dropdown
},
}

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.

Webhook about channel status change

Sent when the channel status changes.

Parameter Type  Description
channelId String Channel guid
state String Channel status
qr String QR code in base64 format, present only with state ‘qr’
timestamp Integer Status setting time in ms
Example
{
    "channelsUpdates": [
        {
            "channelId": "d9e5721c-ce2b-444f-9627-60a8129d7e1f",
            "state": "qr",
            "timestamp": 1603977171000,
            "qr": "data:image/png;base64,iVBORw0KGgoAAAANS"
        }
    ]
}
Channel status values (state)
Value Description Channel types
active The channel is active, everything is fine All
disabled The channel is disabled. Technical, this status can only be during work, fixing the problem All
qr QR code needs to be scanned whatsapp and tgapi
phoneUnavailable There is no connection with the phone. Outdated, but occasionally it can manifest itself in case of problems in the WhatsApp itself or on older versions of the WhatsApp application on the handset whatsapp
openElsewhere WhatsApp web app opened in a different location whatsapp
notEnoughMoney Channel not paid All
unauthorized Not authorized, you need to re-authorize the channel All

Webhook about new moderation status of a WABA template

Parameter Type Description
templateGuid String Template guid
name String Template name
status String Template moderation status
Status values
Value Description
APPROVED  Same as “Active” in Wazzup account. The template is Meta approved and can be used
PENDING  The same as “On moderation” in Wazzup personal account. Meta still validates template
REJECTED  In Wazzup personal account — “Rejected”. The template did not pass Meta moderation
PAUSED  In Wazzup personal account — “Rejected”. Recipients complained about the template, so Meta checks it again
DISABLED  In Wazzup personal account — “Rejected”. The template was blocked after complaints