Как отправляем вебхуки и что ждем в ответ
Вебхуки отправляем методом POST на указанный URI. Он может включать в себя query string.
Если у нас есть ваш crmKey, мы добавляем заголовок Authorization: Bearer ${crmKey}. Если нет — не добавляем заголовок Authorization вообще.
Вебхуки содержат в теле JSON и соответствующий заголовок Content-Type: application/json; charset-utf-8. В JSON закодирован объект со свойствами, которые соответствуют типам вебхуков.
Вебхуки о новых сообщениях и изменении их статуса могут содержать объекты messages и statuses одновременно. Вебхук о необходимости создать контакт или сделку содержит только один объект: createContact или createDeal.
В ответ ожидаем код 200 OK. В некоторых случаях ждем определенную информацию в теле ответа. Таймаут — 30 с.
Как подключить вебхуки
Чтобы подписаться на вебхуки, вызовите:
PATCH https://api.wazzup24.com/v3/webhooks
В теле должен быть JSON с параметрами:
Параметр | Тип | Описание |
webhooksUri | String | Адрес для получения вебхуков. Не более 200 символов |
subscriptions | Object | Настройки вебхуков |
subscriptions.messagesAndStatuses | Boolean | Вебхук о новых сообщениях и вебхук об изменении статуса исходящих.
Если вебхук нужен, укажите true. Если нет — false. |
subscriptions.contactsAndDealsCreation | Boolean | Вебхук о том, что нужно создать новый контакт или сделку.
Если вебхук нужен, укажите true. Если нет — false. |
subscriptions.channelsUpdates | Boolean | Вебхук об изменении статуса канала.
Если вебхук нужен, укажите true. Если нет — false. |
subscriptions.templateStatus | Boolean | Вебхук об изменении статуса модерации шаблона WABA.
Если вебхук нужен, укажите true. Если нет — false. |
При подключении на указанный url будет отправлен тестовый POST запрос с телом {test: true }. В ответ сервер должен вернуть 200 при успешном подключении вебхуков. Иначе вернется ошибка: Webhooks request not valid. Response status must be 200.
Пример запроса
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 } }'
Пример ответа
{ ok }
Ошибки
Помимо общих ошибок для всех роутов могут быть:
Ошибка | Описание |
400 Bad Request, { error: ‘uriNotValid’, description: ‘Provided URI is not valid URI’ } | При неверном по формальным признакам URI |
400 Bad Request, { error: ‘testPostNotPassed’, description: ‘URI does not return 200 OK on test request’, data: { ‘${код ответа}’ } } |
Если была получена ошибка при отправке тестового запроса на указанный URL |
Проверка адреса для получения вебхуков
Чтобы проверить установленный адрес для получения вебхуков, вызовите:
GET https://api.wazzup24.com/v3/webhooks
Пример ответа
HTTP/1.1 200 OK ```json { "webhooksUri": "https://example.com/webhooks", "subscriptions": { "messagesAndStatuses": "true", "contactsAndDealsCreation": "true" } } ``
Вебхук о новых сообщениях
Вебхук пришлет JSON-объект с ключом messages, в значении которого лежит массив объектов со следующими параметрами:
Параметр | Тип | Описание |
messageId | String (uuid4) | guid сообщения в Wazzup |
channelId | String (uuid4) | ID канала |
chatType | String | Тип чата. Доступные значения:
|
chatId | String | ID чата (аккаунт контакта в мессенджере):
|
avitoProfileId | String | Id профиля Авито. Не то же, что chatId.
avitoProfileId всегда один и тот же для аккаунта Авито, chatId — уникальный для чата. То есть у одного и того же avitoProfileId могут быть разные chatId. |
dateTime | String | Время отправки сообщения, указанное мессенджером в формате yyyy-mm-ddThh:mm:ss.ms |
type | String | Тип сообщения:
|
status | String | Содержит в себе только значение из ENUM из вебхука statuses:
|
error | Object | Приходит, если status: error |
error.error | String | Код ошибки:
|
error.description | String | Описание ошибки |
text | String | Текст сообщения. Может отсутствовать, если сообщение с контентом |
contentUri | String | Ссылка на контент сообщения. Может отсутствовать, если сообщение не содержит контента |
authorName | String | Имя пользователя, отправившего сообщение, если оно есть. Может быть только у сообщений isEcho == true |
authorId | String | Идентификатор пользователя CRM |
isEcho | Boolean | Если сообщение входящее — false. Если исходящее, отправленное не из этого API (с телефона, или из iframe) — true |
instPost | Object | Информация о посте из Instagram. Прикладывается к комментарию в Instagram |
contact | Object | Информация о контакте |
contact.name | String | Имя контакта |
contact.avatarUri | String | URI аватарки контакта. Прикладывается, если аватарка есть у Wazzup |
contact.username | String | Только для Telegram. username (имя пользователя) контакта в Telegram, без @ в начале |
contact.phone | String | Только для Telegram. Телефон контакта в международном формате |
interactive | Interactive | Массив объектов с кнопками Salesbot amoCRM прикрепленных к сообщению |
quotedMessage | Object | Cодержит в себе объект с параметрами цитируемого сообщения |
Пример
Вид объекта с информацией о посте Instagram
{ id: '2430659146657243411_41370968890', src: 'https://www.instagram.com/p/CG7b52ejyET', sha1: 'dc8c036b4a0122bb238fc38dcb0391c125e916f2', likes: 0, author: 'wztestdlv', comments: 22, timestamp: 1603977171000, updatedAt: 1608905897958, authorName: '', authorId: '78596324', description: 'Красота', previewSha1: '3a55c2920912de4b6a66d24568470dd4ad367c34', imageSrc: 'https://store.dev-wazzup24.com/dc8c036b4a0122bb238fc38dcb0391c125e916f2', previewSrc: 'https://store.dev-wazzup24.com/3a55c2920912de4b6a66d24568470dd4ad367c34' }
Вебхук про обновление статусов исходящих сообщений
Вебхук отправляет JSON-объект с ключом messages, содержащий массив объектов со следующими параметрами:
Параметр | Тип | Описание |
messageId | String | guid сообщения в Wazzup |
timestamp | String | Время получения информации об обновлении статуса |
status | String | Статус сообщения, на который обновился: ENUM (‘sent’|’delivered’|’read’|’error’) |
error | Object | Приходит, если status: error |
error.error | String | Код ошибки |
error.description | String | Описание ошибки |
error.[data] | String | Дополнительная информация об ошибке |
{ "messages": [ { "messageId": "be3dc577-60c4-4fc8-83a5-8c358e0bfe15", // guid сообщения, об обновлении статуса которого мы оповещаем "timestamp": "2025-02-05T06:01:07.499Z", // время получения информации об обновлении статуса "status": "delivered" } ] }
Вебхуки о том, что нужно создать новый контакт, сделку
Отправляем, когда нужно создать контакт или сделку в CRM. Это происходит в 3 случаях:
Кейс 1: в п. 3 настроек интеграции выбрано «Нового клиента получает первый ответивший менеджер».
Пишет новый клиент. Сотрудник ему отвечает. Wazzup отправляет вебхук о создании нового контакта и сделки на первое исходящее, если из CRM загружены воронки с этапами.
Кейс 2: в п. 3 настроек интеграции выбрано «Менеджеры получают новых клиентов по очереди».
Пишет новый клиент. Wazzup отправляет вебхук о создании нового контакта и сделки на первое входящее, если из CRM загружены воронки с этапами.
Кейс 3: при нажатии на кнопку «+» в списке «Сделки» для создания сделки:
Мы проверяем, создан ли контакт у нас в базе.
Если контакт уже создан, мы отправляем вебхук о необходимости создания сделки:
{ createDeal: { responsibleUserId: '1', // id выбранного по очереди или первого ответившего пользователя contacts: ['1'] // связь сделки с новым контактом source: 'auto'|'byUser', // auto - при входящем или исходящем, byUser - по кнопке в списке «Сделки» }, }
Если контакт отсутствует, мы сначала отправляем вебхук о необходимости создания контакта:
{ createContact: { responsibleUserId: '1', // id выбранного по очереди или первого ответившего пользователя name: 'contacts.name', // имя контакта из таблицы contacts contactData: [{ chatType, chatId }], source: 'auto'|'byUser', // auto - при входящем или исходящем, byUser - по кнопке }, }
После этого CRM должна создать контакт и вернуть в ответе 200 OK с JSON-объектом новой сущности, соответствующим сигнатуре CRUD-роутов контактов.
Затем мы отправим вебхук о необходимости создания сделки.
После чего CRM должна создать сделку и аналогично вернуть 200 OK с JSON-объектом, соответствующим сигнатуре CRUD-роутов сделок.
Изменение статуса канала
Параметр | Тип | Описание |
channelId | String | guid канала |
state | String | Cтатуса канала |
qr | String | QR-код в формате base64, присутствует только при state ‘qr’ |
qridle | String | канал разавторизован или QR-код протух |
timestamp | Integer | Время установки статуса в мс |
Пример
{ "channelsUpdates": [ { "channelId": "d9e5721c-ce2b-444f-9627-60a8129d7e1f", "state": "qr", "timestamp": 1603977171000, "qr": "data:image/png;base64,iVBORw0KGgoAAAANS" } ] }
Значения статуса канала (state)
Значение | Описание | Виды транспорта |
active | Канал активен, все нормально | Все |
disabled | Канал выключен. Такой статус может быть только во время технических работ | Все |
qr | Необходимо отсканировать qr-код | whatsapp и tgapi |
phoneUnavailable | Нет связи с телефоном. Устаревшее, но изредка может проявляться при проблемах в самом WhatsApp или на старых версиях приложения WhatsApp на телефоне | |
openElsewhere | WhatsApp Web открыли в другом месте | |
notEnoughMoney | Канал не оплачен | Все |
unauthorized | Не авторизован — надо заново авторизовать канал | Все |
Изменение статуса модерации шаблона WABA
Параметр | Тип | Описание |
templateGuid | String | guid шаблона |
name | String | Имя шаблона |
status | String | Статус модерации шаблона |
Пример
{ templateStatus: { templateGuid:"8d255e5d-aefd-44dc-8131-c3ad6c3ab28c", name: "Test", status: approved } }
Значения статуса (status)
Значение | Описание |
APPROVED | То же, что «Активен» в ЛК Wazzup. Шаблон одобрен Meta, его можно использовать |
PENDING | То же, что «На модерации» в ЛК Wazzup. Meta еще проверяет шаблон |
REJECTED | В ЛК Wazzup — «Отклонен». Шаблон не прошел модерацию Meta |
PAUSED | В ЛК Wazzup — «Отклонен». На шаблон жаловались получатели, поэтому Meta его снова проверяет |
DISABLED | В ЛК Wazzup — «Отклонен». Шаблон заблокировали после жалоб |