Web SDK
The Web SDK is one script. It adds the chat bubble to your page, inside an iframe, and exposes a small JavaScript API on window.Orka.
Install the widget
Paste this before </head> on every page where the chat should appear. Your Project ID is in Settings → Developers.
<script type="text/javascript">
window.ORKA_APP_ID = "YOUR_PROJECT_ID";
(function (w, d) {
if (!w.Orka) {
var o = (w.Orka = { _q: [] });
["load", "update", "reset", "toggle", "show", "hide", "showWidget", "hideWidget", "destroy", "on", "off", "track"].forEach(function (m) {
o[m] = function () {
o._q.push([m, [].slice.call(arguments)]);
};
});
}
var s = d.createElement("script");
s.src = "https://widget.orka.chat/app.js";
s.async = 1;
d.getElementsByTagName("head")[0].appendChild(s);
})(window, document);
</script>
Reload the page: the bubble is there. The script loads asynchronously and never blocks your page.
The few lines around the script create a stub of window.Orka that queues your calls until the SDK is loaded, then replays them in order. You can call Orka.update(), Orka.on() and the rest from anywhere, at any time.
The shorter snippet of older installations, without the stub, keeps working. With it,
window.Orkaonly exists once the script is loaded: setwindow.ORKA_SESSIONbefore the snippet, and call the SDK from user actions.
Using React, Vue or another framework? Use the npm package instead.
Identify your logged-in users
If the visitor is logged in to your product, tell Orka who they are. Set ORKA_SESSION before the snippet:
<script type="text/javascript">
window.ORKA_SESSION = {
user_id: "4821",
name: "Ada Lovelace",
email: "[email protected]",
thumbnail: "https://example.com/avatars/ada.png",
// Anything else is a custom attribute, shown next to the conversation
plan: "pro",
mrr: "49",
company: "Analytical Engines Ltd",
};
</script>
| Key | Type | Notes |
|---|---|---|
user_id |
string | Optional. The id of the person in your system: another user_id in the same browser starts a new visitor. See SDK methods. |
name |
string | Display name. |
email |
string | Must be a valid email, otherwise it is ignored. Links the visitor to a contact. |
thumbnail |
string | Avatar URL (https). |
signature |
string | HMAC of the email computed by your server, see Identity verification. Never stored as an attribute. |
| any other key | string | Custom attribute. Values are stored as strings. Empty values are ignored. |
The same data can be sent or changed later with Orka.update().
Emails set from the browser can be forged by anyone who opens the console. Turn on identity verification if your team makes decisions based on the email it sees.
Options
Options are global variables. Set them before the snippet runs.
| Variable | Type | Default | Description |
|---|---|---|---|
ORKA_APP_ID |
string | — | Required. Your Project ID. |
ORKA_SESSION |
object | {} |
Visitor identity and custom attributes, see above. |
ORKA_LOAD |
boolean | true |
false loads the SDK without showing the widget. Call Orka.load() when ready. |
ORKA_LOCALE |
string | browser | Forces the widget language, see Language. |
Load the widget later
Useful to wait for a cookie banner, or to show the chat on some screens only.
<script type="text/javascript">
window.ORKA_APP_ID = "YOUR_PROJECT_ID";
window.ORKA_LOAD = false;
// …snippet…
</script>
// Later, for instance once the visitor accepted your cookie policy
window.Orka.load();
What the SDK does on its own
- Page tracking. Every page view is sent to Orka, single page applications included (History and Navigation APIs). Your team sees the last five pages of each visitor. URLs longer than 150 characters lose their query string.
- Unread messages. When a reply arrives while the tab is in the background, the tab title becomes
💬 1 - Your titleand a sound is played. The title goes back to normal when the visitor comes back with the chat open, or opens it. - Bots are ignored. Crawlers do not create visitors.
- Responsive. Under 700 px wide the chat opens full screen.
Troubleshooting
Add ?orka_debug=1 to the page URL, or run localStorage.setItem("orka_debug", "1") in the console, then reload. The SDK and the widget log what they do in the console.
| Symptom | Check |
|---|---|
| Nothing shows up | The Project ID is right. ORKA_LOAD is not false. Your Content Security Policy allows Orka, see Domains to allow. |
No orka config found in the console |
ORKA_APP_ID was not set before the script ran. |
window.Orka is undefined |
You use the older snippet, without the stub that queues calls. Replace it with the one above. |
| The widget is set up but never shows up | The project setting Show widget when you are offline is turned off: the widget stays hidden. ready fires all the same: call showWidget() then show() from your own button. |
| The email does not show in the dashboard | The email is not valid, or you looked too early: update() calls are batched and sent after 3 seconds. |