Интеграция сервиса рассылок с OkoCRM
Подключите свой сервис email-рассылок к OkoCRM через виджет OkoStore — и ваши клиенты будут управлять подписками прямо из CRM: автодействия воронки и раздела «Клиенты» добавляют и убирают адреса из ваших списков, а подписки, отписки и статусы писем попадают в ленту клиента. Без кода внутри CRM: запросы от OkoCRM и три эндпоинта API.
Что получает клиент вашего сервиса в OkoCRM
Всё то же, что у штатных интеграций с сервисами рассылок — без доработок с нашей стороны
Добавить в список рассылки
Сделка перешла на этап — email контактов сам уходит в нужные списки вашего сервиса. Клиент выбирает сервис и списки в настройках автодействия, вам делать ничего не нужно.
Удалить из списка рассылки
Обратное автодействие: клиент купил — убрать его из списка «прогрев», сделка проиграна — из списка «акции». Работает и в воронках, и в правилах раздела «Клиенты».
Честный статус подписки
Менеджер видит, добавлен ли адрес, ждёт ли сервис подтверждения подписки от человека (double opt-in) или отказал — с вашей причиной ошибки.
Письма в ленте клиента
Рассылка и тема письма, метки «Доставлено», «Прочитано», «Переход по ссылке» со ссылкой — в истории клиента рядом со звонками и сделками.
Возвраты, жалобы, отписки
«Не доставлено» с причиной, «Жалоба на спам» и отписка по ссылке в письме сразу видны менеджеру — он не напишет человеку, который просил больше не писать.
События пачками
Статусы массовой рассылки вы шлёте пачками до 100 событий в одном запросе. Повторы безопасны: дублей в ленте не будет.
Путь разработчика: что делать и в каком порядке
От регистрации виджета до публикации в OkoStore — десять шагов, каждый с понятным результатом
-
1
Зарегистрируйте виджет
В своём аккаунте OkoCRM откройте «Мои виджеты», создайте виджет и на его странице скопируйте секретный ключ (private_key). Результат: есть ключ для проверки подписи запросов от OkoCRM.
-
2
Поднимите три адреса на своём сервере
Первый принимает вебхуки installed / settings_updated / uninstalled, второй — команду mailing.subscribe «добавить адрес в список», третий — mailing.unsubscribe «удалить из списка». Все по https, все проверяют заголовок Signature по сырому телу запроса. Результат: OkoCRM есть куда стучаться.
-
3
Опишите config.json
Добавьте блок mailing с webhook_url, subscribe_url и unsubscribe_url и поля настроек, которые заполнит клиент (например, ключ API вашего сервиса). script.js может быть пустым модулем. Результат: архив виджета готов к загрузке.
-
4
Опубликуйте личную версию и установите себе
Загрузите версию как personal — без модерации, только для вашего аккаунта. Подключите виджет в магазине и сохраните настройки. Результат: на ваш webhook_url пришёл installed с токеном подключения.
-
5
Сохраните токен и передайте списки рассылок
Запомните пару setting_ulid → token и сразу вызовите PUT lists с перечнем списков клиента. Результат: списки видны во вкладке «Списки рассылок» настроек виджета, в воронке появились автодействия «Добавить в список рассылки» и «Удалить из списка рассылки».
-
6
Примите команды
На mailing.subscribe и mailing.unsubscribe в течение 4 секунд ответьте статусом: subscribed / unsubscribed — сделано, pending — ждёте подтверждения от человека. Повтор с тем же Idempotency-Key не должен выполняться дважды. Результат: в ленте клиента «добавлен в список» или «ждём подтверждения».
-
7
Присылайте подписки и отписки
Человек подтвердил подписку, отписался по ссылке в письме или подписался через форму на сайте — шлите в POST events событие mailing.subscription. Результат: запись «ждём подтверждения» становится «добавлен», отписка видна менеджеру сразу.
-
8
Присылайте статусы писем пачками
sent, delivered, opened, clicked, bounced, complained — событием mailing.letter, пачками до 100 штук. Порядок не важен, повторы безопасны. Результат: одна запись письма в ленте клиента с метками доставки, прочтения, перехода по ссылке.
-
9
Сообщайте об ошибках понятно
Не можете выполнить команду — ответьте кодом ошибки с полем error.message: менеджер увидит этот текст. Если проблема общая (неверный ключ, заблокирован кабинет) — POST status error, когда починили — ok. Результат: честный статус интеграции у клиента.
-
10
Пройдите чеклист и опубликуйте
Сверьтесь с чеклистом из документации (13 пунктов: подпись, команды, double opt-in, идемпотентность, события, перевыпуск токена, удаление) и загрузите версию как public. Результат: после модерации ваш сервис в категории «Рассылка» OkoStore у всех клиентов.
Где что читать в документации
- Как это работает — начало группы «Рассылки: виджеты сервисов рассылок»: схема подключения, блок mailing в config.json, токен подключения, секретный ключ, базовый адрес API, лимиты, коды ошибок и чеклист перед публикацией (шаги 1–4, 10).
- Запросы от OkoCRM — вебхуки installed / settings_updated / uninstalled и команды mailing.subscribe и mailing.unsubscribe, проверка подписи на PHP, Node.js и Python, статусы ответа, идемпотентность и формат ошибок (шаги 2, 6, 9).
- Списки рассылок и статус — PUT lists и POST status (шаги 5, 9).
- События подписок и писем — POST events: события mailing.subscription и mailing.letter, пачки до 100, их поля и правила обработки (шаги 7, 8).
Что понадобится от вашей стороны
- Сервер с публичным https-адресом. На него OkoCRM шлёт пять запросов: установка, изменение настроек, удаление и команды «добавить в список» и «удалить из списка». Каждый подписан HMAC-SHA256 ключом вашего виджета.
- Быстрый ответ на команды. На ответ со статусом есть 4 секунды, поэтому сервис принимает команду и отвечает сразу. Если нужно подтверждение от человека — отвечает «жду подтверждения», а итог сообщает отдельным событием.
- События подписок и писем. Сервис сам сообщает OkoCRM о подписках, отписках и статусах писем — пачками до 100 событий. OkoCRM ваш сервис не опрашивает.
- Перечень списков рассылок клиента. Вы присылаете его целиком после установки и при каждом изменении. Идентификаторы списков и рассылок — строками.
Отладка без модерации: личный виджет ставится на ваш собственный аккаунт OkoCRM и работает точно так же, как публичный. Когда всё работает — публикуйте в OkoStore, и ваш сервис появится в категории «Рассылка» у всех клиентов OkoCRM.
Готовы подключить свой сервис рассылок?
Полное описание запросов, эндпоинтов и событий с примерами на curl, PHP, Node.js и Python — в разделе «Рассылки: виджеты сервисов рассылок» документации API.
Открыть документациюВопросы по интеграции — в поддержку OkoCRM с пометкой «Виджет рассылок»
