Install the chat window

The chat window is one small script. It loads without holding your page up, keeps its styles to itself so it cannot clash with yours, and answers from your knowledge. You need a channel first: it gives you the key and the snippet.

1. Get your snippet

1. Open Channels and choose your channel.
2. Open the Who and where tab and list your website under Websites allowed to show it, for example https://www.example.com. The chat window works only on listed sites.
3. Open the Install tab and copy the snippet.

2. Paste it into your site

Paste it just before the closing </body> tag, on every page where the chat window should appear:

<script src="https://api.askmychatty.com/widget/v1/widget.js" async></script>
<script>
  window.addEventListener('load', function () {
    Chatty.init({
      key: "pk_your_channel_key",
      api: "https://api.askmychatty.com",
      mode: "website"
    });
  });
</script>

Always copy the real snippet from your channel. It has your own key and address. The key is not a secret: it sits in your page and only works on the sites you listed.

For a single-page app, call Chatty.init once when the app starts, not on every route change.

What your customers can do

• Add an emoji from a small set beside the message box.
• Dictate by pressing the microphone button and speaking. The words appear in the box and the customer can fix them before sending. This uses the browser's own speech recognition, so it works in Chrome, Edge and Safari, and the button is hidden where the browser cannot do it. The browser listens, not Chatty, and Chatty stores no audio. In some browsers the browser's maker processes the speech, so say so in your privacy notice. If your website sends a Permissions-Policy header that switches the microphone off (microphone=()), the browser never asks the customer, so the button is hidden. To offer dictation, allow it for your own pages: Permissions-Policy: microphone=(self).
• Attach a picture, such as a screenshot, with the paperclip button, by pasting it into the box, or by dropping it on the window. This is available on paid plans, and only when the model that answers can read images; the button is hidden otherwise. A customer can send PNG, JPEG or WebP files up to 5 MB, with up to 3 pictures in one message. Chatty reads each picture when it is sent, and your team sees it in the Inbox with a short note on what it shows. Location data that a phone puts in a photo is removed before the picture is kept, and the file is deleted 30 days after the conversation is closed.
• Use the menu (the three dots at the top): minimise the chat, expand the view, download the transcript as a text file, open Previous conversations to read an earlier one again, or start a new conversation.
• See where an answer came from by opening Source under it. It lists the pages the answer used.
• Ask for a person at any time from the link under the box.

Options

Option	What it does
key	Your channel's key. Required.
api	Chatty's address. Already filled in by the snippet.
mode	"website" for anonymous visitors, "app" for signed-in customers.
userToken	For "app": the token your server signs, so Chatty knows who the customer is. See Identify your signed-in customers.
context	What the customer is looking at: { url, route, title, entity }. Chatty uses it to answer "where do I find this?".
open	Set to true to open the window straight away.

Control it from your code

Chatty is the only name the script adds to your page.

Call	What it does
Chatty.open() and Chatty.close()	Show or hide the window, for example from your own "Help" button.
Chatty.isOpen()	Returns true while the window is open.
Chatty.send("text")	Puts a message in the box, ready for the customer to send.
Chatty.setContext({ route, title })	Tells Chatty the customer moved to another page. Call it on every route change in an app.
Chatty.identify(token)	Gives Chatty a new user token, for example after sign-in. Pass null on sign-out.
Chatty.destroy()	Removes the chat window.

document.querySelector('#help-button').addEventListener('click', function () {
  Chatty.open();
});

Events

Listen with Chatty.on(name, function (payload) { ... }) and stop with Chatty.off.

Event	When	Payload
ready	The window is loaded.	none
open and close	The customer opens or closes it.	none
message	A message was sent or received.	{ role, text } where role is user, assistant or person
rating	The customer rated an answer.	{ messageId, rating }: 1 helpful, -1 not helpful, 0 cleared
handover	A conversation was handed to your team.	{ ticketNumber }
error	Something went wrong.	{ code }

Use them to send an event to your own analytics, or to open your support form when handover fires.

If it does not show

• Nothing appears: check that your website is listed on the channel exactly as in the address bar, with https:// and no trailing path. A page on any other address is refused.
• It says Chatty is not available: the channel is paused, or you have run out of credits. See Plan & usage.
• A content security policy blocks it: allow the script address under script-src and Chatty's address under connect-src.
• Several chat windows: call Chatty.init once. Calling it again replaces the window.