Разработчику
JS API и события
Как открыть чат, задать вопрос за посетителя, сказать, кто он, и узнать, что разговор ушёл к людям.
Ваша страница может управлять <tolkly-chat> через методы элемента и слушать три события. Для
обычной установки это не нужно.
Как получить элемент
Методы появляются, когда скрипт объявит элемент. Дождитесь этого:
await customElements.whenDefined('tolkly-chat')
const chat = document.querySelector('tolkly-chat')
chat.open()Методы
| Метод | Что делает |
|---|---|
open({ focus }) | Открывает чат. Если нужно, сначала загружает окно. По умолчанию фокус переходит в чат; с focus: false он остаётся на месте. |
close() | Сворачивает чат. У чата с inline ничего не делает. |
ask(text) | Открывает чат, если он закрыт, и отправляет text от имени посетителя. Возвращает promise. Ничего не делает, если text пустой или ещё приходит прошлый ответ. Сервер принимает до 1000 символов. |
identify(token) | Сообщает чату, кто посетитель, токеном, который подписал ваш сервер. Вызывайте после входа на сайт (подпись посетителя). |
identify({ id, name, email, phone, fields }) | Сообщает чату, кто посетитель, без подписи. Операторы увидят пометку «Не проверено». Общей истории между устройствами у такого посетителя не будет. Обязателен только id. |
reset() | Вызывайте при выходе. Чат забывает посетителя и разговор, сохранённый в этом браузере, и начинает заново. Также перестаньте выводить data-identity. |
Подсказанные вопросы
suggestions — это свойство, а не атрибут. В нём вопросы, которые чат предлагает до первого
сообщения. Заданные страницей, они заменяют на ней вопросы из «Виджета»: например, вопрос про одно
направление обмена на его странице.
chat.suggestions = ['How long does a withdrawal take?', 'Which documents do you need?']
chat.suggestions = null // снова вопросы из «Виджета»Чат берёт до 6 вопросов, пустые пропускает. Они видны только до первого сообщения посетителя. Вопросы, заданные страницей, в отчёте не считаются, вопросы из «Виджета» — считаются (Частые вопросы).
События
Все три события всплывают и проходят через shadow root (composed). Поэтому их можно слушать на
document:
document.addEventListener('tolkly:handoff', (event) => {
const { reason, tokens } = event.detail
console.log('handed to people:', reason, tokens)
})
document.addEventListener('tolkly:resolved', (event) => {
console.log('the visitor says this answer helped:', event.detail.answerId)
})tolkly:handoff
Разговор уходит к людям. Событие срабатывает в этой вкладке, когда:
- бот передаёт разговор людям, пока отвечает на сообщение;
- сообщение сразу уходит людям: в режиме «только операторы», когда лимит ИИ исчерпан (месячный лимит компании или дневная защита проекта), или когда посетитель отправил файл отдельно, без текста;
- посетитель нажимает кнопку, которая зовёт человека.
Событие не срабатывает, когда:
- бот отказывается отвечать;
- бот только предлагает позвать человека;
- посетитель переходит по ссылке
handoff; - подключается оператор;
- разговор восстанавливается при загрузке страницы.
detail.tokens — номера заявок и хэши транзакций из вопроса:
{ kind: 'order' | 'tx', value: string }[]. detail.reason — одно из значений:
reason | Почему |
|---|---|
requested | Посетитель попросил человека. |
personal_case | Вопрос о заявке, платеже или аккаунте самого посетителя. Проверить это могут только сотрудники. |
topic | Сообщение на одну из тем, которые проект передаёт человеку. |
operators_only | Проект работает без ИИ: каждое сообщение уходит людям. |
cap_reached | Лимит ИИ исчерпан: месячный лимит ИИ-диалогов компании (Тариф, оплата и лимит) или дневная защита проекта (Как отвечает Tolkly). Вместо бота отвечают люди. |
attachment | Посетитель отправил файл, а бот файлы не читает. |
scenario | Система заявок проекта не ответила боту (ошибка, таймаут, неизвестный статус), поэтому вопрос берут люди. |
tolkly:resolved
Посетитель нажал «Помогло» под ответом бота. detail.answerId — id ответа или null, если чат
его не знает. Событие срабатывает один раз на ответ. На оценку после того, как оператор закрыл
разговор, оно не срабатывает.
tolkly:unread
Изменилось число ответов, которые посетитель ещё не прочитал. detail.unread — их число,
detail.ask — true, когда чат просит контакт, а посетитель этого ещё не видел. Событие
срабатывает только при изменении. С launcher="none" так ваша страница показывает отметку, которую
показала бы кнопка:
document.addEventListener('tolkly:unread', (event) => {
const { unread, ask } = event.detail
helpButton.classList.toggle('has-news', unread > 0 || ask)
})Язык
Чат говорит на языке из своего атрибута lang. Если атрибута нет — на языке из <html lang>.
Чат следит за обоими. Если сайт меняет язык без перезагрузки или задаёт chat.lang = 'ru', чат
перерисовывается на новом языке и заново загружает разговор с сервера.
У чата есть тексты на 15 языках: en, ru, hy, kk, uz, az, ka, ky, tg, uk, tr,
de, es, fr и pt. Для любого другого языка он берёт основной язык проекта
(Как выглядит чат), а если он не задан — английский, но имена операторов
всё равно следуют языку страницы.