Виджеты amoCRM: как разработать и опубликовать в маркетплейсе

Виджеты amoCRM — это один из самых мощных инструментов платформы для разработчиков. Они позволяют встраивать собственный JavaScript-код прямо в интерфейс CRM: в карточки сделок и контактов, списки, Digital Pipeline, Salesbot и даже мобильные приложения. Виджет может отображать данные из внешних систем, отправлять информацию на сторонний сервер, интегрировать телефонию, синхронизировать с 1С или автоматизировать любые действия менеджера — всё это без переключения между вкладками браузера.

В этой статье вы найдёте полное практическое руководство: от скачивания шаблона до получения статуса public в маркетплейсе амоМаркет. Мы разберём структуру проекта, объект callbacks, ключевые методы SDK, типичные ошибки при загрузке и требования модерации. Все технические детали основаны на официальной документации amocrm.ru/developers.

Что такое JS-виджет amoCRM и чем он отличается от API-интеграции

JS-виджет amoCRM — это клиентское расширение интерфейса CRM, написанное на JavaScript. Технически виджет представляет собой AMD-модуль (формат define/require), который система загружает в браузер пользователя в тех областях интерфейса, которые вы укажете в настройках. После загрузки виджет расширяет системный объект Widget своим функционалом и работает непосредственно с DOM-деревом страницы.

В отличие от серверной REST API-интеграции, виджет не требует бэкенда для отображения данных. Он запускается прямо в браузере и может напрямую читать содержимое карточки, добавлять элементы на страницу, перехватывать клики пользователя и при необходимости отправлять данные на ваш сервер через встроенный метод crm_post. Если же нужно отправлять данные на внешний сервер, используется метод crm_post, который проксирует запросы через серверы amoCRM, обходя ограничения CORS браузера.»

Где находятся виджеты в интерфейсе amoCRM

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

амоМаркет — главная страница виджетов

Раздел амоМаркет доступен только администраторам аккаунта. Здесь пользователи находят, устанавливают и управляют виджетами. На главной странице маркетплейса представлены категории:

• Чаты и мессенджеры / WhatsApp-интеграции
• Телефония
• Email, счета и эквайринг
• Аналитика и отчёты
• Работа с документами
• Розница и автоматизация
• Боты и Salesbot
• Работа с задачами
• Разграничение доступа
• Интерфейс и usability
• Отраслевые интеграции
• Интеграции с веб-сайтом
• Полезные сервисы / контроль дублей

На главной странице амоМаркета есть поиск по названию и ключевым словам, вкладка «Установленные» (показывает все активные виджеты аккаунта), а также кнопка «Создать интеграцию» для разработчиков.

Точки отображения виджета внутри CRM

После установки виджет может появляться в следующих местах интерфейса — в зависимости от того, какие области вы указали в manifest.json:

Область	Код в locations	Описание
Карточка сделки	lcard-1	Правая колонка в карточке сделки
Карточка контакта	ccard-1	Правая колонка в карточке контакта
Список сделок	llist-1	Панель при мультивыборе
Список контактов	clist-1	Панель при мультивыборе
Список задач	tlist-1	Панель при мультивыборе
Карточка покупателя	cucard-1	Правая колонка
Digital Pipeline	digital_pipeline	В настройках воронки как триггер
Salesbot Designer	salesbot_designer	В конструкторе сценариев
Расширенные настройки	advanced_settings	Отдельная страница настроек
Мобильное приложение	mobile_card	Встроенный webview в мобильном
Веб-формы	amoforms	В конструкторе веб-форм

Суффикс -1 после кода области означает, что виджет будет использовать правую колонку для отображения. Суффикс -0 означает инициализацию без использования правой колонки (например, для телефонных панелей внизу экрана).

Типы интеграций amoCRM: что выбрать под задачу

amoCRM предоставляет несколько способов расширить функциональность системы. Перед началом разработки важно выбрать правильный подход.

Тип	Описание	Когда выбирать
Публичный виджет (амо Маркет)	JS + manifest.json, архив загружается в маркетплейс, доступен всем аккаунтам	Нужен продукт для широкой аудитории, монетизация
Приватная интеграция	Архив widget.zip для конкретного аккаунта, статус private	Кастомная разработка под одного клиента
Внешняя интеграция (API)	Серверная логика через REST API и веб-хуки, без JS-архива	Фоновые процессы, сложная бизнес-логика без UI
No-code: Albato / Make / n8n	Готовые коннекторы без разработки	Нет ресурса на разработку, стандартные интеграции

В этой статье мы фокусируемся на JS-виджетах — первых двух типах из таблицы. Для серверных API-интеграций обратитесь к разделу CRM Platform в официальной документации.

Инструменты и требования перед началом разработки

Для разработки виджета amoCRM вам потребуется минимальный набор инструментов. Не нужно устанавливать сложные фреймворки или сборщики, достаточно редактора кода и браузера.

Необходимо

• Аккаунт amoCRM — подойдёт тестовый аккаунт с правами администратора
• Редактор кода — рекомендуется Visual Studio Code
• Архиватор для создания ZIP-файлов
• Базовые знания JavaScript (AMD-модули, jQuery)
• Браузер с DevTools (Chrome или Firefox)

Как получить шаблон виджета

Официальный шаблон виджета с примером структуры доступен на странице документации amoCRM. Чтобы его скачать:

1. Откройте amocrm.ru/developers
2. Перейдите в раздел «Интеграции» → «Начало работы»
3. Нажмите кнопку «Скачать пример виджета»
4. Распакуйте архив — внутри будет папка widget_example
5. Скопируйте её в папку вашего проекта и переименуйте

Структура проекта виджета amoCRM

Виджет amoCRM — это папка с файлами определённой структуры, упакованная в ZIP-архив. Разберём каждый файл подробно.

Файл / папка	Обязательность	Назначение
manifest.json	Обязательный	Конфигурация виджета: название, области, поля, тур, поддержка
script.js	Обязательный	JS-логика: объект callbacks, методы, обработчики событий
images/	Обязательный	Логотипы виджета разных размеров (5–6 файлов PNG/JPEG)
i18n/	При мультиязычности	Файлы локализации: ru.json, en.json и др.
style.css	Опционально	CSS-стили для элементов виджета в интерфейсе CRM
templates/	Опционально	Шаблоны twig.js для сложной разметки
lib/	Опционально	Вспомогательные JS-модули (хелперы, утилиты)

manifest.json — мозг виджета

manifest.json — главный конфигурационный файл. Без него виджет не будет загружен. Именно здесь вы описываете всё: как называется виджет, в каких областях интерфейса он работает, какие поля заполняет пользователь при установке, и многое другое.

Обязательные поля manifest.json

Параметр	Тип	Описание
widget.name	string	Название виджета. Указывается как ключ локализации: «widget.name»
widget.description	string	Полное описание. Поддерживает HTML и переменные: #SUBDOMAIN#, #LOGIN#, #ACCOUNT_ID#
widget.short_description	string	Короткое описание для списка виджетов
widget.version	string	Версия виджета: «1.0.0». Увеличивайте при каждой загрузке
widget.interface_version	int	Версия интерфейса. Всегда указывайте 2
widget.locale	array	Массив языков: [«ru», «en»]. Нужны соответствующие файлы в i18n/
widget.support.link	string	Ссылка на страницу поддержки виджета (обязательно)
locations	array	Области подключения виджета в интерфейсе CRM
tour.is_tour	bool	Включить тур. Значение всегда true (обязательно с 2019 года)
tour.tour_images	object	Пути к изображениям тура по каждой локали
tour.tour_description	string	Ключ ланга с кратким описанием тура

Дополнительные важные параметры

Параметр	Описание
widget.init_once: true	Инициализировать виджет только один раз за сессию. Используйте для телефонии, WebSocket-соединений — там, где нельзя прерывать соединение при переходе между страницами
widget.init_once: false	Инициализировать виджет заново при каждом переходе в область. Используйте по умолчанию для большинства виджетов
widget.installation: false	Виджет не запрашивает настройки при установке. Подходит, если все настройки управляются через внешний сервис
widget.is_showcase: true	Меняет кнопку «Установить» на «Посмотреть». Используйте для информационных виджетов (installation при этом должно быть false)
dp.webhook_url	URL для отправки веб-хука при срабатывании триггера в Digital Pipeline
sms.endpoint	URL для отправки системных SMS через виджет
mobile.frame_url	URL страницы, открываемой в webview мобильного приложения

Требования к логотипам в папке images/

Файл	Размер	Назначение
logo_main.png	400 × 272 px	Основной логотип на странице маркетплейса
logo_small.png	108 × 108 px	Иконка в компактных списках
logo.png	130 × 100 px	Поддержка старых версий интерфейса
logo_medium.png	240 × 84 px	Логотип в развёрнутой правой колонке
logo_min.png	84 × 84 px	Иконка в свёрнутой правой колонке
logo_dp.png	174 × 109 px	Логотип в блоке Digital Pipeline

Размер каждого файла не должен превышать 300 КБ. Поддерживаемые форматы: PNG, JPEG, GIF.

Пример минимального manifest.json

Ниже приведён рабочий шаблон с обязательными полями и комментариями. Замените значения на свои перед загрузкой.

{
  "widget": {
    "name": "widget.name",           // ключ из i18n/ru.json
    "description": "widget.description",
    "short_description": "widget.short_description",
    "version": "1.0.0",              // увеличивайте при каждой загрузке
    "interface_version": 2,          // всегда 2
    "init_once": false,
    "locale": ["ru", "en"],
    "installation": true,
    "support": {
      "link": "https://your-site.com/support",
      "email": "support@your-site.com"
    }
  },
  "locations": ["ccard-1", "clist-1", "lcard-1", "llist-1"],
  "tour": {
    "is_tour": true,
    "tour_images": {
      "ru": ["/images/tour_1_ru.png", "/images/tour_2_ru.png"],
      "en": ["/images/tour_1_en.png", "/images/tour_2_en.png"]
    },
    "tour_description": "widget.tour_description"
  },
  "settings": {
    "login":    { "name": "settings.login",    "type": "text", "required": true },
    "password": { "name": "settings.password", "type": "pass", "required": true }
  }
}

Файлы локализации i18n/

Папка i18n/ содержит JSON-файлы с переводами для каждого языка. Минимально необходимы ru.json и en.json. Если виджет публикуется в маркетплейсе для международного рынка добавьте es.json (испанский) и pt.json (португальский).

Критически важно: все файлы локализации должны быть идентичны по структуре. Если в ru.json есть ключ userLang.buttonText, он обязан быть и в en.json, иначе виджет упадёт с ошибкой у пользователей с английским интерфейсом.

// i18n/ru.json
{
  "widget": {
    "name": "Мой виджет",
    "short_description": "Краткое описание",
    "description": "Полное описание для домена #SUBDOMAIN#",
    "tour_description": "Описание тура виджета"
  },
  "settings": {
    "login": "Логин",
    "password": "Пароль"
  },
  "userLang": {
    "buttonText": "Отправить данные",
    "successMessage": "Данные отправлены",
    "errorMessage": "Ошибка при отправке"
  }
}

Доступные переменные-подстановки в поле description: #HOST# (текущий хост), #SUBDOMAIN# (субдомен аккаунта), #LOGIN# (логин текущего пользователя), #API_HASH# (хеш-ключ), #ACCOUNT_ID# (ID аккаунта), #USER_ID# (ID пользователя), #TOP_LEVEL_DOMAIN# (com или ru).

script.js — логика виджета

script.js — это главный JavaScript-файл виджета. Именно он подключается на стороне пользователя во всех указанных областях. Весь виджет оформляется как AMD-модуль (RequireJS) и должен возвращать объект-конструктор CustomWidget.

Архитектура объекта виджета

Когда система загружает виджет, она расширяет существующий системный объект Widget вашим кодом из script.js. Таким образом CustomWidget наследует встроенные свойства и методы платформы, которые мы разберём ниже.

// Базовый скелет script.js
define(['jquery'], function ($) {
  var CustomWidget = function () {
    var self = this,
      system = self.system(), // системные данные (area, amouser, ...)
      langs  = self.langs;    // объект локализации из i18n/

    this.callbacks = {
      render:      function () { return true; },
      init:        function () { return true; },
      bind_actions: function () { return true; },
      settings:    function () { },
      onSave:      function () { return true; },
      destroy:     function () { },
      dpSettings:  function () { },
      contacts:    { selected: function () { } },
      leads:       { selected: function () { } },
      todo:        { selected: function () { } },
    };
    return this;
  };
  return CustomWidget;
});

Таблица функций обратного вызова (callbacks)

Callback	Когда вызывается	Что делать	Должен вернуть
render	Первый при каждой инициализации виджета в области	Отображение виджета: render_template() для правой колонки, добавление шаблонов в DOM	true (обязательно)
init	Сразу после render	Сбор данных, авторизация в сторонних API, инициализация переменных	true (обязательно)
bind_actions	Одновременно с init	Навешивание обработчиков событий: клики, изменения полей	true (обязательно)
settings	Клик на иконку виджета в разделе Интеграции	Отображение модального окна настроек, загрузка шаблона форм	—
onSave	Клик «Установить/Сохранить» в настройках	Валидация и сохранение данных, авторизация в стороннем сервисе	true
onInstall	Один раз при первой установке виджета	Инициализационная логика: создание дефолтных данных, проверка окружения	—
destroy	Отключение виджета или переход из области	Удаление элементов из DOM, закрытие соединений	—
dpSettings	В области digital_pipeline при клике на виджет	Аналог settings, но для настройки триггера в Digital Pipeline	—
advancedSettings	На странице расширенных настроек	Заполнение страницы advanced_settings (область должна быть в locations)	—
leads:selected	Выбор сделок галочками + клик на виджет в меню	Пакетные операции с выбранными сделками	—
contacts:selected	Выбор контактов галочками + клик на виджет в меню	Пакетные операции с выбранными контактами	—
onSalesbotDesignerSave	Сохранение действия виджета в конструкторе Salesbot	Обработка параметров Salesbot-действия	—

Ключевые методы объекта widget

Объект виджета предоставляет набор встроенных методов для работы с интерфейсом, данными и системой amoCRM.

Метод	Описание	Пример
self.system()	Возвращает системные данные: area (текущая область), amouser_id, amouser, amohash	var area = self.system().area;
self.get_settings()	Возвращает объект с данными, введёнными пользователем при подключении виджета (логин, пароль, etc.)	var settings = self.get_settings();
self.i18n('objName')	Возвращает объект локализации из i18n-файла для текущего языка пользователя	var lang = self.i18n('userLang');
self.render(data, params)	Рендеринг шаблона через twig.js. Принимает шаблон и данные, возвращает HTML	self.render({data: template}, {items: arr})
self.render_template({caption, body, render}, params)	Оборачивает разметку в стандартную оболочку виджета и помещает в правую колонку	self.render_template({caption: {class_name: 'cls'}, body: html})
self.crm_post(url, data, cb, type)	POST-запрос на внешний сервер через прокси amoCRM. Нужен для обхода CORS и работы с HTTP-сервисами	self.crm_post('https://...', {key: 'val'}, fn, 'json')
self.list_selected()	Возвращает массив выбранных галочками контактов/сделок с полями id, emails, phones, type	var sel = self.list_selected().selected;
self.add_action(type, fn)	Перехватывает клик на телефон или email в списке контактов. type: ‘phone’ или ’email’	self.add_action('phone', function(){...})
self.set_settings(obj)	Добавляет свойства к объекту настроек виджета	self.set_settings({myProp: 'val'})
self.get_version()	Возвращает строку с версией виджета из manifest.json	var v = self.get_version();
self.get_install_status()	Статус установки: installed, install, not_configured	var s = self.get_install_status();
self.widgetsOverlay(bool)	Включает/выключает оверлей при вызове из списка контактов или сделок	self.widgetsOverlay(true);

Практические паттерны: реальные задачи

Паттерн 1: Отправить данные карточки контакта на внешний сервер

Одна из самых частых задач — по клику пользователя собрать данные из карточки контакта (имя, телефоны, emails) и отправить их во внутреннюю систему компании.

// Сбор данных из карточки контакта и отправка на сервер
this.get_ccard_info = function () {
  if (self.system().area !== 'ccard') return false;
  var phones = $('.card-cf-table-main-entity .phone_wrapper input[type=text]:visible'),
      emails = $('.card-cf-table-main-entity .email_wrapper input[type=text]:visible'),
      name   = $('.card-top-name input').val(),
      data   = { name: name, phones: [], emails: [] };
  phones.each(function() { if ($(this).val()) data.phones.push($(this).val()); });
  emails.each(function() { if ($(this).val()) data.emails.push($(this).val()); });
  return data;
};

this.sendInfo = function (contactData) {
  self.crm_post(
    'https://your-server.com/api/contact',
    { name: contactData.name, phones: contactData.phones, emails: contactData.emails },
    function (response) { console.log('Отправлено:', response); },
    'json'
  );
};

Паттерн 2: Пакетные операции с мультивыбором контактов

Если пользователь отмечает несколько контактов в списке и нажимает на название вашего виджета в меню, срабатывает callback contacts:selected. Здесь удобно реализовать массовую рассылку, экспорт или синхронизацию.

contacts: {
  selected: function () {
    var selected = self.list_selected().selected;
    // selected — массив объектов: { id, emails, phones, type }
    var dataToSend = selected.map(function(contact) {
      return { id: contact.id, phone: contact.phones[0], email: contact.emails[0] }
    });

    self.crm_post('https://your-server.com/api/bulk', { contacts: dataToSend },
      function() { alert('Готово: ' + dataToSend.length + ' контактов отправлено'); },
      'json');
  }
},

Паттерн 3: Подключение CSS без проблем с кешем

При обновлении стилей виджета браузер может показывать старую версию CSS из кеша. Решение — передавать версию виджета как параметр к URL файла стилей.

init: function () {
  var settings = self.get_settings();
  var cssHref  = settings.path + 'style.css?v=' + settings.version;
  if ($('link[href="' + cssHref + '"]').length < 1) {
    $('head').append('');
  }
  return true;
},

Паттерн 4: Настройки виджета в дочерних модулях

Если виджет состоит из нескольких файлов (lib/error.js, lib/api.js и т.д.), каждому из них может понадобиться доступ к настройкам виджета (логин, API-ключ). Правильное решение — хелпер-хранилище.

// lib/settings_helper.js
define([], function () {
  var settings = {};
  return {
    set: function (s) { settings = s; },
    get: function ()  { return settings; }
  };
});

// В начале script.js (ещё в конструкторе, до callbacks)
define(['jquery', './lib/settings_helper.js'], function ($, helper) {
  var CustomWidget = function () {
    var self = this;
    helper.set(self.get_settings()); // запоминаем ДО callbacks
    // ...
  };
});

Паттерн 5: Согласие на передачу данных (оферта)

Для публичных виджетов, которые передают данные пользователя на сторонний сервер, amoCRM рекомендует (и ряд требований обязывает) получить явное согласие пользователя при установке. Реализуется через скрытое обязательное поле + чекбокс.

В manifest.json добавьте скрытое поле:

"settings": {
  "oferta": { "name": "settings.oferta", "type": "custom", "required": true }
}

В callback settings добавьте чекбокс, который при нажатии записывает значение в скрытое поле oferta. Пока поле пустое — кнопка «Установить» не срабатывает, так как поле обязательное.

Загрузка виджета в amoCRM: пошаговая инструкция

Загрузка и регистрация виджетов происходит через раздел амоМаркет → «Моё приложение» (ранее это делалось через раздел «Интеграции»). Важное изменение: для новых виджетов поля code и secret_key в manifest.json больше не требуются — код генерируется автоматически. Для уже загруженных интеграций эти поля пока нужны.

Пошаговая инструкция

1. Войдите в amoCRM под учётной записью администратора.
2. Перейдите в амоМаркет → нажмите «Создать интеграцию» → выберите тип «Приватная интеграция» (требует загрузки архива с кодом).
3. Заполните основные данные интеграции: название, описание, логотип, категорию.
4. В редакторе кода заполните manifest.json: обновите version, проверьте locations, убедитесь в корректности всех обязательных полей.
5. Сохраните все файлы. Убедитесь, что кодировка UTF-8 без BOM.
6. Упакуйте содержимое папки в ZIP-архив. Архив ОБЯЗАТЕЛЬНО должен называться widget.zip. Файлы должны лежать в корне архива, не внутри дополнительной папки.
7. В режиме редактирования интеграции в амоМаркет загрузите widget.zip в поле загрузки виджета.
8. Если manifest.json содержит ошибки — система покажет описание проблемы. Исправьте и повторите загрузку.
9. После успешной загрузки виджет доступен в вашем аккаунте со статусом private.
10. Перейдите в раздел «Интеграции» вашего аккаунта, найдите виджет, нажмите на него и заполните поля настроек (API-ключ, логин — в зависимости от вашего manifest.json).
11. Нажмите «Установить». Если появится статус «Включён» — виджет успешно активирован.

Проверка работы виджета

После активации важно проверить, что виджет корректно инициализируется в нужных областях. Правило из практики: всегда проверяйте виджет в режиме инкогнито или после полной очистки cookies. Браузер кешируует JS-файлы виджетов, и без очистки кеша вы будете видеть старую версию, даже если уже загрузили новую.

• Откройте браузер в режиме инкогнито (Ctrl+Shift+N в Chrome)
• Войдите в amoCRM
• Откройте нужный раздел (например, список сделок или карточку контакта)
• Нажмите F12 → перейдите во вкладку Console (или Ctrl+Shift+J)
• Виджет должен показать инициализационные сообщения если вы добавили console.log в callbacks

Публикация в маркетплейсе: путь от private к public

После того как виджет протестирован в вашем аккаунте и готов к использованию другими компаниями, его можно опубликовать в маркетплейсе амоМаркет. После публикации (получения статуса public) виджет становится доступным всем аккаунтам amoCRM.

Требования к публичному виджету

Перед отправкой на модерацию виджет должен соответствовать следующим требованиям:

• Отсутствие дебаг-кода и тестовых данных в коде (console.log, временные ключи, тестовые URL)
• Готовое описание на всех заявленных языках (locale в manifest.json)
• Логотипы всех требуемых размеров (6 файлов) в папке images/
• Тур — слайды с демонстрацией функционала для каждой локали (минимум 2-3 изображения)
• В описании виджета указан телефон и email для поддержки конечных пользователей
• Запрещены виртуальные клики на кнопку «Установить» в JS-коде
• Запрещено скрывать рейтинг или отзывы виджета
• Запрещено влиять на рейтинг виджета программными методами

Как подать заявку на модерацию

Процедура публикации проходит через техподдержку amoCRM. Напишите в чат техподдержки прямо из вашего аккаунта amoCRM и укажите:

1. ID интеграции или код виджета, а также ID аккаунта, в котором создана интеграция.
2. Подробное описание работы виджета: что он делает, с какими сервисами интегрируется.
3. Инструкцию по подключению и работе с виджетом для конечного пользователя.
4. Тестовые данные для проверки (если виджет требует подключения к стороннему сервису), чтобы специалисты модерации могли проверить работоспособность.

Особенности логотипов и описаний в амоМаркет

Важный нюанс: логотип интеграции (который вы загружаете в карточку интеграции) и логотип виджета (в папке images/) — это два разных файла. На странице получения доступов отображается логотип интеграции. Если у интеграции есть виджет — логотип виджета отображается только там.

Ещё один нюанс: если виджет загружен в разделе амоМаркет → Моё приложение, то в модальном окне установки будет показываться название и описание из настроек интеграции, а не из manifest.json. Тем не менее, поля name и description в manifest.json остаются обязательными.

Продвинутые возможности виджетов

Digital Pipeline — виджет как триггер

Если в manifest.json в разделе locations указана область digital_pipeline, ваш виджет появится в настройках воронки как доступный триггер. Пользователь сможет настроить автоматическое действие виджета при смене этапа сделки. Для передачи данных триггеру без участия пользователя укажите в manifest.json параметр dp.webhook_url — amoCRM будет отправлять POST-запрос на этот адрес автоматически.

Salesbot Designer — виджет в сценариях

Виджет можно встроить в конструктор Salesbot как отдельный блок действия. Пользователь добавляет блок виджета в сценарий, настраивает его параметры, и виджет выполняет своё действие в нужный момент автоматически. Для этого в manifest.json заполняется раздел salesbot_designer, а в script.js реализуется callback onSalesbotDesignerSave.

SDK карточки и SDK списков

Для расширенной работы с карточками сделок, контактов и компаний amoCRM предоставляет специализированный SDK карточки (область card_sdk). Он позволяет работать с полями карточки программно — читать и изменять значения, добавлять кастомные блоки. Аналогично, SDK списков (область catalogs) предназначен для работы с каталогами и справочниками.

Мобильные виджеты

Для отображения виджета в мобильном приложении amoCRM используется параметр mobile_card в locations и mobile.frame_url в manifest.json. Виджет открывается в встроенном webview — по сути, это iframe с вашей страницей внутри мобильного приложения. Поддерживаются iOS и Android.

Виджет в веб-формах

С помощью области amoforms виджет можно добавить в конструктор веб-форм amoCRM. Это позволяет, например, интегрировать капчу, виджет телефонной верификации или любой кастомный компонент прямо в форму захвата лидов.

Модели монетизации виджетов amoCRM

Если вы разрабатываете виджет для публикации в маркетплейсе, важно заранее продумать модель монетизации. В амоМаркет существует несколько распространённых моделей.

Модель	Описание	Пример
Полностью бесплатный	Виджет устанавливается и работает без какой-либо оплаты	Базовые утилиты, open-source решения
Бесплатный виджет + платный сервис	Установка виджета бесплатна, но функционал работает только с платной подпиской на сторонний сервис	Виджеты телефонии: виджет бесплатен, оплата идёт оператору связи
Платный с демо-периодом	Виджет платный, но предоставляется пробный период 5–14 дней	Большинство профессиональных виджетов
Внешняя оплата	Стоимость не указана в маркетплейсе, пользователь узнаёт её после регистрации в сервисе	SaaS-продукты с индивидуальным ценообразованием

Варианты ценообразования

• За аккаунт (фиксированная цена) — пользователь платит за подключение аккаунта, независимо от числа пользователей
• За пользователя — стоимость умножается на количество активных пользователей в аккаунте
• Периоды оплаты: помесячно, поквартально, за полгода, за год. Многие разработчики указывают стоимость «от … в месяц» при оплате за полгода

Некоторые разработчики предлагают продление демо-периода за отзыв — практика, которая помогает быстро набрать первые оценки в маркетплейсе.

FAQ: частые вопросы разработчиков

Можно ли создать виджет без публикации в маркетплейсе?

Да. Виджет в статусе private доступен только в том аккаунте, где был загружен. Это удобно для кастомной разработки под конкретного клиента. Никакой модерации не требуется — загрузили widget.zip, активировали в Интеграциях, и виджет работает.

Виджет не отображается после загрузки — что делать?

Пошаговая диагностика:

1. Откройте браузер в режиме инкогнито и войдите в amoCRM — это исключит кеш как причину.
2. Перейдите в тот раздел, где виджет должен быть виден (например, lcard — карточка сделки).
3. Откройте DevTools → Console (F12). Ищите ошибки JavaScript.
4. Убедитесь, что в manifest.json в поле locations указана правильная область.
5. Убедитесь, что в callback render возвращается true.
6. Проверьте, что виджет активирован — статус «Включён» в разделе Интеграции.

Почему виджет работает только в некоторых разделах?

Это ожидаемое поведение. Виджет инициализируется только в тех областях, которые перечислены в locations в manifest.json. Чтобы виджет работал во всех разделах, добавьте все нужные коды областей. Подробный список областей доступен в официальной документации.

Как обновить уже опубликованный публичный виджет?

Загрузите новый widget.zip через амоМаркет в режиме редактирования интеграции. Обязательно увеличьте значение version в manifest.json — это помогает системе корректно обновить кешированные файлы у пользователей. Затем напишите в техподдержку amoCRM с описанием изменений для повторной проверки модератором.

Нужен ли SSL для внешнего сервера?

Рекомендуется использовать HTTPS с валидным SSL-сертификатом на вашем сервере. Метод crm_post работает через прокси-сервер amoCRM и позволяет обходить ограничения CORS, однако для production-решений HTTPS обязателен по соображениям безопасности.

В чём разница между виджетом и oAuth-интеграцией?

Виджет — это клиентская JS-часть, которая работает в браузере и взаимодействует с DOM интерфейса CRM. oAuth-интеграция — серверная авторизация для обращения к REST API amoCRM. Они не исключают друг друга: в рамках одного приложения можно иметь и JS-виджет (для UI), и серверную интеграцию (для фоновой обработки данных).

Как отлаживать виджет без лишних перезагрузок архива?

Для быстрой отладки используйте browser DevTools: ставьте breakpoints прямо в исходном коде виджета в вкладке Sources. Загружать новый widget.zip нужно только при изменении manifest.json или добавлении новых файлов. Если вы меняете только script.js — после загрузки нового архива откройте вкладку в инкогнито, чтобы исключить кеш.

Сколько времени занимает модерация?

Официальных сроков amoCRM не публикует. На практике модерация занимает от нескольких рабочих дней до нескольких недель в зависимости от загруженности команды. Рекомендуем подавать заявку на модерацию, когда виджет полностью готов и протестирован — возврат на доработку занимает дополнительное время.

Чеклист разработчика перед загрузкой виджета

Используйте этот список как финальную проверку перед каждой загрузкой widget.zip.

Файлы проекта

• manifest.json присутствует, валидный JSON (проверьте на jsonlint.com)
• Все файлы в кодировке UTF-8 без BOM
• script.js возвращает true из callbacks render, init, bind_actions
• В папке images/ есть все 6 обязательных файлов логотипов нужных размеров
• Папка i18n/ содержит файлы для всех языков из параметра locale
• Структура JSON-файлов локализации идентична

manifest.json

• Заполнены все обязательные поля: name, description, short_description, version, locale, locations, support
• Версия виджета увеличена по сравнению с предыдущей загрузкой
• Параметр tour заполнен: is_tour: true, изображения для каждой локали, описание
• Список locations корректен: включены только нужные области
• Для новых виджетов: поля code и secret_key не нужны в manifest

Код виджета

• Нет отладочного кода: убраны лишние console.log, alert, временные данные
• Нет тестовых API-ключей и паролей в коде
• Виджет не производит виртуальных кликов на «Установить»
• CSS подключается с параметром версии (style.css?v=version)

Архив

• Архив называется строго widget.zip
• Файлы лежат в корне архива, НЕ внутри дополнительной папки
• Размер архива не чрезмерно велик (логотипы не превышают 300 КБ каждый)

Для публичного виджета дополнительно

• Готова инструкция по подключению и использованию
• В описании указаны телефон и email поддержки
• Подготовлены тестовые данные для модератора (если нужна авторизация в стороннем сервисе)
• Описание и название финализированы на всех языках

Полезные материалы