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",
});
name,email,thumbnail,signatureanduser_idare reserved keys. Every other key is a custom attribute.- Calls are merged: you can send
plannow andmrrlater. A key sent again replaces its previous value. - Values are stored as strings. An attribute cannot be removed from the SDK. Remove it from the dashboard or with the REST API.
- Calls are batched and sent after 3 seconds of silence. Data that did not change is not sent again.
- Called before the widget is ready, the data is kept and sent once it is.
- An invalid email is ignored, the rest of the call is kept.
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:
- Another
user_idthan the one of the visitor in this browser: a new visitor, with an empty chat. The previous conversation stays in your inbox. - The same
user_id: the same visitor and the same conversation, even when the email changes. - No
user_idsent: nothing changes, the visitor of the browser goes on.
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.