For developers

JS API and events

Open the chat, ask a question for the visitor, say who they are, and learn when a conversation goes to people.

Open in…
On this page

Your page can control <tolkly-chat> with methods on the element and listen to three events. A plain install needs none of this.

Getting the element

The methods appear once the script defines the element. Wait for that:

JavaScript
await customElements.whenDefined('tolkly-chat')
const chat = document.querySelector('tolkly-chat')
chat.open()

Methods

MethodWhat it does
open({ focus })Opens the chat. Loads its window first if needed. By default, focus moves into the chat; focus: false leaves it where it is.
close()Minimizes the chat. Does nothing on an inline chat.
ask(text)Opens the chat if it is closed and sends text as the visitor's message. Returns a promise. Does nothing if text is empty or an answer is still coming. The server accepts up to 1000 characters.
identify(token)Tells the chat who the visitor is, with a token your server signed. Call it after the visitor signs in on your site (identity).
identify({ id, name, email, phone, fields })Tells the chat who the visitor is, without a signature. Operators see the visitor marked «not verified». Such a visitor never gets a history shared across devices. Only id is required.
reset()Call it on sign-out. Forgets the visitor and the conversation stored in this browser, and the chat starts over. Also stop rendering data-identity.

Suggested questions

suggestions is a property, not an attribute. It holds questions the chat offers before the first message. Set on a page, they replace the questions from «Widget» on that page, for example a question about one exchange direction on its own page.

JavaScript
chat.suggestions = ['How long does a withdrawal take?', 'Which documents do you need?']
chat.suggestions = null // the questions from «Widget» again

The chat keeps up to 6 and drops empty ones. They show only until the visitor's first message. Questions set by a page are not counted in the report; the ones from «Widget» are (Frequent questions).

Events

All three events bubble and cross the shadow root (composed). So you can listen on document:

JavaScript
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

The conversation goes to people. The event fires in this tab when:

  • the bot hands the conversation over while answering a message;
  • a message goes straight to people: in operators-only mode, after the AI limit is spent (the company's month or the project's daily guard), or when the visitor sends a file on its own;
  • the visitor presses the button that calls a person.

It does not fire when:

  • the bot refuses to answer;
  • the bot only offers a person;
  • the visitor follows the handoff link;
  • an operator joins;
  • a conversation is restored on page load.

detail.tokens lists order numbers and transaction hashes found in the question: { kind: 'order' | 'tx', value: string }[]. detail.reason is one of:

reasonWhy
requestedThe visitor asked for a person.
personal_caseThe question is about the visitor's own order, payment or account. Only staff can check it.
topicThe message is about one of the topics the project sends to a person.
operators_onlyThe project runs without the AI: every message goes to people.
cap_reachedThe AI limit is spent: the company's month of AI conversations (Plan, payment and limit) or the project's daily guard (How Tolkly answers). People answer instead of the bot.
attachmentThe visitor sent a file, which the bot does not read.
scenarioThe project's order system did not answer for the bot (an error, a timeout, an unknown status), so people take it.

tolkly:resolved

The visitor pressed «It helped» under a bot answer. detail.answerId is the answer's id, or null if the chat does not know it. The event fires once per answer. It does not fire for the rating the visitor gives after an operator closes a conversation.

tolkly:unread

The replies the visitor has not read changed. detail.unread is their count, detail.ask is true when the chat asks for a contact the visitor has not seen yet. It fires only on a change. With launcher="none" this is how your page shows the mark the button would have shown:

JavaScript
document.addEventListener('tolkly:unread', (event) => {
  const { unread, ask } = event.detail
  helpButton.classList.toggle('has-news', unread > 0 || ask)
})

Language

The chat uses the language of its lang attribute. Without it, the chat uses <html lang>.

The chat watches both. If your site switches language without a reload, or sets chat.lang = 'ru', the chat redraws itself in the new language and loads the conversation from the server again.

The chat has texts in 15 languages: en, ru, hy, kk, uz, az, ka, ky, tg, uk, tr, de, es, fr and pt. Any other language gets the project's primary language (How the chat looks), or English when none is set, but operators' names still follow the page's language.