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

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

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

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

Набор методов при этом один на всё: аккаунты WhatsApp*, Телеграма и Макса и боты Телеграма, Макса, ВКонтакте и Яндекса. Чтобы добавить ещё один мессенджер, новую интеграцию писать не нужно: меняется значение в том же запросе.

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

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

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

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

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

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

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

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

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

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

curl https://api.wsender.io/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 запускает отправку с выбранного аккаунта.

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

Повтор запроса не создаст вторую рассылку

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

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

Idempotency-Key: 3f0c1b7e-8a2e-4a51-9d2b-6a1e0f2c4d88

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

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

Практический вывод для интеграции: повторять стоит то, у чего результата нет: обрыв связи, ошибки сервера и ответ 429 (превышение частоты запросов). Такие ответы не сохраняются, и повтор действительно выполнит операцию. А отказ по существу, например «в тексте не хватает обязательного поля», это уже результат, и повтор вернёт его же.

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

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

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

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

Боты Телеграма, Макса, ВКонтакте и Яндекса: тот же API

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

Различий ровно два, и оба видны сразу.

Подключение по токену. Токен вы получаете на стороне платформы: у Телеграма его выдаёт @BotFather, у Макса кабинет для бизнеса, у ВКонтакте это ключ доступа сообщества, у Яндекса админка Яндекс 360. Дальше тот же запрос, что и для аккаунта, только вместо способа входа в нём токен. Если токен перевыпустили, бот не теряется: отдельный запрос обновления токена меняет его у уже подключённого бота, подписчики, рассылки и история остаются на месте (в кабинете то же самое делает ссылка «Обновить токен» на странице бота).

Получатели: подписчики бота. Бот пишет тем, кто сам ему написал: загруженный сегмент номеров ему недоступен. Так устроены сами платформы: Bot API не позволяет писать первым, и обойти это не может никто.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

То же и с ботами. На бесплатном тарифе бот работает только на исходящие: рассылки уходят, а входящие от подписчиков не принимаются и нигде не сохраняются, ни в API, ни в кабинете. Сами подписчики при этом продолжают появляться, и рассылать по ним можно.

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

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

curl -X PUT https://api.wsender.io/v1/webhook \
  -H "Authorization: key ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/wsender","secret":"your-secret"}'

Вебхук один на проект, адрес обязательно на HTTPS. Замените адрес и секрет из примера своими: в секрете допустимы латинские буквы, цифры, дефис и подчёркивание. Сервис присылает его обратно в заголовке X-WSender-Secret-Token каждого запроса, так вы отличаете свои события от чужих обращений на тот же адрес.

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

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

События по получателям и отдельным сообщениям приходят только при явной подписке. Перечислите нужные типы в events: пустой список их не включает, чтобы большая рассылка не создавала ненужный поток событий.

Сначала надёжно сохраните входящее событие, затем ответьте кодом 2xx и обработайте его. Если ваш сервер не ответил за 10 секунд или вернул ошибку, сервис повторит попытку с паузой от 30 секунд до получаса. Каждое событие хранится в очереди не больше суток с момента создания.

Одно событие может прийти повторно: проверяйте его id, чтобы дважды не выполнить действие в CRM.

Если с первого отказа прошли сутки и ни одной успешной доставки за это время не было, вебхук автоматически приостанавливается. Владельцу проекта приходит уведомление через подключённого бота уведомлений WSENDER в Telegram или MAX. Состояние можно проверить запросом GET /v1/webhook: в объекте health находятся статус Active или Suspended, последняя ошибка и даты.

После исправления своего приёмника вызовите POST /v1/webhook/resume ключом с правом управления вебхуком:

curl -X POST https://api.wsender.io/v1/webhook/resume \
  -H "Authorization: key ВАШ_ТОКЕН"

Сервис отправит на ваш адрес проверочное событие webhook.test с обычным секретом. Только ответ 2xx возобновит доставку. Обычный POST /v1/webhook/test помогает проверить адрес, но сам приостановку не снимает.

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

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

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

Так сервис бережёт ваш номер: если разослать всю базу за час, мессенджер, скорее всего, ограничит аккаунт. Поэтому такой возможности в сервисе нет.

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

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

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

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

Что дальше

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

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

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

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