Документация по интеграции

Встраивание вешалки

Внедрите виджет службы поддержки на ваш сайт, добавив всего одну строку кода.

Получение кода внедрения

Войдите в панель управления продавцом → Настройки каналов → Код внедрения, скопируйте свой уникальный код внедрения:

<script>
  window.$aicrs = window.$aicrs || { q: [] };
</script>
<script async src="https://ваш-домен-поддержки/widget/loader.js" data-wk="ваш widget_key"></script>

Вставьте этот код перед </body> на каждом странице вашего сайта. Виджет будет отображаться в виде всплывающего окна чата в правом нижнем углу страницы, посетитель может нажать на него, чтобы начать консультацию.

Белый список доменов

Чтобы предотвратить кражу виджета, он будет работать только на зарегистрированных вами доменах. Добавьте домен вашего сайта (поддерживаются несколько) в панели управления продавцом → Настройки каналов → Белый список доменов. Незарегистрированные домены при загрузке виджета будут работать в режиме без ошибок, что не повлияет на вашу страницу.

Перезапись widget_key

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

Часто задаваемые вопросы

• Не отображается виджет? Проверьте, находится ли текущий домен в белом списке, совпадает ли widget_key с тем, что указан в панели управления, и находится ли ваш аккаунт в периоде действия.
• Влияет ли это на скорость сайта? Размер загрузчика меньше 1КБ, и он загружается асинхронно, не блокируя рендеринг вашей страницы.

Идентификация, членство, подключение

После входа пользователя на ваш сайт вызывается функция identify с передачей информации о клиенте, и система обслуживания клиентов привяжет текущую сессию браузера к этому клиенту — оператор увидит информацию о клиенте, и посещения с разных устройств будут объединены в одного посетителя.

Метод вызова

Вызовите, когда на вашей странице будет определено, что пользователь вошёл в систему:

$aicrs.identify({
  externalId: 'U10086',      // Обязательно, уникальный идентификатор пользователя в вашей системе
  name: 'Леди Ли',             // Необязательно, отображаемое имя
  phone: '138****0000',      // Необязательно
  email: 'user@example.com', // Необязательно
  hash: 'Подпись HMAC, вычисленная на стороне сервера',  // Обязательно, защита от подделки
  custom: { vip: 'gold' }     // Необязательно, дополнительные поля, видимые оператором
})

Алгоритм подписи

hash должен быть вычислен на вашей серверной стороне (widget_secret не должен быть в коде клиента):

hash = HMAC-SHA256(widget_secret, externalId) в шестнадцатеричном виде в нижнем регистре

widget_secret находится в: Панель партнёра → Настройка каналов → Встроенный код, и он сбрасывается вместе с widget_key.

Пример на Node.js:

const crypto = require('crypto')
const hash = crypto.createHmac('sha2 hash = crypto.createHmac('sha256', WIDGET_SECRET).update(externalId).digest('hex')

Результат проверки

Посетители с успешно проверенной подписью будут отображаться в системе оператора с отметкой "Проверен". Если проверка подписи не удалась, вызов identify будет проигнорирован, а анонимность посетителя сохранится, не прерывая работу страницы и не вызывая ошибок.

Отправка событий веб-хука

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

Настройка

Панель управления клиентом → Данные и система → Webhook: укажите URL обратного вызова (должен быть HTTPS) и секретный ключ подписи secret, выберите типы событий для подписки. После сохранения можно нажать «Отправить тестовое событие», чтобы сразу настроить интеграцию.

Формат запроса

Каждое уведомление — это POST-запрос:

POST Ваш URL обратного вызова
Content-Type: application/json
X-AICRS-Event: Тип события
X-AICRS-Signature: HMAC-SHA256(secret, Тело запроса) в шестнадцатеричном виде, строчные буквы

Структура тела запроса:

{
  "event": "message.created",
  "tenant_id": 129,
  "timestamp": 1784500000,
  "data": { "объектный снимок": "..." }
}

Типы событий

Проверка подписи и повторная попытка

После получения уведомления вычислите HMAC-SHA256 от оригинального тела запроса с использованием секретного ключа и сравните его с X-AICRS-Signature. Если значения не совпадают, сообщение следует отбросить.

Возврат 2xx вашим интерфейсом считается успешным; при неудаче будет выполнено 3 повторных попытки с интервалами 1 минута / 5 минут / 15 минут. Если все попытки завершатся неудачей, статус будет установлен как «ошибка», причину можно будет найти в записях о доставке в панели управления и вручную устранить проблему.

Открытый API

Открытый API позволяет считывать данные службы поддержки из вашей системы, создавать заявки, обеспечивая изоляцию по мерчантам.

Аутентификация

Панель мерчанта → Данные и система Генерация API Key (начинается с ak_, в виде открытого текста отображается только один раз при генерации, сохраните его осторожно; старый ключ становится недействительным сразу после сброса).

Все запросы должны содержать заголовок:

Authorization: Bearer ak_ВашКлюч

Ограничение частоты запросов

На каждый ключ максимально 120 запросов в 60 секунд, при превышении возвращается 429.

Список интерфейсов

Пример:

curl -H "Authorization: Bearer ak_xxx" \
  "https://ВашДоменПоддержки/api/open/v1/conversations?page=1"

Описание

• Все ответы в формате JSON, интерфейсы списков поддерживают параметр page для пагинации.
• В текущей версии не поддерживается отправка сообщений посетителям через API.
• При приостановке мерчанта или истечении срока действия услуги API также приостанавливается.

Сопоставление кодов ошибок

Все ответы об ошибке API унифицированы в структуре JSON:

{ "code": "код ошибки", "message": "подсказка на китайском языке" }

Соответствие кода состояния HTTP и кода:

Рекомендации по обработке:

• 401/403: Проверьте, действителен ли Key и состояние сервиса учетной записи.
• 429: Повторите попытку позже согласно Retry-After или стратегии отступления.
• 5xx: Для идемпотентных интерфейсов можно безопасно повторить запрос; для неидемпотентных операций сначала выполните запрос подтверждения, а затем повторите запрос.

CRM открытый интерфейс

Чтение и запись данных клиентов и деловой информации осуществляются через открытый API (/api/open/v1, Bearer ak_ ключ, сгенерированный в разделе "Данные и система → API" в админке мерчанта).

Клиенты

Правило дедупликации такое же, как в админке: external_id > телефон > почта. При совпадении данные объединяются с уже существующим клиентом, вместо повторного создания.

Ограничение по частоте: 120 запросов на ключ в 60 секунд, при превышении возвращается 429.

Отправка событий клиентов

События жизненного цикла клиента проходят через существующий канал вебхуков (подписка в административной панели продавца "Данные и система → Вебхуки"), подписи и механизм повторных попыток идентичны событиям сообщений (X-AICRS-Signature HMAC-SHA256, экспоненциальное отступление при повторе).

Формат полезной нагрузки: {"event":"customer.created","data":{...объект клиента...},"ts":1690000000}. При получении вебхука, возврат кода 2xx подтверждает успешный прием; при получении не 2xx или превышении времени ожидания будет выполнено повторное обращение в соответствии с политикой отступления.