Виджет Kulpunai в вашей CRM
Виджет 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 и нажмите кнопку ещё раз.
