Главная Интеграции и API Виджет Kulpunai в вашей CRM

Виджет Kulpunai в вашей CRM

Обновлено 1 октября 2026

Виджет Kulpunai в вашей CRM

Встраиваемый виджет добавляет на страницы вашей CRM плавающую кнопку. По клику открывается панель с диалогами Kulpunai: список обращений, чат, ответы, шаблоны и вложения работают так же, как в основном приложении. Оператор не переключается между вкладками, а CRM может открыть нужный диалог прямо из карточки лида.

Подходит для любой CRM, в которую можно добавить строку скрипта: Bitrix24, amoCRM, собственная разработка.

Что понадобится

  • Роль администратора в Kulpunai;
  • Домен CRM, на страницах которой появится виджет, с доступом по HTTPS;
  • Возможность вставить скрипт в шаблон страниц CRM.

Шаг 1. Разрешите домены

  1. Откройте Настройки → Интеграции → Встраиваемый виджет.
  2. В блоке Разрешённые домены введите домен CRM и нажмите Добавить. Примеры: crm.example.com, https://*.bitrix24.ru, localhost:3001 для локальной проверки.
  3. Нажмите Сохранить.

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

Шаг 2. Вставьте код

В блоке Код для установки нажмите Копировать код и вставьте сниппет перед закрывающим тегом </body> на страницах CRM, где нужен виджет. Код уже содержит адрес платформы и номер вашего аккаунта:

<script>
  (function (d, t) {
    var g = d.createElement(t), s = d.getElementsByTagName(t)[0];
    g.src = 'https://online.kulpunai.com/packs/js/embed.js';
    g.async = true;
    s.parentNode.insertBefore(g, s);
    g.onload = function () {
      window.kulpunaiEmbed.run({ baseUrl: 'https://online.kulpunai.com', accountId: 123 });
    };
  })(document, 'script');
</script>

После загрузки страницы справа внизу появится кнопка. Клик открывает панель, повторный клик или кнопка «Свернуть» в шапке панели скрывает её.

Шаг 3. Вход в панель

При первом открытии панель показывает форму входа Kulpunai. Есть три способа войти:

  • Логин и пароль оператора, как в основном приложении;
  • Кнопка «Продолжить с открытой сессией Kulpunai» — если оператор уже вошёл в Kulpunai в другой вкладке, откроется небольшое окно, которое передаст сессию в панель и закроется само;
  • Автоматически в Chrome с настройками по умолчанию: панель сразу видит открытую сессию и входит без клика.

Вход через Google и SSO внутри панели недоступен: браузеры не разрешают такие окна во встроенных страницах. Если браузер блокирует хранилище для встроенных страниц (например, режим инкогнито в Chrome), панель покажет сообщение со ссылкой открыть Kulpunai в новой вкладке.

Открыть диалог из карточки лида

Виджет принимает команды со страницы CRM. Чтобы по клику открыть конкретный диалог, вызовите:

window.kulpunaiEmbed.openConversation(4821);

Число — номер диалога, тот же, что в адресе чата в Kulpunai. Панель откроется сама; если оператор ещё не вошёл, команда выполнится сразу после входа.

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

  • kulpunaiEmbed.open(), close(), toggle() — управление панелью;
  • kulpunaiEmbed.openConversation(id) — открыть диалог;
  • kulpunaiEmbed.on('ready', fn) — оператор вошёл, панель готова;
  • kulpunaiEmbed.on('unread', fn) — изменилось число непрочитанных, fn получает { count };
  • kulpunaiEmbed.on('conversation:opened', fn) — открыт диалог, fn получает { conversationId };
  • kulpunaiEmbed.on('auth:required', fn) — панель показывает форму входа.

Откуда CRM берёт номер диалога

Через вебхук. В Настройки → Интеграции → Webhooks подпишите адрес вашего бэкенда на событие conversation_created. В запросе приходит номер диалога в поле id и контакт в meta.sender с телефоном, именем и email. Сохраните номер в карточке лида и передавайте его в openConversation. Подробнее — в статье «Webhooks».

Через API. Если лид создан раньше, чем клиент написал, бэкенд CRM находит диалог по телефону двумя запросами с токеном оператора (см. статью «API и токен доступа»):

GET /api/v1/accounts/123/contacts/search?q=%2B996555123456
GET /api/v1/accounts/123/contacts/917/conversations

Первый запрос возвращает контакт, второй — его диалоги; возьмите id самого свежего.

Для Bitrix24 отдельно ничего делать не нужно: интеграция уже пишет в таймлайн лида номер диалога и ссылку на него.

Ссылка на лид внутри панели

Чтобы оператор видел карточку CRM прямо в чате, запишите её адрес в атрибуты контакта Kulpunai:

PATCH /api/v1/accounts/123/contacts/917
{ "custom_attributes": { "crm_lead_url": "https://crm.example.com/leads/4821" } }

Заведите атрибут crm_lead_url в Настройки → Пользовательские атрибуты с типом «ссылка», и он появится в боковой панели контакта.

Синхронизация назначения оператора

Назначение работает в обе стороны без доработок виджета.

Из Kulpunai в CRM. Подпишите бэкенд CRM на событие conversation_updated в Настройки → Интеграции → Webhooks. Оно приходит при любой смене оператора или команды, в том числе при автоназначении. Текущий оператор лежит в meta.assignee, команда — в meta.team:

{
  "event": "conversation_updated",
  "id": 4821,
  "status": "open",
  "meta": {
    "assignee": { "id": 7, "name": "Айгуль", "availability_status": "online" },
    "assignee_type": "User",
    "team": { "id": 2, "name": "Продажи" }
  }
}

Пустой meta.assignee означает, что диалог никому не назначен. Email оператора в событии не передаётся: сопоставьте id с пользователем CRM по списку GET /api/v1/accounts/123/agents, где есть id, name и email. Событие приходит и при других изменениях диалога (статус, метки, приоритет), поэтому сравнивайте оператора с сохранённым и реагируйте только на реальную смену.

Из CRM в Kulpunai. Чтобы назначить или сменить оператора, отправьте запрос с токеном доступа:

POST /api/v1/accounts/123/conversations/4821/assignments
{ "assignee_id": 7 }

Пустой assignee_id снимает назначение. Чтобы назначить команду, передайте team_id вместо assignee_id. Оператор должен быть добавлен в канал диалога; кто подходит, покажет GET /api/v1/accounts/123/inboxes/<id канала>/assignable_agents.

Чтобы не зациклиться. После назначения из CRM Kulpunai пришлёт conversation_updated обратно. Если оператор в событии совпадает с тем, кого CRM только что поставила, событие пропускают.

Ограничения

  • Один сниппет обслуживает один аккаунт Kulpunai; оператор должен быть участником этого аккаунта;
  • Панель показывает те же диалоги и права, что и основное приложение: оператор видит только доступные ему обращения;
  • В Safari сессия внутри панели сбрасывается после недели без использования, оператору нужно войти снова;
  • На экранах уже 480 пикселей панель раскрывается на весь экран.

Если что-то не работает

  • Кнопка не появляется — проверьте, что скрипт загружается с online.kulpunai.com и в консоли браузера нет ошибок. Убедитесь, что в сниппете правильный accountId.
  • Панель пустая — домен страницы не добавлен в Разрешённые домены или указан с ошибкой. Домен должен совпадать со страницей, на которой стоит сниппет, включая порт.
  • Панель показывает сообщение о блокировке хранилища — браузер запрещает встроенным страницам хранить данные. Разрешите сторонние cookie для online.kulpunai.com или откройте Kulpunai в новой вкладке по ссылке из сообщения.
  • Кнопка «Продолжить с открытой сессией» не срабатывает — браузер заблокировал всплывающее окно. Разрешите его для домена CRM и нажмите кнопку ещё раз.