API рассылок в мессенджерах WhatsApp, Telegram и MAX

API рассылок в Ватсапе, Телеграме и Максе: подключить аккаунт, создать рассылку и получать статусы прямо из своей CRM или на своём сайте.

API рассылок в мессенджерах WSENDER
API рассылок: сообщения уходят из вашей системы

Сообщения клиентам почти никогда не нужны «когда дойдут руки». Они нужны в момент события: оплатил заказ, записался на визит, не пришёл, месяц не появлялся. Событие уже случилось в вашей системе, и заходить после этого в кабинет, чтобы собрать рассылку руками, странно.

Для этого и есть публичный API. Один и тот же набор методов работает для WhatsApp*, Telegram и MAX, поэтому смена канала не требует переделки интеграции.

Что умеет API рассылок в Ватсапе, Телеграме и Максе

Всё, что вы делаете в кабинете руками, доступно по HTTP:

  • Подключение аккаунтов. Запрос возвращает QR-код, вы показываете его пользователю, сервис сообщает результат. Если аккаунт защищён двухфакторным паролем, пароль тоже передаётся через API.
  • Аудитория. Создать сегмент и загрузить номера телефонов, до 1000 номеров за один запрос. Уже известные проекту номера не дублируются.
  • Рассылки. Создать, добавить текст или медиа (картинку, видео, аудио, документ), выбрать получателей: сегмент контактов, телефонная книга аккаунта или существующие чаты. Дальше проверка текста, запуск, пауза, отмена.
  • Результат по каждому получателю. Отправлено, доставлено, прочитано, получен ответ, номера нет в мессенджере.
  • Ответы получателей. Не только факт «ответил», но и текст ответа: что именно человек написал в ответ на рассылку.
  • Вебхуки. Аккаунт подключился или отключился, мессенджер ограничил аккаунт, рассылка запустилась, встала на паузу, завершилась, получатель ответил. Опрашивать API в цикле не нужно.

Важное про отправителя: сообщения уходят с ваших аккаунтов, подключённых по QR-коду. Своих номеров сервис не выдаёт, и это к лучшему: номер и его репутация остаются вашими, а ответы клиентов приходят вам в обычное приложение мессенджера.

Как получить API-ключ

  1. Войдите в кабинет рассылок и откройте раздел API.
  2. Нажмите «Создать ключ», задайте название (по нему потом понятно, какой интеграции ключ выдан) и при желании срок действия.
  3. Скопируйте токен. Он показывается один раз: сервис хранит только его хэш и восстановить значение не может. Потеряли — создайте новый ключ, старый удалите.

Раздел API открыт только владельцу проекта: он один создаёт ключи и видит их список. Так что если интеграцию делает разработчик или подрядчик, ключ выпускает владелец и передаёт токен ему, а не выдаёт доступ в кабинет.

Ключ выдаётся на проект, а не на сотрудника, и даёт полный доступ к API этого проекта. Храните его как пароль. Можно создать несколько ключей, например по одному на каждую интеграцию, чтобы отзывать их независимо.

Токен передаётся в заголовке каждого запроса. Проверить, что всё работает, можно списком подключённых аккаунтов:

curl https://api.wsender.ru/v1/channel \
  -H "Authorization: key ВАШ_ТОКЕН"

Все методы описаны в документации API, причём выполнить запрос со своим ключом можно прямо из браузера, не написав ни строки кода. Рядом лежит машинная спецификация — OpenAPI-файл: по нему инструменты вроде Swagger Codegen или NSwag сами соберут клиент на вашем языке, вручную описывать запросы и модели не придётся.

Рассылка за семь запросов

Минимальный сценарий выглядит так: собрали сегмент → создали рассылку → добавили текст → указали получателей → отправили на проверку → запустили.

  1. PUT /v1/segment создаёт сегмент.
  2. PUT /v1/segment/{segmentId}/contact загружает номера.
  3. PUT /v1/mailing создаёт рассылку.
  4. PUT /v1/mailing/{mailingId}/message/text добавляет текст сообщения.
  5. PUT /v1/mailing/{mailingId}/recipient/source указывает, что получатели берутся из сегмента.
  6. POST /v1/mailing/{mailingId}/moderate отправляет текст на проверку.
  7. POST /v1/mailing/{mailingId}/start запускает отправку с выбранного аккаунта.

Запросы одинаковые для всех трёх мессенджеров: рассылка в Ватсапе создаётся тем же способом, что в Телеграме и Максе, отличается только подключённый аккаунт. Дальше можно ничего не опрашивать, статусы прилетят вебхуками.

Откуда брать получателей

Пятый шаг заслуживает отдельного разбора: от источника зависит и результат, и риск для аккаунта. Их три.

  • Сегмент контактов. Номера загружаете вы. Рассылка, привязанная к сегменту, продолжит отправлять сообщения контактам, которых вы добавите позже. Для интеграции это главный источник, о нём отдельный раздел ниже.
  • Контакты аккаунта. Телефонная книга подключённого номера. По умолчанию сообщения уходят только тем, с кем переписка уже была: такая аудитория и отвечает лучше, и почти не даёт жалоб. Ограничение можно снять, но лучше не надо.
  • Чаты аккаунта. Существующие диалоги. Тоже можно оставить только тех, с кем общались, и отдельно исключить диалоги с ботами, чтобы не писать в служебные чаты. Подробный разбор двух последних источников есть в статье про рассылку по чатам и контактам.

Один нюанс, который важно учесть при проектировании: при первом запуске источник фиксируется вместе с мессенджером и больше не меняется. Нужен другой источник — это новая рассылка.

Триггерные рассылки: один вызов на одно событие

Самое полезное свойство сегмента: рассылка по нему не завершается, когда разослала сообщения всем, кто в сегменте был. Она остаётся в работе и ждёт новых контактов, проверяя сегмент примерно раз в минуту.

Запущенная рассылка, по сути, работает как очередь отправки. А значит, схема получается такая:

  1. Один раз создаёте сегмент и рассылку на него, добавляете текст и запускаете. Через API или руками в кабинете, разницы дальше нет.
  2. Дальше на каждое событие в вашей системе делаете один запрос: добавить номер в сегмент.

Всё. Сообщение уйдёт само, в безопасном темпе, с проверенным текстом и учётом лимитов. Оплатил заказ, записался на визит, не пришёл, месяц не появлялся: у вас получаются собственные триггерные рассылки, а поддерживать нужно ровно один вызов на каждый повод.

Текст у такой рассылки один для всех получателей, с подстановкой имени и вариантов формулировок. Поэтому на каждый повод делают свою пару «сегмент плюс рассылка»: приветствие, напоминание о записи, возврат клиента. Создали один раз, дальше они просто ждут номера.

Ответы клиентов возвращаются в вашу систему

Рассылка не заканчивается отправкой: люди отвечают, и ответ обычно и есть результат, ради которого всё затевалось. Через API видно не только то, что человек ответил, но и что именно он написал.

Порядок такой: приходит вебхук «получатель ответил», по нему вы запрашиваете ответы этого получателя и получаете время, текст, тип сообщения и названия вложенных файлов.

curl https://api.wsender.ru/v1/mailing/{ИД_РАССЫЛКИ}/recipient/{ИД_ПОЛУЧАТЕЛЯ}/reply \
  -H "Authorization: key ВАШ_ТОКЕН"

Возвращаются именно ответы на эту рассылку, а не вся переписка с человеком: сервис берёт сообщения после отправки конкретному получателю. По этому же правилу выставляется статус «ответил», так что статус и содержимое не разойдутся.

Дальше ответ попадает в вашу CRM: менеджеру в задачу, в чат отдела продаж, в дашборд. Пара оговорок, чтобы не заложить лишнего: переписка подтягивается с аккаунта периодически, поэтому между ответом человека и его появлением в API проходит время, а список бывает пустым — когда вместо текста человек поставил реакцию на сообщение.

Вебхуки: сервис сам скажет, что произошло

Опрашивать API в цикле «а что там» не нужно. Укажите свой адрес, и события будут приходить сами:

curl -X PUT https://api.wsender.ru/v1/webhook \
  -H "Authorization: key ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://ваш-домен/wsender","secret":"ваш-секрет"}'

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

Приходят события четырёх групп:

  • Аккаунт: подключён, отключён, а во время подключения по QR — что код готов, что нужен двухфакторный пароль, что всё получилось.
  • Ограничения мессенджера: аккаунт ограничен и ограничение снято. Пожалуй, самое ценное: при блокировке аккаунт остаётся подключённым, и без события рассылка встаёт молча.
  • Рассылка: прошла проверку, не прошла с замечаниями, запущена, встала на паузу с причиной, завершена, отменена.
  • Получатели: сообщения отправлены, человек ответил, отправка не удалась, номера нет в мессенджере.

Два момента, о которые спотыкаются на интеграции. Первый: события по получателям приходят только если перечислить их явно. Пустой список событий значит «всё, кроме них» — их столько же, сколько контактов в базе, и по умолчанию сервис ими не заваливает. Второй: если ваш сервер не ответил, сервис повторит попытку, увеличивая паузу с 30 секунд до получаса, но через сутки перестанет. Поэтому после долгого простоя приёмника состояние лучше дочитать обычными запросами.

Скорость: почему API не отправит всё сразу

Здесь ожидания разработчиков расходятся с реальностью мессенджеров чаще всего. API принимает запрос мгновенно, но темп отправки задаёт не он, а автостратегия: она начинает спокойно и наращивает скорость по мере того, как у аккаунта накапливается история отправок. Если площадка притормозила аккаунт, сервис ставит рассылку на паузу и продолжает медленнее.

Это не ограничение сервиса, а защита вашего номера. Попытка «прогнать базу за час» через любой API заканчивается ограничением аккаунта, и мы такую возможность сознательно не даём.

Ещё четыре момента, которые лучше учесть до интеграции:

  • Текст проверяется до запуска. ИИ смотрит сообщение и может вернуть замечания: список читается через API, по каждому видно, что не так и в каком сообщении. Замечания-рекомендации принимаются одним запросом, запрещённые темы исправляются только правкой текста. Как собрать текст, на который отвечают, разобрано в статье про формулу сообщения из 4 частей.
  • Лимиты тарифа работают так же, как в кабинете. Сообщения расходуют суточную квоту: когда она исчерпана, рассылка ждёт следующего дня или доплаты.
  • Лимит запросов считается на проект. Он общий для всех ключей проекта: выпуск новых ключей его не увеличивает.
  • Холодные номера идут медленнее. Если номера нет в вашей переписке, мессенджер сначала нужно спросить, зарегистрирован ли он. В Телеграме такой поиск ограничен строже всего, поэтому рассылка по незнакомым номерам там заметно спокойнее по темпу, чем в Ватсапе.

Где API пригодится

  • CRM: уведомления о статусе сделки и заказа, а ответы клиентов возвращаются обратно в карточку.
  • Интернет-магазин: подтверждение заказа, оплата, доставка.
  • Сайт или лендинг: мгновенный ответ на заявку в тот мессенджер, которым человек пользуется.
  • Онлайн-запись: напоминание о визите за день.
  • Реактивация: сегмент «не покупал 3 месяца» пополняется из вашей базы, а рассылка сама разбирает очередь.

Чего в API пока нет

Честно про границы, чтобы вы не проектировали лишнего.

Отдельного метода «отправить сообщение вот этому человеку с вот этим текстом» нет. Точечная отправка закрывается сегментом-очередью: рассылка живёт постоянно, а вы добавляете в неё номер. Разный текст под каждое событие означает разные рассылки, а не разные вызовы одного метода.

Ответить клиенту через API тоже нельзя: ответы на рассылку вы читаете (об этом раздел выше), а продолжать диалог нужно в самом мессенджере, на подключённом аккаунте. Всю переписку с человеком API не отдаёт — только то, что он написал в ответ на рассылку.

Что дальше

Отдельной платы за API нет, действуют обычные тарифы, и он доступен даже на бесплатном: на бесплатном тарифе 15 сообщений в день, для сборки и проверки интеграции этого хватает.

Начните с малого: создайте ключ, выполните запрос списка аккаунтов, подключите один аккаунт и отправьте рассылку на сегмент из одного своего номера. Весь контур станет понятен за полчаса. Дальше останется собрать рабочую пару «сегмент плюс рассылка» и добавлять в неё номера из того места, где у вас появляется событие.

Полное описание методов — в документации API, спецификация для генерации клиента — в OpenAPI-файле.

* WhatsApp принадлежит компании Meta, деятельность которой признана в России экстремистской и запрещена.