Веб-виджет

Технические имена, такие как window.SingChat, относятся к виджету и API. Используйте их в коде ровно в таком виде.

Веб-виджет — это один скрипт, widget.js, который загружается с askais.com. Он добавляет на страницы кнопку чата и отрисовывает окно чата внутри Shadow DOM, поэтому стили вашего сайта и стили виджета не пересекаются.

Добавьте виджет на сайт

Вставьте этот код перед </body> на каждой странице, где должен появляться чат. App ID находится в разделе Настройки → Входящие.

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  async></script>

data-base-url обязателен на вашем сайте: без него виджет ищет свой сервер на вашем домене, а не на askais.com.

⚠️ Загружайте widget.js с askais.com

Не скачивайте widget.js и не встраивайте его в свой код. При загрузке с askais.com всегда работает актуальная версия, а копия застывает и не получает ни исправлений, ни новых функций.

Атрибуты скрипта

Всё настраивается атрибутами data- в теге script:

• data-app-id — Обязательный. App ID ваших входящих.
• data-base-url — Обязательный на вашем сайте. Всегда https://askais.com.
• data-locale — Необязательный. Задаёт язык виджета, например ja или zh-Hant. Если его не указать, виджет использует язык устройства посетителя, а затем lang вашей страницы.
• data-external-id — Ваш ID авторизованного пользователя.
• data-email — Email пользователя, его видит ваша команда.
• data-name — Имя пользователя, его видит ваша команда.
• data-avatar-url — Ссылка на фото профиля пользователя.
• data-hmac — Подпись личности, см. ниже.
• data-attrs — Дополнительные данные в формате JSON, например {"plan":"Pro"}; команда видит их в профиле посетителя. Некорректный JSON игнорируется.

data-embed, data-platform, data-app-version и data-device-model задаёт страница чата в приложении. См. «Чат в приложении (WebView)».

Авторизованные посетители

Для авторизованного пользователя добавьте его данные в тег script. Команда видит, с кем говорит, а чат переходит вместе с пользователем на другие устройства:

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  data-external-id="user_123"
  data-email="ada@example.com"
  data-name="Ada Lovelace"
  data-attrs='{"plan":"Pro"}'
  data-hmac="SIGNATURE_FROM_YOUR_SERVER"
  async></script>

Без data-external-id виджет присваивает каждому браузеру собственный анонимный ID и хранит его в локальном хранилище браузера, поэтому в этом браузере история чата сохраняется после перезагрузки страницы. Если у входящих есть форма перед чатом, анонимные посетители заполняют её до начала чата.

Подтверждённая личность (HMAC)

• hmac — это HMAC-SHA256 от externalId с секретным ключом входящих в качестве ключа, записанный в шестнадцатеричном виде строчными буквами.
• Вычисляйте его на своём сервере. Секретный ключ никогда не должен попадать на страницу или в приложение.
• Секретный ключ показывается один раз при создании входящих и ещё раз, когда вы меняете его в разделе Настройки → Входящие. После смены ключа все старые подписи становятся недействительными.
• Всегда передавайте data-external-id вместе с data-hmac. Подпись проверяется по внешнему ID, поэтому подпись только от email отклоняется.
• С неверной подписью виджет не сможет подключиться. Без data-hmac данные принимаются в том виде, в каком их передаёт страница, поэтому любой, кто может изменить страницу, может выдать себя за другого человека.

Пример для Node.js:

import { createHmac } from "node:crypto";

// Runs on your server. INBOX_SECRET_KEY never leaves it.
const hmac = createHmac("sha256", INBOX_SECRET_KEY)
  .update(user.id) // the exact value you pass as data-external-id
  .digest("hex");

Запуск виджета из JavaScript

Чтобы запустить виджет самостоятельно, например когда страница уже знает, кто пользователь, загрузите скрипт без data-app-id и вызовите window.SingChat.start() после его загрузки:

<script src="https://askais.com/widget.js"></script>
<script>
  window.SingChat.start({
    appId: "YOUR_APP_ID",
    baseUrl: "https://askais.com",
    // optional, for a signed-in user:
    externalId: "user_123",
    email: "ada@example.com",
    name: "Ada Lovelace",
    hmac: "SIGNATURE_FROM_YOUR_SERVER",
  });
</script>

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

Внешний вид и поведение

• Настройки → Входящие, затем разверните нужные входящие: основной цвет и цвет текста, положение (внизу справа или внизу слева), размер пузыря, светлый или тёмный фон, заголовок и подзаголовок окна — с живым предпросмотром.
• Форма перед чатом (там же): запрашивайте у анонимных посетителей email, имя, телефон или компанию до начала чата.
• Разрешённые источники (там же): сайты, которым разрешено загружать виджет этих входящих. Пустой список разрешает любой сайт.
• Брендинг виджета (там же): строка «Powered by» внизу чата. Можно ли её скрыть или показать там своё название, зависит от вашего тарифа.
• Приветственное сообщение ИИ задаётся в разделе ИИ-агент, кликабельные пузыри с частыми вопросами — в разделе Настройки → Частые вопросы, а статьи — в разделе Help Center.

Безопасность

• App ID публичный, его можно спокойно размещать в HTML.
• Секретный ключ входящих должен храниться только на вашем сервере.
• Используйте подтверждённую личность (HMAC) всегда, когда страница знает, кто пользователь.
• Ограничьте разрешённые источники своими доменами, чтобы виджет нельзя было загрузить на других сайтах.