Отправить сообщение клиенту из своего сайта или сервиса через Wazzup можно одним запросом: POST https://api.wazzup24.com/v3/message с ключом API в заголовке Authorization и телом в формате JSON, где указаны канал, тип чата, получатель и текст. Если канал подключён и клиент доступен, API вернёт код 201 и идентификатор сообщения.
На проектах B2BPRO.KZ к этому запросу обычно приходят после одной и той же истории: форма на сайте собирает заявки, менеджер вручную копирует номер в мессенджер и пишет «Здравствуйте, мы получили вашу заявку». Это занимает минуты, а клиент за это время успевает написать конкурентам. Автоматическая отправка через API решает задачу за секунды, но у неё есть несколько ограничений, о которых лучше узнать до разработки, а не после первых недоставленных сообщений.
Что такое Wazzup API и что с его помощью можно сделать
Wazzup API — это набор HTTP-запросов, через которые ваша система управляет каналами Wazzup: отправляет сообщения в WhatsApp, Telegram, Instagram и другие мессенджеры, получает ответы клиентов и синхронизирует контакты и сделки. Для разработчика это обычный REST-интерфейс: адрес, метод, заголовок авторизации и тело в JSON.
Отдельно стоит понимать, зачем он нужен, если у вас уже есть готовая интеграция Wazzup с CRM. Готовая интеграция покрывает типовой сценарий: сотрудник открыл чат в карточке клиента и написал. API нужен, когда пишет не человек, а ваша система. Например, интернет-магазин отправляет подтверждение заказа, сервис записи напоминает о визите, внутренняя учётная система сообщает об оплате счёта. Ещё один случай: у вас собственная CRM или личный кабинет, для которых готового коннектора нет.
Сама отправка в API устроена одинаково для разных мессенджеров. Меняются только значения двух полей: тип чата и идентификатор получателя. Список поддерживаемых типов чатов в документации Wazzup сейчас включает WhatsApp, WhatsApp-группы, Viber, Instagram, Telegram, Telegram-группы, VK, Avito и MAX. Для Казахстана на практике важнее всего WhatsApp и Telegram, поэтому дальше примеры ориентированы на них.
Как получить ключ API и правильно передать его в запросе
Ключ API выдаётся в личном кабинете Wazzup, и получить его можно за минуту. Сначала в разделе «Каналы» должен быть подключён хотя бы один канал. Затем откройте раздел «Интеграция с CRM», выберите API и нажмите «Подключить». Появившийся ключ нужно скопировать. Позже его можно найти в том же разделе на вкладке «Дополнительно».
Ключ передаётся в заголовке Authorization: Bearer ваш_ключ, а тело запроса отправляется с типом Content-Type: application/json. Все детали есть в справке Wazzup об авторизации API.
Ключ даёт доступ к отправке сообщений от имени вашей компании, поэтому обращайтесь с ним как с паролем. Его место на сервере: в переменных окружения или менеджере секретов. Если вы вставите ключ в JavaScript формы на сайте, любой посетитель увидит его в инструментах разработчика браузера. Правильная схема такая: браузер отправляет данные формы на ваш сервер, а сервер уже обращается к Wazzup.
Как отправить первое сообщение через POST /v3/message
Для отправки текста достаточно трёх полей: канал, тип чата и получатель, плюс сам текст. Минимальный запрос выглядит так:
curl -X POST https://api.wazzup24.com/v3/message \
-H "Authorization: Bearer ВАШ_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{
"channelId": "UUID-вашего-канала",
"chatType": "whatsapp",
"chatId": "77011112233",
"text": "Ваша заявка принята, менеджер свяжется с вами в течение часа."
}'Номер и UUID здесь условные, это иллюстрация, а не рабочие данные. При успехе в ответе придут два поля: messageId и chatId. Идентификатор сообщения стоит сохранить: по нему потом приходят статусы доставки, и им можно отредактировать или удалить сообщение.
Основные поля тела запроса собраны в таблице по данным справки Wazzup об отправке сообщений.
| Поле | Обязательное | Что передавать |
|---|---|---|
| channelId | да | UUID канала, через который уходит сообщение |
| chatType | да | Тип чата: whatsapp, telegram, instagram и другие |
| chatId | в основном да | Для WhatsApp и Viber только цифры номера в международном формате, например 79011112233; для Instagram имя без @ |
| text | нет | Текст сообщения; нельзя передавать вместе с contentUri |
| contentUri | нет | Ссылка на файл; нельзя передавать вместе с text |
| crmMessageId | нет | Ваш идентификатор сообщения для защиты от дублей |
| templateId, templateValues | нет | Код шаблона WABA и значения его переменных |
Для Telegram и MAX вместо chatId можно передать phone или username. Для групп, VK и Avito идентификатор берётся из входящих вебхуков, придумать его самому нельзя.
Сколько символов можно отправить в одном сообщении
Предел длины зависит от мессенджера. По документации Wazzup, в WhatsApp можно отправить до 10 000 символов, в Telegram и MAX до 4096, в Instagram, VK и Avito до 1000. Для официального WhatsApp Business API (WABA) лимиты строже: 1024 символа в обычном сообщении и 550 в шаблоне. Если текст не влезает, API вернёт ошибку вида MESSAGES_TOO_LONG для соответствующего мессенджера, поэтому длинные уведомления лучше сокращать на своей стороне заранее.
В WhatsApp, WABA, Viber и Telegram Bot работает простая разметка: подчёркивания для курсива и жирного, обратные кавычки для моноширинного текста, тильды для зачёркнутого. Для Telegram Bot дополнительно принимаются HTML-теги <b>, <i>, <u>, <s> и <code>. Перед выпуском в продакшен пришлите себе тестовое сообщение: на экране телефона разметка выглядит иначе, чем в исходнике.
Как отправить файл, картинку или счёт клиенту
Файл отправляется тем же запросом, только вместо text передаётся contentUri, то есть ссылка на файл. Передать текст и файл в одном запросе нельзя: если нужна подпись, отправляйте два сообщения подряд.
Ссылка должна открываться без редиректов, иначе Wazzup не скачает файл. Скачивание происходит сразу после запроса, поэтому подойдёт и временная ссылка: например, подписанный адрес на ваше файловое хранилище, который действует несколько минут. Это удобно для счетов и договоров, которые не хочется держать на публичном адресе.
Размеры ограничены. Общий предел для контента составляет 10 МБ. Для WABA фото ограничено 5 МБ, остальные файлы 16 МБ. В Telegram фото ограничено 5 МБ, остальные файлы 20 МБ. Голосовые сообщения Telegram до 1 МБ в форматах mp3 и ogg уходят как голосовые, всё остальное доставляется как обычные файлы.
Почему сообщение клиенту не уходит: окно 24 часа и шаблоны WABA
Чаще всего сообщение не уходит потому, что вы пытаетесь первым написать клиенту в официальный WhatsApp Business API. WABA устроен так: начать диалог можно только шаблоном, заранее согласованным в Meta. После ответа клиента открывается 24-часовое окно, и в нём можно писать свободным текстом. Именно поэтому в документации Wazzup сказано, что шаблоны WABA нужны, чтобы начать 24-часовую переписку, а интерактивные сообщения с кнопками разрешено отправлять только внутри уже активной переписки.
Для отправки шаблона в тело запроса добавляются поля templateId с кодом шаблона и templateValues со значениями переменных. Тексты кнопок шаблона в запросе не передаются, они утверждаются вместе с самим шаблоном, а в buttonsObject нужен только payload. Если вы раньше пользовались неофициальным подключением WhatsApp по QR-коду, такого ограничения там нет, но у каждого подключения свои риски. Подробнее мы сравнивали варианты в материале про Wazzup Business API и обычный WhatsApp.
Отдельная ловушка связана с тарифом. По справке Wazzup, на тарифе «Inbox» писать клиенту первым нельзя, и API вернёт ошибку MESSAGES_NOT_TEXT_FIRST. Для автоматических рассылок и уведомлений такой тариф не подходит, и это нужно выяснить до начала разработки, а не после.
Как не отправить клиенту одно сообщение дважды
Запрос на отправку не идемпотентен: если повторить его, клиент получит второе такое же сообщение. Это справедливо и для автоматических повторов, которые делает ваш код или очередь задач при таймауте. Представьте, что сервер Wazzup успел принять сообщение, но ответ дошёл до вас слишком поздно. Ваша система решит, что отправка не удалась, повторит запрос, и клиент увидит одно и то же уведомление дважды.
Защита предусмотрена в API: в поле crmMessageId передайте собственный идентификатор сообщения в вашей системе, например номер записи в таблице уведомлений. Если в течение 60 секунд придёт запрос с тем же значением, Wazzup вернёт ошибку REPEATED_CRM_MESSAGE_ID и не отправит дубль. Окно в 60 секунд короткое, поэтому полностью полагаться на него нельзя. Надёжнее хранить у себя статус каждого уведомления и повторять отправку только для тех, по которым ответ так и не пришёл.
Ещё одно полезное поле называется clearUnanswered. Оно управляет счётчиком неотвеченных чатов: значение false оставляет счётчик нетронутым. Для автоматических уведомлений это полезно, потому что робот не должен «закрывать» чат, который ещё ждёт ответа живого менеджера.
Как получать ответы клиентов и статусы доставки через вебхуки
Ответы клиентов и статусы исходящих сообщений приходят не по запросу, а через вебхуки: Wazzup сам отправляет POST на адрес вашего сервера. Вебхуки подключаются запросом PATCH https://api.wazzup24.com/v3/webhooks. В теле передаются адрес webhooksUri длиной не более 200 символов и объект subscriptions, в котором каждый тип событий включается значением true. Проверить текущие настройки можно запросом GET на тот же адрес. Полное описание есть в справке Wazzup по вебхукам.
Подписаться можно на четыре типа событий:
messagesAndStatuses: новые входящие сообщения и смена статуса исходящих;contactsAndDealsCreation: запрос на создание контакта или сделки;channelsUpdates: изменение статуса канала;templateStatus: результат модерации шаблона WABA.
При подключении Wazzup отправляет на ваш адрес проверочный POST с телом {test: true}, и сервер должен ответить кодом 200. Иначе подключение вернёт ошибку: либо uriNotValid для неверного адреса, либо testPostNotPassed, если адрес не ответил 200. На ответ на каждый вебхук отводится 30 секунд, поэтому тяжёлую обработку лучше выносить в очередь: принять событие, сразу вернуть 200, а разбирать позже.
Про повторную отправку вебхуков при сбое вашего сервера в справке информации нет. Раз гарантий не описано, закладывайте в схему запас прочности: периодически сверяйте историю сообщений, а не рассчитывайте, что ни одно событие не потеряется.
Какие ошибки возвращает API и что с ними делать
Ошибки API Wazzup имеют текстовые коды, по которым можно понять причину, не обращаясь в поддержку. Полный перечень приведён в справке об общих ошибках, а в отправке сообщений чаще всего встречаются такие:
| Код ошибки | Что означает | Что делать |
|---|---|---|
| INVALID_MESSAGE_DATA | Неверное значение параметра; нужное поле указано в data.fields | Проверить формат номера и тип чата |
| WRONG_TRANSPORT | Тип чата не соответствует каналу | Сверить chatType с типом канала |
| CHANNEL_NOT_FOUND, CHANNEL_BLOCKED | Канала нет или он заблокирован | Проверить канал в кабинете |
| CHANNEL_NO_MONEY, BALANCE_IS_EMPTY | Не хватает средств | Пополнить баланс или продлить подписку |
| BAD_CONTACT | Номера нет в WhatsApp | Не повторять отправку на этот номер |
| MESSAGES_IS_SPAM | Сообщение признано спамом | Пересмотреть текст и частоту рассылки |
| TEMPLATE_REJECTED | Шаблон отклонён | Согласовать новый шаблон |
| MESSAGES_NOT_TEXT_FIRST | На тарифе «Inbox» нельзя писать первым | Сменить тариф |
| REPEATED_CRM_MESSAGE_ID | Повтор crmMessageId в течение 60 секунд | Дубль не отправлен, это штатная защита |
Различайте ошибки, которые стоит повторять, и те, которые повторять бессмысленно. Если номера нет в WhatsApp или канал заблокирован, десять повторов ничего не изменят, а в случае спам-метки только навредят репутации номера. Здесь полезно вести журнал: каждый ответ API записывается рядом с уведомлением, чтобы потом можно было понять, почему конкретному клиенту ничего не пришло. Если в ответе встретился код UNKNOWN_ERROR_WITH_TRACE_ID, справка рекомендует обращаться в поддержку Wazzup и приложить идентификатор трассировки.
Можно ли редактировать и удалять уже отправленное сообщение
Да, но с ограничениями. Редактирование выполняется запросом PATCH https://api.wazzup24.com/v3/message/:messageId, удаление запросом DELETE на тот же адрес. За один запрос можно изменить либо текст, либо вложение, но не оба сразу. Сообщения с кнопками изменить нельзя. И редактирование, и удаление ограничены по времени и зависят от возможностей конкретного мессенджера, поэтому при истечении срока вы получите ошибку MESSAGES_EDITING_TIME_EXPIRED или MESSAGES_DELETION_TIME_EXPIRED. Для сервисов с уведомлениями это обычно мелочь, но пригодится, когда ушло сообщение с неверной суммой или датой.
С чего начать подключение к сайту или сервису
Практичный порядок действий для типового проекта в Казахстане выглядит так. Сначала подключите канал и убедитесь, что его тип подходит под задачу: для уведомлений по инициативе компании нужен канал, который разрешает писать первым. Затем получите ключ и отправьте тестовое сообщение со своего телефона на свой же номер. После этого подключите вебхуки, чтобы видеть статусы и ответы. И только потом встраивайте отправку в бизнес-процесс: форму заявки, оформление заказа или смену статуса в CRM.
Хорошо, если у отправки есть очередь. Событие в вашей системе создаёт запись, отдельный обработчик берёт её, вызывает API и сохраняет результат. Так сбой Wazzup или сети не ломает оформление заказа, а повтор по тайм-ауту не рассылает дубли. По нашему опыту внедрений, именно отсутствие очереди и журнала превращает рабочую интеграцию в источник жалоб от клиентов.
Если вам не нужна разработка с нуля, а нужен рабочий результат, B2BPRO.KZ как официальный партнёр Wazzup в Казахстане подключает каналы и настраивает интеграцию с вашей CRM и сайтом. И внедрение, и оплату лицензии можно оформить через агентство: подключить Wazzup к вашей CRM и заказать внедрение под ключ. Если у вашей команды есть свой разработчик, он справится самостоятельно по описанию выше, а мы можем подключиться на этапе проверки схемы.
Что проверить перед запуском отправки в рабочем режиме
Перед тем как включить автоматическую отправку для всех клиентов, пройдите короткий список проверок. Он составлен по описанным выше ограничениям API и по типичным ошибкам, которые мы видим на проектах.
- Канал подключён, а его тип разрешает писать клиенту первым. Для WABA подготовлен и согласован шаблон.
- Ключ API лежит на сервере, а не в коде страницы, и не попал в репозиторий.
- В каждом запросе передаётся crmMessageId, а результат отправки сохраняется в журнал рядом с уведомлением.
- Номера приводятся к одному виду: только цифры, с кодом страны. Для Казахстана это номер, начинающийся с 7.
- Вебхуки подключены, адрес отвечает кодом 200, а входящие сообщения клиентов кто-то видит. Автоматическое уведомление, на которое клиент ответил в пустоту, портит впечатление хуже, чем его отсутствие.
- Тестовая отправка на свой номер прошла для каждого типа сообщения: текст, файл и шаблон.
Последний пункт самый недооценённый. Оформление текста, подпись к файлу и кнопки шаблона ведут себя по-разному в разных мессенджерах, и заметить это можно только на реальном телефоне.
Частые вопросы
Как получить API-ключ Wazzup?
Ключ выдаётся в личном кабинете. Сначала подключите канал в разделе «Каналы», затем откройте «Интеграция с CRM», выберите API и нажмите «Подключить». После этого ключ можно скопировать, а позже найти на вкладке «Дополнительно». Храните его только на сервере, как пароль.
Можно ли первым написать клиенту через API?
Зависит от канала и тарифа. В официальном WhatsApp Business API первое сообщение отправляется только по согласованному шаблону, а свободный текст разрешён после ответа клиента в течение 24 часов. На тарифе «Inbox» писать первым нельзя, API вернёт ошибку. Проверьте это до начала разработки.
Как отправить файл через Wazzup API?
Передайте в запросе поле contentUri со ссылкой на файл вместо поля text. Ссылка должна открываться без редиректов, а файл скачивается сразу после запроса, поэтому подойдёт и временный адрес. Общий предел составляет 10 МБ, у WABA и Telegram есть свои дополнительные ограничения.
Что делать, если сообщение отправилось дважды?
Передавайте в каждом запросе уникальный crmMessageId из вашей системы. Если за 60 секунд придёт повтор с тем же значением, Wazzup вернёт ошибку REPEATED_CRM_MESSAGE_ID и дубль не отправит. Дополнительно храните у себя статус каждого уведомления и повторяйте только те отправки, по которым ответ не получен.
Как узнать, что клиент ответил?
Подключите вебхуки запросом PATCH на адрес /v3/webhooks и включите подписку messagesAndStatuses. Wazzup будет присылать на ваш сервер каждое входящее сообщение и смену статуса исходящих. Сервер должен отвечать кодом 200 в течение 30 секунд, тяжёлую обработку лучше вынести в очередь.