Wazzup База знаний по сервису

wz-help-logo-part

База знаний

Webhooks

Вебхуки отправляются нами на указанный с помощью соответствующих роутов URI. Он может включать в себя query string.

В случае, если нам предоставлен crmKey, мы добавляем заголовок Authorization: Bearer ${crmKey}. Если не предоставлен, не добавляем заголовок Authorization вообще.

Вебхуки всегда отправляются методом POST и содержат в теле 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”: “https://someuri.com/”, // длина не более 200 символов
“subscriptions”: {  //  Отсутствие аналогично false
“messagesAndStatuses”: true, // подписка на вебхуки о сообщениях и их статусах, может не требоваться, если используется интеграция через CRM
“contactsAndDealsCreation”: true // подписка на вебхуки о создании сущностей
}
}

В значении url укажите адрес для получения веб-хуков.

При подключении на указанный 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 '{
"webhooksUril": "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
Общие ошибки для всех роутов

Проверка адреса для получения веб-хуков

Для проверки текущего установленного callback URL, необходимо вызвать

 GET https://api.wazzup24.com/v3/webhooks
Пример ответа
 HTTP/1.1 200 OK
```json
{
"webhooksUrl": "https://example.com/webhooks",

“subscriptions”: {

“messagesAndStatuses”: “true”,

“contactsAndDealsCreation”: “true”

}

}
``

Новые сообщения

Веб-хук пришлет JSON-объект с ключом messages, в значении которого лежит массив объектов со следующими параметрами:

Параметр Тип Описание
messageId String (uuid4) guid сообщения в Wazzup
channelId String (uuid4) Id канала
chatType String Тип чата мессенджера-адресата. Доступные значения «whatsapp», «instagram», «telegram», «vk»
chatId String Id чата (аккаунт контакта в мессенджере):

для whatsapp только цифры, без пробелов и спец. символов, например “79124698489”

для instagram аккаунт без «@» вначале, например “wazzuptest”

dateTime String время отправки сообщения, указанное мессенджером в формате yyyy-mm-ddThh:mm:ss.ms
type String Тип сообщения:

text‘— текст

image‘ — изображение

audio‘ — аудио

video‘ — видео

document‘ — документ

‘vcard’ — карточка контакта

‘geo‘ — геолокация

‘wapi_template’ — Шаблона WABA

‘unsupported’ — неподдерживаемый тип

‘missing_call‘ — пропущенный звонок

Иначе — ‘unknown‘ — неизвестная ошибка

status String Статус сообщения есть только, если isEcho == true.
Содержит в себе только значение из ENUM из вебхука statuses:‘sent’ — отправлено — (аналог одной серой галки)‘delivered’ — доставлено (аналог двух серых галок)‘read’ — прочитано (аналог двух голубых галок)Иначе — “error”Виды ошибок:
BAD_CONTACT’ — для instagram: такой аккаунт Instagram не существует. Возможно, клиент изменил имя профиля‘TOO_LONG_TEXT’ — слишком длинный текст сообщения

‘BAD_LINK’ — фильтры Instagram не пропускают сообщение из-за ссылки

‘TOO_BIG_CONTENT’ — размер файла не должен превышать 50 Mb

‘SPAM’ — сообщение не отправлено из-за подозрения на спам

‘TOO_MANY_EXT_REQS’ — отправка прервана. С аккаунта поступило слишком много сообщений

‘WRONG_CONTENT’ — контент файла не подходит под параметры Instagram

‘MESSAGE_CANCELLED’ — Отправка сообщения прекратилась

’24_HOURS_EXCEEDED’ — 24-часовое диалоговое окно закрыто [WABA]

‘COMMENT_DELETED’ — Комментарий был удален [inst]

‘MENTION_FORBIDDEN’ — отмеченного в сообщение пользователя (mentioned) нельзя отмечать

‘CONTENT_CONVERSION_ERROR’ — контент не удалось конвертировать

‘MESSAGE_DELETED’ — сообщение было удалено отправителем

‘CHATID_IGSID_MISMATCH’ — Не удалось сопоставить ChatId с IGSID [inst]

‘7_DAYS_EXCEEDED’ — 7-дневное диалоговое окно закрыто [inst]

‘COMMENT_ALREADY_PRIVATE_REPLIED’ — На этот комментарий уже ответили в директ [inst]

‘COMMENT_INVALID_FOR_PRIVATE_REPLY’ — Невозможно ответить на этот комментарий в директ [inst]

‘COMMENT_CAN_BE_TEXT_ONLY’ — На комментарий можно отвечать только в текстовом формате [inst]

‘CANNOT_REPLY_TO_DELETED’ — Нельзя ответить на сообщение, потому что пользователь его удалил.

‘GENERAL_ERROR’ — произошла ошибка. Информация уже направлена
разработчикам Wazzup

‘UNKNOWN_ERROR’ — произошла неизвестная ошибка. Повторите попытку позже.

99 — входящее сообщение

text String Текст сообщения. Может отсутствовать, если сообщение с контентом
contentUri String Ссылка на контент сообщения (может отсутствовать, если сообщение не содержит контента)
authorName String Имя отправителя в whatsapp, если оно есть. Может быть только у сообщений isEcho == true
instPost Object Объект с информацией о посте Instagram
isEcho Boolean Если сообщение входящее — false, если исходящее, отправленное не из этого АПИ (с телефона, или из iframe) — true
instPost Object Информация о посте из Instagram, Прикладывается, когда сообщение является комментарием в инстаграме
contact.name String Имя контакта
contact.avatarUri String URI автарки контакта. Прикладывается, если аватарка есть у Wazzup

Вид объекта с информацией о посте Instagram

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

Обновление статусов исходящих сообщений

Веб-хук пришлет JSON-объект с ключом statuses, в значении которого будет лежать массив объектов со следующими параметрами:

Параметр Тип Описание
messageId String Id канала (uuidv4), через который нужно отправить сообщение
timestamp Number UNIX timestamp — время получения информации об обновлении статуса
status String статус сообщения, на который обновился: ENUM (‘sent’|’received’|’read’|’error’)
[error] Object Опционально, приходит только когда “status’:”error”

error.error — код ошибки,
error.description — описаание ошибки
error.[data] — дополнительная информация об ошибке

 statuses: [
{
"messageId": "00010203-0405-0607-0809-0a0b0c0d0e0f", // guid сообщения, об обновлении статуса которого мы оповещаем
"timestamp": "2021-12-14T20:00:05+00:00", // UNIX timestamp - время получения информации об обновлении статуса
"status":read"
}
]

Вебхуки createContact, createDeal

Отправляются, когда требуется создать контакт или сделку в интегрированной СРМ. Это может произойти в двух случаях:

Кейс 1: пишет новый клиент, Wazzup отправляет вебхук о создании нового контакта и сделки, если из CRM загружены воронки с этапами.

Кейс 2: при нажатии на кнопку создания сделки в инструменте чемодан, внутри чатов Wazzup.

 {
createContact: {
responsibleUserId: '1', // id выбранного по очереди или первого ответившего пользователя
name: 'contacts.name', // имя контакта из таблицы contacts
contactData: [{ chatType, chatId }],
source: 'auto'|'byUser', // auto - при входящем, byUser - по кнопке
},
}
 {
createDeal: {
responsibleUserId: '1', // id выбранного по очереди или первого ответившего пользователя
contacts: ['1'] // связь сделки со свежесозданным контактом
source: 'auto'|'byUser', // auto - при входящем, byUser - по кнопке в чемодане
},
}

При получении этого вебхука СРМ должна создать контакт или сделку, и вернуть в теле ответа 200 OK JSON c объектом созданной сущности, соответствующий сигнатуре объекта, принятого для работы роутов CRUD контактов и сделок. Если контакт или сделка уже существуют в CRM, и CRM считает, что создавать новую сущность не следует, то необходимо прислать объект уже существующего контакта или сделки.