WAZZUP Help

API

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

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

https://{subdomain}.wazzup24.com/api/v1.1/send_message

Заголовки

Тело запросов и ответов в формате JSON.

В заголовках запроса необходимо указывать «Content-type» = «application/json», а также ключ API в заголовке «Authorization».

Чтобы получить ключ войдите в личный кабинет Wazzup и добавьте интеграцию по API: Настройки → Интеграции → Добавить → API.

Headers-example

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

ПараметрТипОписание
transportStringТранспорт отправки (указывать «whatsapp» или «instagram»)
fromStringНомер телефона канала отправки в международном формате без спец.символов или имя Instagram-аккаунта (то, которое указывали при подключении канала)
toStringНомер телефона получателя в международном формате без спец.символов или имя Instagram-аккаунта получателя
textStringТекст сообщения (до 10000 символов)
contentStringСсылка на контент (Например, «https://picrutre-hoster.com/pic123.jpg»)
refId GUIDID сообщения при цитировании для whatsapp или ID поста в Instagram при ответе в комментарии

Body-example

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

В случае успеха в ответ будет оправлен результат HTTP/1.1 201 OK и guid созданного сообщения

HTTP/1.1 201 OK

В случае неверного токена будет отправлен результат HTTP/1.1 401 Unauthorized.
В случае серверной ошибки будет возвращено HTTP/1.1 5xx — можно попробовать еще раз.
В случае некорректного запроса будет отправлен HTTP/1.1 400 Bad request.

HTTP/1.1 404 Bad request

Код ошибки Описание
MESSAGE_TEXT_TO_LONG Слишком длинный текст сообщения
MESSAGE_CHANNEL_NOT_FOUNDКанал с таким номером не найден в аккаунте
MESSAGE_INCORRECT_PHONEНекорректный номер телефона получателя или некорректное имя Instagram-аккаунта
MESSAGE_ONLY_TEXT_OR_CONTENTМожет быть заполнен только текст или контент
MESSAGE_NOTHING_TO_SEND Не заполнен ни текст, ни контент
MESSAGE_CHANNEL_DISABLEDКанал отправки выключен
MESSAGE_WRONG_TRANSPORTНекорректный тип транспорта
MESSAGE_CHANNEL_TARIFF_IS_NOT_ENOUGHНа тарифе «Старт» нельзя писать первым и отправлять контент
MESSAGE_DOWNLOAD_CONTENT_ERRORНе удалось скачать контент
MESSAGE_WRONG_CONTENT_TYPEТип контента не поддерживается
MESSAGES_CONTENT_CAN_NOT_BE_BLANKФайл с контентом не может быть пустым, т.е. вес файла должен быть больше нуля
MESSAGES_TEXT_CAN_NOT_BE_BLANKТекстовое сообщение не может быть пустым
MESSAGES_CONTENT_SIZE_EXCEEDEDПревышен максимальный размер отправляемого контента (ограничение — 50 мб)
MESSAGES_IS_SPAMWazzup оценил это сообщение, как спам

Веб-хуки

Веб-хуки отправляем на указанный URL до момента получения статуса HTTP/1.1 200 OK или до исчерпания всех попыток. URL для веб-хуков можно установить в личном кабинете при добавлении интеграции. Если интеграция по API у вас уже установлена — удалите ее и добавьте заново:

Появится окно, выберите значение «Интеграция по API»:

Далее введите URL для получения веб-хуков:

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

  1. Сразу в момент наступления события
  2. Через 1 секунду
  3. Через 3 секунды
  4. Через 5 секунд
  5. Через 10 секунд
  6. Через 30 секунд
  7. Через 60 секунд
  8. 3 попытки с интервалом в 5 минут
  9. 3 попытки с интервалом в 1 час
  10. 30 попыток с интервалом в 24 часа

Веб-хук отправляется в формате JSON и может содержать 3 массива с обновлениями.

1. Новые сообщения (messages)

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

ПолеТипОписание
guidStringГуид сообщения
channelStringНомер телефона канала
phoneStringНомер телефона контакта или аккаунт Instagram
dateTimeNumberВремя сообщения (unix time milliseconds)
typeNumberТип сообщения:
0 — сообщение неподдерживоемого типа
1 — Текст
2 — Изображение
3 — Аудио
4 — Видео
5 — Документ
statusNumber Статус сообщения. 99 — входящее сообщение, статусы исходящих см. в таблице ниже
textStringТекст сообщения
contentStringСсылка на контент сообщения (может отсутствовать)
senderTypeNumberТип отправителя (может отсутствовать):
0 — Телефон
1 — Интерфейс Wazzup
2 — API Wazzup
3 — amoCRM
4 — planfix
5 — bitrix24
refIdStringId цитируемого сообщения. Для Instagram наличие этого поля означает, что это сообщение в комментариях, если его нет — это директ.
usernameStringИмя отправителя в whatsapp, если оно есть.
instPostObject Объект с информацией о посте Instagram.

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

2. Обновления статусов исходящих сообщений (statuses)

Все обновления статусов сообщений «в очереди», «отправлено» и тд, отправляются в API с помощью веб-хуков. Их дальнейшая обработка зависит от разработчика.

Обычно так: отправлено → доставлено → прочитано. Но иногда бывают проблемы. Подробнее о значении ошибок отправки сообщения читайте в отдельной инструкции.
Важно: 13 — у клиента нет WhatsApp или Instagram, некуда слать.
Если после 1 долго не приходит 2 или 3, возможно надо связываться иначе — клиент перестал пользоваться WhatsApp или Instagram или у него нет интернета.

Если во время отправки сообщения канал перешел в статус «Выключен», «Удален» и «Не оплачен» — сообщения не становятся в очередь на отправку и не отправляются клиенту. API в этом случае получает сообщение об ошибке. Важно правильно его обработать и предупредить пользователя, что сообщение не отправлено.

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

Подробное описание статусов сообщений и рекомендации по их исправлению читайте здесь.

3. Изменения состояния каналов (channels)

По разным причинам статус канала может меняться. «Active» — хороший статус, остальные — не очень, надо что-то сделать.

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

Обо всех изменениях статуса придет веб-хук.

ПолеТипОписание
channelStringНомер телефона канала или имя Instagram-аккаунта канала
stateStringСостояние канала:
active — канал активен, все нормально
disabled — канал выключен
phoneUnavailable — нет связи с телефоном
qr — необходимо отсканировать qr-код
openElsewhere — приложение открыли в другом месте
notEnoughMoney — канал не оплачен