orka.Developers
Developers / Web SDK

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.Orka only exists once the script is loaded: set window.ORKA_SESSION before 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

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.