Виджеты OkoCRM

Дата изменения: 7.05.2026

Виджет — это пользовательское расширение OkoCRM, которое подключается к карточкам сделок, контактов и компаний и расширяет интерфейс CRM собственными кнопками, окнами и страницами.

Что такое виджет и для чего он нужен

Виджет — это набор файлов (JavaScript, CSS, Handlebars-шаблоны, конфигурация, изображения), который загружается в OkoCRM и исполняется внутри интерфейса CRM через Widget API. Виджет может:

• отображать собственную иконку в карточке сделки, контакта, компании или в сайдбаре;
• открывать модальные окна и отдельные страницы внутри CRM;
• читать данные сущности (название, ответственный, сумма, телефоны, e-mail и т.д.);
• реагировать на события CRM: открытие карточки, изменение, сохранение, создание и т.д.;
• обращаться к публичному API OkoCRM и к внешним сервисам;

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

Личные и публичные виджеты

Виджеты в OkoCRM делятся на два типа по способу распространения. Технически это один и тот же формат файлов, но условия использования и проверки различаются.

Личные виджеты

• доступны только пользователям аккаунта, в котором его загрузили;
• не публикуются в OkoStore и не проходят модерацию OkoCRM (но можно сделать его публичным, указав это в новой версии);
• подходят для внутренних интеграций компании, кастомных расчётов и одноразовых задач;
• могут содержать настройки и параметры, специфичные для одной компании.

Публичные виджеты

• публикуются в OkoStore и доступны любому аккаунту;
• проходят модерацию перед публикацией;
• запрещена обфускация и минификация кода;
• должны иметь корректное и адекватное описание;
• должны корректно работать у пользователей.

Техническое описание виджета

Структура файлов

Виджет — это папка с определенной структурой:

/
  config.json          # Конфигурация виджета (обязательно)
  script.js            # Главный скрипт — ES-модуль с default export (обязательно)
  logo.png             # Иконка виджета (опционально)
  templates/           # Handlebars-шаблоны (.hbs) (опционально)
    modal.hbs
    more_settings.hbs
    page.hbs
  styles/              # CSS-стили для шаблонов (опционально)
    modal.css
    more_settings.css
    page.css

Имена шаблонов и стилей не ограничены приведёнными — можно создавать собственные (например, templates/row.hbs, styles/row.css) и подключать их через widgetApi.getTemplate('row') и widgetApi.linkStyle('row').

Также можно указать отдельную иконку для каждой позиции.

config.json

Декларативное описание виджета: идентификатор, версия, поля настроек и иконки позиций. Пример:

{
    "id": "<widget-id>",
    "author": "Автор",
    "version": "1.0.0",
    "settings": {
        "links": [
            { "title": "Документация", "url": "https://example.com" }
        ],
        "text": "Описание виджета для страницы настроек",
        "fields": [
            {
                "name": "field_name",
                "type": "text",
                "label": "Название поля",
                "required": true
            }
        ]
    },
    "icons": {
        "lead.main":        "logo.png",
        "contact.main":     "logo.png",
        "company.main":     "logo.png",
        "sidebar":          "sidebar.png",
        "pipeline_action":  "action.png"
    },
    "pipeline_action": {
        "title": "Название автодействия",
        "text": "Короткое описание автодействия",
        "webhook_url": "https://api.example.com/v3/create_template",
        "fields": [
            {
                "name": "user_id",
                "data": "users",
                "type": "select",
                "label": "Пример выбора пользователя"
            },
            {
                "name": "template",
                "type": "textarea",
                "label": "Пример шаблона",
                "required": true
            }
        ]
    },
}

Описание полей config.json:

script.js

Главный скрипт-файл виджета — ES-модуль с default export. Функция получает два аргумента: widgetApi (взаимодействие с CRM) и settingsApi (доступ к настройкам и идентификаторам виджета).

export default async function (widgetApi, settingsApi) {
  // Подписки на события, отрисовка позиций, бизнес-логика виджета
}

Шаблоны и стили

Весь HTML описывается в Handlebars-шаблонах templates/*.hbs. Шаблон загружается асинхронно и компилируется в функцию, которой можно передать данные:

const template = await widgetApi.getTemplate('modal');
const html = template({ title: 'Заголовок', items: [...] });

Стили подключаются через widgetApi.linkStyle('modal') — будет загружен файл styles/modal.css. CSS-классы внутри стилей обязательно должны иметь префикс:
widget-<widget-id>-

Позиции

Все позиции (кроме settings) обёрнуты в элемент с data-атрибутами data-widget-position и data-widget-ulid. Это позволяет найти нужную позицию селектором, например:
[data-widget-position="pipeline_action"][data-widget-ulid="WIDGET_ULID"].
Это полезно, если требуется обновить данные в полях позиции, например, в открытом автодействии.

Позиции settings (настройки подключения в интеграциях) и pipeline_action (автодействие) отрисовываются автоматически.
Остальные позиции необходимо отрисовывать самостоятельно (например, получив событие lead.opened).
Различают два вида позиций:

• Статические позиции (иконки) — отрисовываются методом renderStaticPosition(position). Иконка берётся из config.json — icons. Доступные позиции: lead.main, company.main, contact.main, sidebar.
• Шаблонные позиции (HTML-блоки) — отрисовываются методом renderTemplatePosition(position, html). Используются для more_settings и page.

Автодействия (правила)

Виджет может добавлять собственные автодействия (правила) для сделок. Автодействие описывается в config.json в поле pipeline_action.

Описание pipeline_action

Поля (pipeline_action.fields)

Массив объектов с описанием полей формы автодействия.

Иконка автодействия

Иконка для автодействия указывается в config.json в поле icons (только в случае использования pipeline_action):

"icons": {
    ...
    "pipeline_action": "action.png",
    ...
}

Вспомогательные библиотеки

• Handlebars — для шаблонов; доступны хелперы Lodash с префиксом _ (например, {{_capitalize name}}) и логические хелперы {{and a b}}, {{or a b}}.
• Umbrella JS (import u from 'umbrellajs') — для работы с DOM и обработки событий внутри отрисованного HTML.
• Lodash (import _ from 'lodash') — утилиты.

Ограничения

Правила и соглашения

• Виджет работает только во фронтенде CRM — серверной части у виджета нет;
• Настройки виджета (settings и more_settings) и автодействия (pipeline_action) хранятся на стороне OkoCRM;
• Приватные события (lead.main, company.main, contact.main, more_settings.*, page.*, pipeline_action.*) изолированы для каждого виджета — виджеты не получают приватные события друг друга;
• Для сокращения кода, можно использовать вспомогательные библиотеки: Lodash, Umbrella JS.

Общие требования

• Все текстовые файлы (скрипты, стили, шаблоны, SVG, JSON) — в кодировке UTF-8 без BOM;
• Перевод строки должен быть LF;
• config.json обязателен и содержит параметры виджета;
• script.js — это главный ES-модуль;
• Нельзя использовать icons в config.json, если они не используются. Например, страница (page) виджета не нужна, значит иконку sidebar отрисовывать не нужно;
• Все CSS-классы должны иметь префикс widget-<widget-id>- во избежание конфликтов со стилями платформы и других виджетов;
• HTML формируется в Handlebars-шаблонах в папке templates/;
• Имена полей в шаблоне more_settings должны начинаться с setting, например name="setting[client_id]" — иначе значения не сохраняются;
• HTTP-запросы выполняются через fetch, widgetApi.externalFetch или widgetApi.internalFetch — в зависимости от целевого API;
• Нельзя перекрывать элементы интерфейса OkoCRM;
• Нельзя изменять стандартное поведение элементов системы OkoCRM;
• Нельзя использовать идентичные названия классов/id из OkoCRM;
• Нельзя подключать сторонние шрифты;
• Минимизировать HTML в JS — весь HTML выносить в templates/*.hbs;
• Нельзя оставлять неиспользуемые переменные, функции и обработчики событий;
• Нельзя оставлять закомментированный код (комментарии к коду - можно);
• Не оставлять: eval, prompt, confirm, alert, console.*;
• Для элементов форм в шаблонах нужно использовать CSS-классы платформы: input, textarea, select-base, checkbox, button;
• Нельзя изменять окно автодействия — допускается только взаимодействие с данными (например, в селектах);