WAZZUP Help

Интеграция по API

Для интеграции с API Wazzup разработан набор методов для отправки сообщений, работы с сущностями пользователя, канала, контакта и сделки, получение событий веб-хуков.

API позволяет легко встроить дополнительный интерфейс с чатами Wazzup в любую CRM-систему, а также использовать счетчик неотвеченных.

Оглавление

Счетчик неотвеченных и окно чатов

Получение API Key

  1. Зайдите в «Интеграции» в настройках личного кабинета.
  2. Нажмите .
  3. Выберите «Интеграция по API».
  4. Готово — теперь вы можете скопировать свой ключ API.

Открытие окна чатов

Чтобы открыть окно чата, отправьте POST запрос на роут https://api.wazzup24.com/v2/iframe:

1. Укажите ключ API в заголовке запроса «Authorization».

Headers-example

Параметры запроса

ПараметрТипОписание
userObjectОбъект, который содержит информацию о пользователе
user.idInteger/StringId пользователя в crm-системе, открывающего окно с чатом
user.nameStringИмя пользователя. В дальнейшем используется в качестве имени отправителя
scopeStringКонтекст, в котором открывается окно, где:
"global" для общего чата
"card" для чата в карточке сущности
filterObject (Array)Массив объектов с чатами, которые нужно показать. Обязателен, когда scope = card
filter.chatTypeStringТип чата мессенджера. Доступные значения "whatsapp", "instagram"
filter.chatIdStringId чата (аккаунт контакта в мессенджере):
для whatsapp — только цифры, без пробелов и спец. символов
для instagram — аккаунт без "@" вначале
filter.nameStringНеобязательный параметр, который содержит имя контакта
activeChatObjectЧат, активный при открытии Iframe
activeChat.chatTypeStringТип чата мессенджера. Доступные значения “whatsapp”, “instagram”
activeChat.chatId Integer/StringId чата (аккаунт контакта в мессенджере):
для whatsapp только цифры, без пробелов и спец. символов)
для instagram аккаунт без “@” вначале

Если контакта с указанными chatType и chatId нет в базе данных Wazzup — при открытии его в карточке контакта CRM-системы он будет создан. В качестве имени будет использовано значение name или  chatId, если первое отсутствует.

Пример тела запроса

В ответе придет json с ссылкой для открытия окна чатов.

Пример успешного ответа

В случае ошибки в ответе поступит json, содержащий свойство error, или http-код 500.

Пример ответа с ошибкой

Счетчик неотвеченных

Для использования счётчика неотвеченных подключитесь к веб-сокету на https://api-ws.wazzup24.com.

При подключении сгенерируйте  событие apiV2IframeConnecting и отправьте объект, содержащий API key и id пользователя:

После этого при изменениях в количестве неотвеченных сообщений данные будут приходить в событии apiV2Notify в виде объекта:

Пример с использованием socket.io:

Доступные методы для работы с API

Отправка сообщения 

POST https://api.wazzup24.com/v2/send_message

Параметры запроса

ПараметрТипОписание
channelIdStringId канала (uuidv4), через который нужно отправить сообщение
chatTypeStringТип чата мессенджера-адресата. Доступные значения "whatsapp", "instagram"
chatIdStringId чата (аккаунт контакта в мессенджере):
для whatsapp — только цифры, без пробелов и спец. символов)
для instagram — аккаунт без "@" вначале
textStringТекст сообщения (до 10000 символов). Обязателен, если не указан content
contentStringСсылка на файл для отправки. Обязателен, если не указан text
refMessageIdStringId сообщения для цитирования. Необязательный параметр

Пример тела запроса

Результат запроса

HTTP/1.1 201 OK

Получение списка каналов

GET https://api.wazzup24.com/v2/channels

Результат запроса

В ответе придет массив с информацией о каналах, указанных в настройках личного кабинета Wazzup в разделе «Интеграции»:

HTTP/1.1 200 OK

Данные результата запроса

ПараметрТипОписание
channelIdStringId канала (uuidv4)
transportStringТип канала (мессенджер). Доступные значения:
whatsapp
instagram
plainIdStringНомер телефона или аккаунт instagram-канала
stateStringСостояние канала:
active — канал активен, все нормально
disabled — канал выключен
phoneUnavailable —  нет связи с телефоном
qr — необходимо отсканировать qr-код
openElsewhere — приложение открыли в другом месте
notEnoughMoney — канал не оплачен

Подключение веб-хуков и получение текущего значения url

PUT https://api.wazzup24.com/v2/webhooks

Пример тела запроса

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

При подключении на указанный url будет отправлен тестовый запрос. Сервер должен вернуть 200 при успешном подключении веб-хуков.

В ответе придет вновь установленный адрес для веб-хуков и информация о том, отличался ли предыдущий url от переданного (в значении ключа webhooksUrlChanged).

HTTP/1.1 200 OK

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

GET https://api.wazzup24.com/v2/webhooks

HTTP/1.1 200 OK

Веб-хуки

Wazzup присылает веб-хуки трех типов.

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

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

ПараметрТипОписание
messageIdStringUUID сообщения
channelIdStringId канала
chatTypeStringТип чата мессенджера-адресата. Доступные значения "whatsapp", "instagram"
chatIdStringId чата (аккаунт контакта в мессенджере):
для whatsapp  только цифры, без пробелов и спец. символов)
для instagram аккаунт без "@" вначале
dateTimeNumberВремя сообщения (unix time milliseconds)
typeNumberТип сообщения:
0 — сообщение неподдерживоемого типа                                   
1 — текст                                       
2 — изображение                                     
3 — аудио
4 — видео
5 — документ
21 — Пропущенный звонок от клиента
statusNumberСтатус успешной отправки сообщения или ошибки:
1 — отправлено (аналог одной серой галки)
2 — доставлено (аналог двух серых галок)
3 — прочитано (аналог двух голубых галок)                                            
13 — для whatsapp: клиент, которому адресовано сообщение, не установил приложение или привязал его к другому номеру
13 — для instagram: такой аккаунт Instagram не существует. Возможно, клиент изменил имя профиля
14 — слишком длинный текст сообщения
15 — фильтры Instagram не пропускают сообщение из-за ссылки
17 — размер файла не должен превышать 50 Mb
18 — сообщение не отправлено из-за подозрения на спам
19 — отправка прервана. С аккаунта поступило слишком много сообщений
21 — контент файла не подходит под параметры Instagram
66 — произошла ошибка. Информация уже направлена разработчикам Wazzup
99 — входящее сообщение
textStringТекст сообщения
contentStringСсылка на контент сообщения (может отсутствовать)
authorTypeNumberТип отправителя:
0 — телефон 
1 — интерфейс Wazzup                                           
3 — amoCRM                                            
4 — planfix                                            
5 — bitrix24                                            
6 — Zoho CRM                                           
7 — Salesforce                                            
8 — Hubspot
9 — API Wazzup  
99 — Входящее сообщение от клиента
refMessageIdStringId цитируемого сообщения. Для Instagram наличие этого поля означает, что это сообщение в комментариях. Если его нет — это сообщение из директа
authorNameStringИмя отправителя в whatsapp, если оно есть
instPostObjectОбъект с информацией о посте Instagram

Наличие поля instPost говорит о том, что входящее сообщение фактически является комментарием к посту в Instagram. У сообщений Whatsapp и директа в Instagram этого поля нет.

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

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

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

ПараметрТипОписание
messageIdStringId канала (uuidv4), через который нужно отправить сообщение
statusStringСтатус сообщения:
0 — сообщение в обработке
1 — отправлено (аналог одной серой галки)
2 — доставлено (аналог двух серых галок)  
3 — прочитано (аналог двух голубых галок)
13 — для whatsapp: клиент, которому адресовано сообщение, не установил приложение или привязал его к другому номеру      
13 — для instagram: такой аккаунт Instagram не существует. Возможно, клиент изменил имя профиля.
14 — слишком длинный текст сообщения
15 — фильтры Instagram не пропускают сообщение из-за ссылки
17 — размер файла не должен превышать 50 Mb
18 — сообщение не отправлено из-за подозрения на спам
19 — отправка прервана. С аккаунта поступило слишком много сообщений
21 — контент файла не подходит под параметры Instagram
66 — произошла ошибка. Информация уже направлена разработчикам Wazzup

Обновление состояния каналов

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

ПараметрТипОписание
channelIdStringId канала (uuidv4)
transportStringТип канала (мессенджер). Доступные значения:
whatsapp
instagram
plainIdStringНомер телефона или аккаунт instagram-канала
stateStringСостояние канала:
active — канал активен, все нормально
disabled — канал выключен
phoneUnavailable —  нет связи с телефоном
qr — необходимо отсканировать qr-код
openElsewhere — приложение открыли в другом месте
notEnoughMoney — канал не оплачен

Изменение списка каналов в интеграции (приходит новый список каналов)

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

ПараметрТипОписание
channelIdStringId канала (uuidv4)
transportStringТип канала (мессенджер). Доступные значения:
whatsapp
instagram
plainIdStringНомер телефона или аккаунт instagram-канала
stateStringСостояние канала:
active — канал активен, все нормально
disabled — канал выключен
phoneUnavailable —  нет связи с телефоном
qr — необходимо отсканировать qr-код
openElsewhere — приложение открыли в другом месте
notEnoughMoney — канал не оплачен

Работа с сущностью пользователя

Получение списка пользователей

Для получения списка пользователей в интеграции отправьте GET запрос на https://api.wazzup24.com/v2/users.

Пример результата запроса

Получение информации об отдельном пользователе

Для получения информации об отдельном пользователе в интеграции отправьте GET запрос на https://api.wazzup24.com/v2/users/{id пользователя}.

Пример результата запроса

Обновление списка пользователей

Чтобы добавить нового пользователя или изменить имя у существующего реализован роут для обновления списка пользователей в интеграции.

Отправьте PATCH запрос на https://api.wazzup24.com/v2/users.

В теле запроса должен прийти массив с данными о пользователях. Пользователей сравниваем по id. Если такого пользователя нет в Wazzup, то добавим, если есть, то обновим данные для него.

Параметры запроса

ПараметрТипОписание
idanyИдентификатор пользователя. Строка до 64 символов или целое число
nameStringИмя пользователя. Строка до 150 символов

Пример тела запроса

Замена списка пользователей

Чтобы полностью заменить список пользователей в интеграции, отправьте PUT запрос на https://api.wazzup24.com/v2/users.

В теле запроса должен прийти массив с данными о пользователях. Имеющаяся информация о пользователях будет удалена, вместо нее будут использованы пришедшие данные.

Параметры запроса

ПараметрТипОписание
idanyИдентификатор пользователя. Строка до 64 символов или целое число
nameStringИмя пользователя. Строка до 150 символов

Пример тела запроса

Удаление пользователя

Для удаления пользователя из интеграции отправьте DELETE запрос на https://api.wazzup24.com/v2/users/{id пользователя}.

Работа с контактами

Получение списка контактов

Для получения списка контактов отправьте GET запрос на

https://api.wazzup24.com/v2/contacts. В одном запросе можно получить до 100 записей.

Дополнительные параметры запроса

ПараметрТипОписание
offsetNumberСмещение по пагинации, целое неотрицательное число. По умолчанию — 0
orderByStringПоле для сортировки. По умолчанию id, также можно сортировать по name или responsibleUserId
orderDirectionStringНаправление для сортировки; asc (по умолчанию) или desc

Данные результата запроса

Придут в виде массива объектов со следующими параметрами:

ПараметрТипОписание
idanyId контакта. Строка или число
responsibleUserIdanyId ответственного пользователя. Строка или число.
nameStringИмя контакта
chatsObjectМассив объектов с данными для контакта, который содержит:
chatType — string
chatId — string или number
dealsObjectМассив с id сделок, связанных с контактом. Id сделки может быть string или number

Получение информации об отдельном контакте

Для получения информации об отдельном контакте в интеграции отправьте GET запрос на https://api.wazzup24.com/v2/contacts/{id контакта}.

Данные результата запроса

Придут в виде объекта со следующими параметрами:

ПараметрТипОписание
idanyId контакта. Строка или число
responsibleUserIdanyId ответственного пользователя. Строка или число.
nameStringИмя контакта
chatsObjectМассив объектов с данными для контакта, который содержит:
chatType — string
chatId — string или number
dealsObjectМассив с id сделок, связанных с контактом. Id сделки может быть string или number

Обновление списка контактов

Для обновления списка контактов отправьте PATCH запрос на https://api.wazzup24.com/v2/contacts.

В теле запроса должен прийти массив с данными о контактах. Контакты сравниваются по id. Если контакта нет в Wazzup, то он будет добавлен, если есть, то данные для него будут обновлены.

Параметры запроса

ПараметрТипОписание
idanyId контакта. Строка или число
responsibleUserIdanyId ответственного пользователя. Строка или число. Заполните это поле, чтобы диалог отобразился в окне чата Wazzup для ответственного за контакт. Работает при использовании настройки п. 3 «Только свои диалоги и диалоги из своих очередей».
nameStringИмя контакта
chatsObjectМассив объектов с данными для контакта, который содержит:
chatType — string
chatId — string или number
dealsObjectМассив с id сделок, связанных с контактом. Id сделки может быть string или number

Удаление контакта

Для удаления контакта отправьте DELETE запрос на https://api.wazzup24.com/v2/contacts/{id контакта}.

Работа со списком сделок

Получение списка сделок

Для получения списка сделок отправьте GET запрос на

https://api.wazzup24.com/v2/deals. В одном запросе можно получить до 100 записей.

Дополнительно можно передать в query string следующие параметры:

ПараметрТипОписание
offsetNumberСмещение по пагинации, целое неотрицательное число. По умолчанию — 0
orderByStringПоле для сортировки. По умолчанию id, также можно сортировать по name или responsibleUserId
orderDirectionStringНаправление для сортировки; asc (по умолчанию) или desc

Данные результата запроса

Придут в виде массива объектов со следующими параметрами:

ПараметрТипОписание
idNumberId сделки. Обязательное поле
responsibleUserIdanyId ответственного пользователя. Строка или число
nameStringНазвание сделки
closedBooleanФлаг, отмечающий закрытые сделки
contactsObjectМассив с id контактов, связанных со сделкой. Id контактов может быть string или number

Получение информации по отдельной сделке

Для получения информации об отдельной сделке отправьте GET запрос на https://api.wazzup24.com/v2/deals/{id сделки}

Данные результата запроса

Придут в виде объекта со следующими параметрами:

ПараметрТипОписание
idNumberId сделки. Обязательное поле
responsibleUserIdanyId ответственного пользователя. Строка или число
nameStringНазвание сделки
closedBooleanФлаг, отмечающий закрытые сделки
contactsObjectМассив с id контактов, связанных со сделкой. Id контактов может быть string или number

Обновление списка сделок

Для обновления списка сделок отправьте PATCH запрос на https://api.wazzup24.com/v2/deals.

В теле запроса придет массив с данными о сделках. Сделки сравниваются по id. Если такой сделки нет в Wazzup, то она будет добавлена, если есть, то данные для нее будут обновлены.

Параметры запроса

ПараметрТипОписание
idNumberId сделки. Обязательное поле
responsibleUserIdanyId ответственного пользователя. Строка или число. Заполните это поле, чтобы диалоги с контактами, связанными со сделкой, отобразились в окне чата Wazzup для ответственного за сделку. Работает при использовании настройки п. 3 «Только свои диалоги и диалоги из своих очередей».
nameStringНазвание сделки
closedBooleanФлаг, отмечающий закрытые сделки
contactsObjectМассив с id контактов, связанных со сделкой. Id контактов может быть string или number

Удаление сделки

Для удаления сделки отправьте DELETE запрос на

https://api.wazzup24.com/v2/deals/{id сделки}.