Интеграция SMS-шлюза с OkoCRM
Подключите свой SMS-сервис к OkoCRM через виджет OkoStore — и ваши клиенты будут отправлять SMS через вас прямо из CRM: из карточки клиента, шаблонов, автодействий воронки и через ИИ-ассистента. Статусы доставки и входящие SMS попадают в ленту клиента. Без кода внутри CRM: вебхуки от OkoCRM и три эндпоинта API.
Что получает клиент вашего шлюза в OkoCRM
Всё то же, что у штатных интеграций с SMS-сервисами — без доработок с нашей стороны
SMS из карточки клиента
Менеджер пишет SMS прямо из карточки контакта, компании или сделки: выбирает имя отправителя, включает транслитерацию или откладывает отправку на нужное время.
Шаблоны сообщений
Готовые тексты с подстановкой данных клиента и сделки. В шаблоне можно закрепить отправителя из вашего шлюза.
Автодействия воронки
SMS уходит сама, когда сделка перешла на этап: подтверждение заказа, напоминание о встрече, просьба об оплате. Настраивает клиент, вам делать ничего не нужно.
Отправка через ИИ-ассистента
ИИ-ассистент, подключённый к OkoCRM, отправляет SMS клиенту по просьбе менеджера — через тот же ваш шлюз.
Статусы доставки в ленте
Отправлено, доставлено, прочитано или не доставлено — с вашей причиной ошибки и кнопкой повтора. Менеджер видит судьбу каждого сообщения в истории клиента.
Входящие SMS
Ответ клиента появляется в его ленте, а ответственный менеджер получает уведомление. Подключается по желанию, если ваш шлюз принимает ответные сообщения.
Путь разработчика: что делать и в каком порядке
От регистрации виджета до публикации в OkoStore — десять шагов, каждый с понятным результатом
-
1
Зарегистрируйте виджет
В своём аккаунте OkoCRM откройте «Мои виджеты», создайте виджет и на его странице скопируйте секретный ключ (private_key). Результат: есть ключ для проверки подписи запросов от OkoCRM.
-
2
Поднимите два адреса на своём сервере
Первый принимает вебхуки installed / settings_updated / uninstalled, второй — запрос sms.send «отправить SMS». Оба по https, оба проверяют заголовок Signature по сырому телу запроса. Результат: OkoCRM есть куда стучаться.
-
3
Опишите config.json
Добавьте блок sms с webhook_url и send_url и поля настроек, которые заполнит клиент (например, ключ API вашего шлюза). script.js может быть пустым модулем. Результат: архив виджета готов к загрузке.
-
4
Опубликуйте личную версию и установите себе
Загрузите версию как personal — без модерации, только для вашего аккаунта. Подключите виджет в магазине и сохраните настройки. Результат: на ваш webhook_url пришёл installed с токеном подключения.
-
5
Сохраните токен и передайте имена отправителей
Запомните пару setting_ulid → token и сразу вызовите PUT senders со списком имён, доступных клиенту. Результат: имена видны в настройках виджета и в выборе отправителя при отправке SMS, в карточке клиента активна кнопка SMS.
-
6
Примите отправку
На запрос sms.send поставьте сообщение в свою очередь и в течение 4 секунд ответьте своим message_id. Повтор с тем же ключом Idempotency-Key не должен отправлять SMS второй раз. Результат: SMS из карточки уходит через ваш шлюз, в ленте — одна галка.
-
7
Присылайте статусы доставки
По мере доставки шлите в POST events событие sms.status: sent, delivered, read или failed с причиной. Порядок не важен, повторы безопасны. Результат: в ленте две галки, отметка о прочтении или красная заметка с вашим текстом.
-
8
Сообщайте об ошибках понятно
Не можете принять сообщение — ответьте кодом ошибки с полем error.message: менеджер увидит этот текст. Если проблема общая (кончился баланс, неверный ключ) — POST status error, когда починили — ok. Результат: честный статус интеграции у клиента.
-
9
По желанию: входящие SMS
Если шлюз принимает ответные сообщения, присылайте их событием sms.incoming. Результат: ответ клиента в ленте его карточки и уведомление ответственному менеджеру.
-
10
Пройдите чеклист и опубликуйте
Сверьтесь с чеклистом из документации (12 пунктов: подпись, отправка, идемпотентность, статусы, перевыпуск токена, удаление) и загрузите версию как public. Результат: после модерации ваш шлюз в категории «SMS» OkoStore у всех клиентов.
Где что читать в документации
- Как это работает — начало группы «SMS: виджеты SMS-шлюзов»: схема подключения, блок sms в config.json, токен подключения, секретный ключ, базовый адрес API, лимиты, коды ошибок и чеклист перед публикацией (шаги 1–3, 10).
- Запросы от OkoCRM — вебхуки installed / settings_updated / uninstalled и запрос sms.send, проверка подписи на PHP, Node.js и Python, идемпотентность и формат ошибок (шаги 2, 4, 6, 8).
- Отправители и статус — PUT senders и POST status (шаги 5, 8).
- Статусы доставки и входящие SMS — POST events: события sms.status и sms.incoming, их поля и правила обработки (шаги 7, 9).
Что понадобится от вашей стороны
- Сервер с публичным https-адресом. На него OkoCRM шлёт четыре запроса: установка, изменение настроек, удаление и команда «отправить SMS». Каждый подписан HMAC-SHA256 ключом вашего виджета.
- Быстрый приём сообщения. На ответ с идентификатором сообщения есть 4 секунды, поэтому шлюз принимает SMS в очередь и отвечает сразу, а результат доставки сообщает отдельным событием.
- Статусы доставки. Шлюз должен уметь сам сообщать OkoCRM, что сообщение доставлено или не доставлено. OkoCRM ваш шлюз не опрашивает.
- Список имён отправителей клиента. Вы присылаете его целиком после установки и при каждом изменении. Имена — до 15 символов латиницей или цифрами.
- По желанию — входящие SMS. Если ваш шлюз принимает ответы клиентов, они попадут в ленту клиента в CRM.
Отладка без модерации: личный виджет ставится на ваш собственный аккаунт OkoCRM и работает точно так же, как публичный. Когда всё работает — публикуйте в OkoStore, и ваш шлюз появится в категории «SMS» у всех клиентов OkoCRM.
Готовы подключить свой SMS-шлюз?
Полное описание вебхуков, эндпоинтов и событий с примерами на curl, PHP, Node.js и Python — в разделе «SMS: виджеты SMS-шлюзов» документации API.
Открыть документациюВопросы по интеграции — в поддержку OkoCRM с пометкой «SMS-виджет»
