JavaScript SDK: control the chat widget from your page

The embed script adds window.IntoChat to your page. With it, your own JavaScript can open and close the chat bubble, tell the agent who the signed-in visitor is, switch the widget language and react to what happens in the chat.

Before you start

The SDK comes with the script tag. There is nothing else to install:

<script src="https://www.intochat.ai/api/embed.js" data-chatbot-id="YOUR_AGENT_ID"></script>
<script>
  window.IntoChat.on("reply", function (event) {
    console.log("The agent replied:", event.text);
  });
</script>

window.IntoChat exists as soon as the script has run, before the chat window has loaded. Calls you make early wait until the launcher and the chat window are ready, so you can call any method right after the snippet.

The SDK only works with the chat bubble that the script adds. An inline iframe or a share link has no script on the page to talk to.

Methods

open, close and toggle

<button type="button" onclick="IntoChat.open()">Chat with us</button>

Opening the chat this way counts as the visitor using the chat, so the welcome pop-up and auto-open don't appear afterwards during that visit.

IntoChat.open() also works for visitors who don't see the launcher because of Show the chat to a share of visitors. The rollout only hides the launcher and its invitations, so a "Chat with us" button on your page still opens the chat for everyone. For those visitors the chat window loads the first time it opens. With Center Stage, open() opens the centred window, and close() closes it like Esc does.

identify

IntoChat.identify({
  userId: "4711",                  // required: the user's id on your site
  userHash: "9f2c…",               // required: computed on your server
  name: "Ada Lovelace",            // optional
  email: "ada@example.com",        // optional
  metadata: { plan: "pro", seats: 3 } // optional
});

identify is how identity verification works. userHash is the HMAC-SHA256 of userId, keyed with your agent's identity secret and computed on your server, so nobody can claim to be another user. Without a valid userHash the visitor simply stays unverified.

identify returns true when the input passes these rules, and false (with a warning in the browser console) when it doesn't. Whether the signature is valid is only checked by intoCHAT's server, when the visitor sends a message.

Call identify on every page load while the visitor is signed in. Identifying a different user than the last one on this browser starts a new chat automatically, so one person never sees another person's conversation. A visitor who chatted before signing in keeps that chat.

reset

IntoChat.reset();

Call it when the visitor signs out. It forgets the identity and starts a new, empty chat. The list of earlier chats on this browser is cleared too; the conversations themselves stay in your dashboard.

setLanguage

IntoChat.setLanguage("de");

Switches the widget's own words (buttons, labels, notices) to English (en), German (de), French (fr), Italian (it) or Spanish (es). A region code such as de-CH counts as de. Any other code returns false. It takes the place of your page's lang attribute, so it has no effect when you picked a fixed widget language on the Appearance tab. It doesn't change your welcome messages or the language the agent replies in.

on and off

function onReply(event) {
  analytics.track("chat_reply", { agent: event.chatbotId });
}

IntoChat.on("reply", onReply);
// later
IntoChat.off("reply", onReply);

on also returns a function that removes the listener. A listener that throws an error doesn't stop the others; the error is logged to the console.

Events

Every callback receives one object. It always has chatbotId, the agent the event came from.

IntoChat.on("live_chat", function (event) {
  if (event.status === "active") document.title = "A team member is chatting with you";
});

Events don't fire in a temporary chat for lead and booking, because those aren't offered there. Contact details a visitor types into the chat, instead of using the form, don't fire lead.

Call it before the script loads

If your code may run before the snippet, push calls to window.IntoChatQueue. Each entry is the method name followed by its arguments:

<script>
  window.IntoChatQueue = window.IntoChatQueue || [];
  window.IntoChatQueue.push(["identify", { userId: "4711", userHash: "9f2c…" }]);
  window.IntoChatQueue.push(["on", "lead", function () { console.log("New lead"); }]);
</script>
<script src="https://www.intochat.ai/api/embed.js" data-chatbot-id="YOUR_AGENT_ID"></script>

The script applies the queue when it loads. Later pushes run straight away.

Several agents on one page

With snippets for several agents on one page, every call applies to all of their launchers, and each event's chatbotId says which agent it came from. Each agent has its own identity secret, so a userHash only verifies the visitor for the agent whose secret signed it.

How it relates to IntoChatActions

window.IntoChatActions is separate and works exactly as before: it runs client-side actions when the agent calls them. IntoChat is for your own code to drive the widget. The two can be used together. When the visitor is verified, a client-side action handler also receives them as context.user:

IntoChatActions.register("Get_cart", async function (args, context) {
  // context.user: { id, name, email, metadata }, only for a verified visitor
  return { items: window.myStore.cart.items };
});

Security

The chat window runs on intoCHAT's domain. The script on your page exchanges messages only with its own chat window, and only while that window shows intoCHAT: other frames on your page can't receive the visitor's identity, send fake events or trigger actions. Events carry what the visitor typed and the agent's replies, so treat them like any other visitor data on your page.