Webhooks

Как отправляем вебхуки и что ждем в ответ

Вебхуки отправляем методом 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 с параметрами:

При подключении на указанный 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
}

Ошибки

Помимо общих ошибок для всех роутов могут быть:

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

Чтобы проверить установленный адрес для получения вебхуков, вызовите:

 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, в значении которого лежит массив объектов со следующими параметрами:

Пример

Вид объекта с информацией о посте 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-объект с ключом statuses, в значении которого будет лежать массив объектов со следующими параметрами:

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

Вебхуки о том, что нужно создать новый контакт, сделку

Отправляем, когда нужно создать контакт или сделку в CRM. Это происходит в 3 случаях:

Кейс 1: в п. 3 настроек интеграции выбрано «Нового клиента получает первый ответивший менеджер».

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

Вебхук отправляем, только если получили id сотрудника, который ответил на сообщение нового клиента.

Кейс 2: в п. 3 настроек интеграции выбрано «Менеджеры получают новых клиентов по очереди».

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

Чтобы вебхуки приходили в первом и втором кейсах, нужно в ЛК добавить сотрудников и включить кому-то из них в настройках интеграции ползунок «Получает новых клиентов».

Кейс 3: при нажатии на кнопку создания сделки в «чемодане» в чатах 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 - по кнопке в «чемодане»
},
}

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

Если контакт или сделка уже есть в CRM и создавать новую сущность не следует — нужно прислать объект уже существующего контакта или сделки.

Изменение статуса канала

Пример

{
    "channelsUpdates": [
        {
            "channelId": "d9e5721c-ce2b-444f-9627-60a8129d7e1f",
            "state": "qr",
            "timestamp": 1603977171000,
            "qr": "data:image/png;base64,iVBORw0KGgoAAAANS"
        }
    ]
}

Значения статуса канала (state)

Изменение статуса модерации шаблона WABA

Пример

{
  templateStatus: {
    templateGuid:"8d255e5d-aefd-44dc-8131-c3ad6c3ab28c",     
    name: "Test",     
    status: approved   
} 
}

Значения статуса (status)