Webchat

Webchat puts your assistant on your own website as a chat window. Visitors ask their question or request an appointment without calling, and your team can read along or take over at any time. This article explains how to enable, style and embed the widget, and how to control it from JavaScript.

Enabling webchat

You need the Editor or Admin role, and an active subscription. Webchat is included in every plan. If your subscription stops, the widget no longer appears on your website.

1. Open Assistants, choose the assistant and go to the Channels tab.
2. Open the Webchat row and switch Enable webchat on. Without an active subscription the switch stays off and you see where to choose a plan.
3. Check Public link name. A name is already filled in, and you can change it: lowercase letters, digits and dashes (for example smith-plumbing). The name must be unique across Yarla; otherwise you see "That chat link is already in use". It appears in the chat page URL and in the code for your website.
4. There is nothing to save by hand. Text is saved when you leave the field; switches, dropdowns and checkboxes straight away. At the bottom of the row you find Code for your website and the Ready-made chat page link.

Appearance

In the same row you match the widget to your branding.

Setting	Meaning	Default
Colour	The main colour of the widget: launcher button, header, send button and the visitor's messages.	Purple (#8237f0)
Position	Which side of the bottom of the page the launcher sits on: Right or Left.	Right
Title	The text in the chat window header. Empty means your business name, which follows a change of name by itself.	Empty
First message in the chat	The first message the visitor sees when the window opens. Empty = your assistant's greeting and, if that is empty too, a standard line.	Empty
Input placeholder	The grey hint text in the typing field, for example "Ask us anything…". Empty = a standard text in your assistant's language, such as "Type your message...".	Empty
Footer text	A short line below the typing field, for example "Replies are generated by AI". Empty = no line.	Empty
Button label	The text on the launcher, for example "Ask us". Empty = a standard word in your assistant's language, usually "Chat".	Empty

Changes apply on your website as soon as a visitor reloads the page; you do not need to re-add the code. The one exception is Public link name: if you change it, the old name stops working, in links to the chat page too, so you do need to re-add the code.

Who answers and handover

Setting	Meaning	Default
Who answers	The assistant: the assistant answers every conversation and only hands over if the visitor insists on a person. The team: the first message goes straight to the Inbox, the visitor gets a short confirmation and your team replies; the assistant does nothing. Conditional: the assistant answers and hands over once the condition below applies or the visitor insists on a person.	The assistant
Handover condition	In plain language, when the assistant should hand over, for example "If the visitor wants a quote above £5,000 or asks for a member of staff". Only visible with Conditional. If you later go back to The assistant, a condition you filled in still applies, so empty it first.	Empty
Inactivity timeout (minutes)	A number from 5 to 1,440. After this many minutes without a message the chat closes and the actions after the conversation run (for example an email, SMS or webhook). It closes sooner when the customer says goodbye and the assistant wraps up, or when you end it in the Inbox. When the customer waits for your team, the chat stays open until someone answers or ends it, also over the weekend; after that it closes after 18 quiet hours. A closed chat doesn't continue: the visitor starts a new one.	60
Allowed websites	List of websites where the widget may load, with https:// in front, for example https://www.example.com. 200 at most. The address must match exactly: with and without www and each subdomain are separate lines. On other sites the widget stays invisible. Empty = the widget loads anywhere. If you turn the chat on while this list is empty, we fill in your website from Settings → Business, with and without www. After that the list is yours.	Empty

A conversation can also close sooner: the assistant closes it after saying goodbye (after a thank-you it first asks whether it can help with anything else), and your team can end it. Once a conversation is closed, the visitor can no longer type in it. The chat page then shows the Start a new conversation button. The widget on your website has no such button and stays on the closed conversation in that browser; you start a new one there with startNewConversation() (see JavaScript SDK).

Limit the websites

Always enter your own website(s) under Allowed websites. That way nobody can copy your code and run your assistant on another website, where the replies would still count towards your usage.

Embed on your website

Copy the line under Code for your website and add it to your website's HTML, just before the closing </body> tag. Your name and the addresses are already correct in it. The line looks like this:

<script src="https://<dashboard-domain>/widget.js" data-slug="<slug>" data-api="https://<chat-api>" async></script>

data-api is the chat API from the dashboard, not the dashboard API. A snippet copied earlier that still points at the dashboard API no longer works. Copy the snippet again.

Thanks to async the widget loads in the background and does not slow your page down.

How you add the line depends on your website platform:

• WordPress: use a header/footer scripts plugin (search the plugin directory for "header footer scripts") and paste the code into the footer field. Alternatively add it to footer.php of your (child) theme.
• Webflow: go to Project settings → Custom code and paste the code under Footer code. Republish the site.
• Squarespace: go to Settings → Advanced → Code injection and paste the code into the Footer field.
• Other platforms: look in the settings for "custom code", "scripts" or "tracking code" for the footer. If in doubt, send the line to your web developer.

Replies from your team and strict security policies

When a chat is with your team, the widget checks every 5 seconds whether there is a new message. When it stays quiet, that slows down to once every 30 seconds, and it pauses while the tab is in the background. So the visitor usually sees your reply within 5 to 30 seconds. Where a live WebSocket connection to Yarla is available, the reply appears almost immediately. The widget opens that connection by itself; there is nothing to set up. The widget starts watching once it knows the conversation is with your team. If you take over a conversation while the visitor is doing nothing, your reply only appears when the visitor sends something, opens the window or reloads the page.

If your website sends a strict Content-Security-Policy header, add the live-updates address to connect-src, next to the chat API address:

connect-src https://<chat-api> wss://*.execute-api.eu-central-1.amazonaws.com

Also allow https://<dashboard-domain> in script-src and inline styles ('unsafe-inline') in style-src: that is where the script comes from, and the widget adds a style block of its own to your page.

Without the wss:// address the chat still works. The widget then simply keeps checking for new messages as described above. Your website's security policy does not apply to the chat page.

Ready-made chat page

If you would rather offer the chat without adding anything to your website, use the Ready-made chat page link:

https://<dashboard-domain>/en/chat/<slug>

Replace /en/ with /nl/ or /es/ for Dutch or Spanish buttons and notices on the page; the assistant itself answers the way you set it up. The page shows your title, your assistant's name and the chat window, in your colour. Handy as a link in your email signature, on social media or as a QR code on your van and quotes.

JavaScript SDK

Once the script has loaded, the window.YarlaChat object is available on your page. Use it to control the widget from your own code, for example to open it when someone clicks your own "Ask a question" button.

Method	What it does
open()	Opens the chat window.
close()	Closes the chat window (the launcher stays visible).
toggle()	Opens the window if it is closed, and vice versa.
show()	Shows the widget again after hide().
hide()	Hides the whole widget: the launcher and the chat window.
startNewConversation()	Starts a new, empty conversation in this browser. The previous conversation stays in your Inbox.
setContext(object)	Passes context to the assistant, see below.

After loading, the widget first fetches its settings. Until then open(), close(), toggle(), show() and hide() do nothing yet. If you never want the widget on a page, for example a checkout page, leave the code off that page.

Passing context

With setContext() you give the assistant information about the visitor's situation: which page they are on, which product they are looking at or, if they are logged in, their first name. The assistant uses this to answer more precisely ("I can see you're looking at our boiler servicing page…"). The context goes along with the visitor's next messages. Keep the following in mind:

• The object may be at most 8 KiB. If it is larger, the call throws an error and the previous context stays in place.
• Every call replaces the previous context entirely.
• The context is treated as untrusted input: the assistant reads it as information, not as instructions.
• Never include passwords, tokens, account numbers or other sensitive data. Anything you pass can be inspected by the visitor.

Example

Because the widget loads asynchronously, window.YarlaChat only exists once the script has run. So wait for the page's load event; if the object already exists, you can start straight away.

function setupChat() {
  window.YarlaChat.setContext({
    page: document.title,
    url: window.location.pathname,
    product: 'Boiler service plan',
    firstName: 'Sam' // only if the visitor is logged in
  });

  document.querySelector('#ask-button').addEventListener('click', function () {
    window.YarlaChat.open();
  });
}

if (window.YarlaChat) {
  setupChat();
} else {
  window.addEventListener('load', setupChat);
}

Limits

So nobody can run up your chat with a script, the chat has limits. One chat takes 60 messages an hour and one network 300. Your assistant gives at most 1,000 replies an hour and 5,000 a day over all chats on your website together; a busy site stays far below that. Past it, visitors see a message to try again later, or tomorrow for the daily limit.

Privacy and GDPR

What we store from a webchat conversation:

• the visitor's messages and the replies from the assistant or your team;
• the contact details the visitor gives during the conversation, such as name, email or phone;
• the context your website passes via setContext().

The widget and the chat page keep a random session number in the visitor's browser (localStorage), so the conversation carries on when they move to another page.

The visitor's IP address is not stored with the conversation. It does appear in the chat's technical access logs, for 90 days at most. You set how long conversations are kept under Keep conversations (days) in Settings → Business: 7 to 3,650 days, 365 by default. Only an Admin can change this. After that they are deleted automatically.

Because we process personal data on your behalf, the webchat belongs in your website's privacy policy. You can use the paragraph below as a starting point and adapt it to your situation:

Chat on our website
You can chat with our digital assistant on our website. The messages you send
and the contact details you give are processed by Yarla, which acts
as a data processor on our behalf. Replies in the chat are generated by
artificial intelligence; a member of our team can take over the conversation at
any time. We keep chat conversations for no longer than [retention period] and
use them only to answer your question and to improve our service. Your IP
address is not stored with the conversation and stays in technical logs for 90
days at most. You have the right to access, correct and erase your data; to
exercise these rights, contact us at [email address].

Related articles

• WhatsApp
• Inbox & analytics
• Technical settings
• Troubleshooting: WhatsApp and webchat