API виджетов OkoCRM

Виджет получает два аргумента в default export: widgetApi — для взаимодействия с CRM (события, шаблоны, модалки, HTTP), и settingsApi — для доступа к настройкам и идентификаторам виджета.

export default async function (widgetApi, settingsApi) {
  // ...
}

1. Widget API

События

Подписка на события CRM, отписка и создание собственных событий. В обработчик приходит нативный объект CustomEvent — данные доступны через event.detail.

// Подписка
widgetApi.subscribe('lead.opened', (event) => {
  const entity = event.detail.entity;
});

// Отписка
widgetApi.unsubscribe('lead.opened', handler);

// Создание собственного события
widgetApi.createEvent('my-widget.recalculated', { total: 1000 });

Доступные события:

Объект entity

Доступен через event.detail.entity при событиях *.opened. Если entity.id равен null или undefined — сущность ещё не создана (открыто окно создания).

Шаблоны

Загрузка скомпилированной Handlebars-функции из файла templates/<name>.hbs:

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

Доступные хелперы внутри шаблона:

• все методы Lodash с префиксом _ — например, {{_capitalize name}};
• логические {{and a b}} и {{or a b}}.

Стили

widgetApi.linkStyle('modal'); // подключает styles/modal.css

CSS-классы внутри файла должны быть с префиксом widget-<widget-id>-, чтобы не конфликтовать со стилями платформы и других виджетов.

Модальные окна

// Создать модалку с готовым HTML
const modal = await widgetApi.createModal({ content: htmlString, isLoading: false });

// Переключить состояние «загрузка»
widgetApi.loadingModal({ id: modal.id, isLoading: true });

// Закрыть модалку
widgetApi.closeModal(modal.id);

Уведомления

widgetApi.createNotice({ text: 'Готово' }); // success
widgetApi.createNotice({ text: 'Ошибка запроса', variant: 'error' }); // error

Отрисовка позиций

Виджет не отрисовывает позиции автоматически — это всегда делается из скрипта виджета в ответ на события.

Статические позиции (иконки) — берутся из config.json → icons:

// Иконка в карточке сделки (по событию lead.opened)
widgetApi.renderStaticPosition('lead.main');

// Иконка в карточке компании / контакта
widgetApi.renderStaticPosition('company.main');
widgetApi.renderStaticPosition('contact.main');

// Иконка в сайдбаре
widgetApi.renderStaticPosition('sidebar');

Шаблонные позиции (HTML-блоки):

widgetApi.subscribe('more_settings.opened', async () => {
  const template = await widgetApi.getTemplate('more_settings');
  const content  = template({ /* данные */ });
  widgetApi.linkStyle('more_settings');
  await widgetApi.renderTemplatePosition('more_settings', content);
});

widgetApi.subscribe('page.opened', async () => {
  const template = await widgetApi.getTemplate('page');
  const content  = template();
  widgetApi.linkStyle('page');
  await widgetApi.renderTemplatePosition('page', content);
});

HTTP-запросы

const response = await widgetApi.internalFetch('/api/v1/leads/123');
const data     = await response.json();

Пользователи

const users = await widgetApi.getUsers(); // [{ id, name, ... }, ...]

Работа с DOM и утилиты

Umbrella JS — для DOM, обработки событий и форм внутри отрисованного HTML:

import u from 'umbrellajs';

u('.widget-my-button').on('click', () => {
  // ...
});

u('form.widget-my-form').handle('submit', () => {
  // ...
});

Lodash — утилиты:

import _ from 'lodash';

const isReady = _.isBoolean(entity.ready);
const total   = _.sumBy(entity.contacts, 'budget');

CSS-классы платформы

Чтобы элементы форм выглядели как родные элементы OkoCRM, используйте CSS-классы платформы в шаблонах:

2. Widget Settings API

Доступ к настройкам виджета, идентификаторам и токенам пользователя. Передаётся в script.js вторым аргументом.

export default async function (widgetApi, settingsApi) {
  const settings = settingsApi.getSettings();
  const userId   = settingsApi.getUserId();
}

3. Публичное API OkoCRM

Для чтения и записи бизнес-данных (сделки, контакты, компании, задачи, пользователи, пользовательские поля и т. д.) используется публичное API OkoCRM. Из виджета — через widgetApi.internalFetch, токен авторизации подставляется автоматически.

const response = await widgetApi.internalFetch('/api/v1/leads/123');
const lead     = await response.json();

Полная документация публичного API: https://okocrm.com/api/