orka.Developers
Developers / Web SDK

SDK methods

All methods live on window.Orka. With the npm package, the same methods are on the imported Orka object.

Method What it does
Orka.update(data) Sets the visitor identity and custom attributes
Orka.reset() Forgets the visitor and starts a new session
Orka.show(message?) Opens the chat, optionally pre-fills the input
Orka.hide() Closes the chat, the bubble stays
Orka.toggle() Opens the chat if closed, closes it if open
Orka.showWidget() Shows the bubble again after hideWidget()
Orka.hideWidget() Hides everything, bubble included
Orka.load() Shows the widget when ORKA_LOAD is false
Orka.destroy() Removes the widget from the page
Orka.on(event, fn) Subscribes to an event
Orka.off(event, fn?) Unsubscribes
Orka.isReady() true once the widget is set up
Orka.isOpen() true when the chat is open
Orka.isOnline() true when your team is available
Orka.getUnreadCount() Number of unread messages
Orka.track(name, data?) Adds an event to the contact timeline

update

Sets who the visitor is, and any custom attribute you want your team to see next to the conversation.

window.Orka.update({
  name: "Ada Lovelace",
  email: "[email protected]",
  thumbnail: "https://example.com/avatars/ada.png",
  plan: "pro",
  mrr: "49",
});

user_id (optional)

The id of the person in your own system: your user id, an account id, or a store domain for a Shopify app. Optional, and recommended when several accounts can be used in the same browser.

window.Orka.update({
  user_id: "4821",
  email: "[email protected]",
});

The widget keeps its session in the browser, not in your account. Without user_id, when another account logs in the same browser without reset(), the widget goes on with the previous visitor: the new person sees the previous conversation, and your replies are emailed to them. With user_id, Orka sees the change by itself:

It covers the cases where you cannot call reset() at the right time. For example, a Shopify app embedded in the admin of each store: every store opened in the same browser shares the storage of your app. Send user_id: shop (store-a.myshopify.com) and each store gets its own conversation.

user_id is never used to restore a conversation on another browser: that is what Session continuity does, with a signed email. Your team sees it in the details of the visitor.

reset

Forgets the current visitor: closes the chat, clears the local session, and starts a new anonymous visitor with a new conversation.

// When your user logs out
window.Orka.reset();

Call it on logout. Otherwise the next person using the same browser sees the previous conversation. The conversation itself is not deleted: your team keeps it in the inbox. Sending a user_id (see above) also protects the switches where reset() was not called.

show

Opens the chat. With a message, the input is pre-filled. The message is not sent, the visitor can edit it. Without one, the visitor's current draft is kept.

window.Orka.show();
window.Orka.show("Hello, I have a question about my invoice");

hide

Closes the chat. The bubble stays visible.

window.Orka.hide();

toggle

window.Orka.toggle();

hideWidget and showWidget

hideWidget() closes the chat and hides the bubble. The session stays alive: unread messages still update the tab title. showWidget() brings the bubble back.

// No chat bubble over the checkout
if (location.pathname.startsWith("/checkout")) {
  window.Orka.hideWidget();
} else {
  window.Orka.showWidget();
}

Use this pair to build your own launcher: hide the bubble for good, and call Orka.show() from your own button.

load

Only useful when window.ORKA_LOAD = false. Creates the widget. Call it once.

window.Orka.load();

destroy

Removes the widget from the page. To hide it for a while, prefer hideWidget().

window.Orka.destroy();

on and off

function onUnread(count) {
  document.querySelector("#support-badge").textContent = count || "";
}

window.Orka.on("unread:change", onUnread);
window.Orka.off("unread:change", onUnread); // without the function: removes every listener of the event
Event Argument Fired when
ready { visitor_id, conversation_id } The widget is displayed and the session exists. Fires once. A listener added later is called right away. conversation_id is null until the visitor writes.
session:change { visitor_id, conversation_id } The conversation changed after ready: the first message or contact form of the visitor created it, reset(), or Session continuity restored the one of the person.
open — The chat opens, whoever asked for it.
close — The chat closes.
unread:change count (number) The number of unread messages changes.
message:sent { id, content, created_at } The visitor sent a message.
message:received { id, content, author: { type, name }, created_at } A teammate, the AI agent or a bot replied. author.type is agent, ai or bot.
visitor:email email (string) The visitor typed their email in the chat.
availability:change is_online (boolean) Your team goes online or away.

ready fires once the widget is set up. When the project hides the widget (setting Show widget when you are offline turned off), ready fires all the same and the widget stays hidden: call showWidget() then show() from your own button. Calls to show(), hide(), toggle() and track() made before ready are kept and run at that moment. A reset() made before ready makes the widget start with a new session: what update() set before it is dropped, what update() sets after it is kept, and so is ORKA_SESSION. A listener that throws is logged in the console and does not break the widget.

Typical uses: send message:sent to your analytics, show your own unread badge, save the conversation_id of ready and session:change (null until the visitor writes) next to your user to open the conversation from your back office.

isReady, isOpen, isOnline, getUnreadCount

Synchronous. They return false, false, false and 0 until the ready event. With the stub of the snippet they only exist once the SDK is loaded: read them inside a ready listener, or guard the call.

window.Orka.on("ready", function () {
  if (!window.Orka.isOnline()) {
    showContactForm();
  }
});

track

Adds an event to the timeline of the contact, next to the pages they visited. Events need an identified visitor (an email). They are dropped otherwise.

window.Orka.track("Clicked upgrade", { from: "billing page", plan: "pro" });

Names are cut at 120 characters. data is flat: up to 20 keys with string, number or boolean values. A visitor can send 50 events every 10 minutes, the ones above are dropped.

Events sent from the browser are marked as such in the dashboard, since anyone can forge them. For events your team must trust ("paid", "churned"), use POST /events of the REST API from your back end.