Connecting Nora to your systems

This page covers three ways to connect: Nora inside your own system, webhooks that pass questions on to you, and automatic uploads from inboxes and folders. Every company has its own Nora instance, so the addresses below start with yours.

Overview

Nora inside your system

Your system shows a Nora page in an iframe, typically in a side panel. People ask about the company’s procedures there and get answers with the source, without leaving the system. Everything in the panel is Nora’s page: we deploy changes on our side, nothing changes in your system.

• No sign-in. The panel is checked by the key in its URL and by the network address the branch connects from. Nobody signs in at the till.
• No names. Nora knows an employee only by an opaque ID from your system. It never receives a name.
• Everyone sees only their own questions. The history belongs to the branch and the employee; another employee can’t see it.
• Answers from the documents you choose. What the panel may read is set by the connection’s tags. Answers can include pictures.
• When it doesn’t know, it hands over. A button under each answer hands the question to a person, and the reply shows up right in the panel.

URL and parameters

We set up a connection for your system with its own key. You save the panel’s URL in your system’s settings, and your system adds the parameters itself:

<iframe
  src="https://<your-instance>/embed/<system>/<key>?lang=en&store=PRAGUE01&station=PRAGUE01-TILL2&user=u_8f3a2c&theme=light&accent=%231e6bd8&header=1"
  width="380" height="560" title="Nora">
</iframe>

Nora ignores unknown parameters. The panel is designed for 320–480 × 400–720 px and works in a sandboxed frame: it opens no dialogs and opens links from answers in a new browser window. Sources, pictures, earlier chats and handing over open inside the panel.

Messages with your system

The panel and your system talk with postMessage. Every message has the same shape, a type and data. The panel accepts messages only from its parent window, ignores unknown types and never puts a key, a question or an answer in a message.

// Messages from the Nora panel
window.addEventListener("message", (event) => {
  if (event.source !== noraFrame.contentWindow) return;
  const message = event.data; // { protocol, version: 1, type, payload }
  if (message.type === "unread") showBadge(message.payload.count);
  if (message.type === "error") showUnavailable(message.payload.message);
});

// The panel was shown: Nora marks answers as read and checks its status
noraFrame.contentWindow.postMessage(
  { protocol: "<protocol>", version: 1, type: "visibility", payload: { visible: true } },
  "https://<your-instance>"
);

You get the exact protocol name and message set with your key. We build an adapter for each system, so we fit what your system can do.

Panel security

• The key and the branches’ addresses together. A leaked panel URL doesn’t work outside your branches’ networks. We see every refused load in an overview and can allow it in one step.
• No cookies. The panel keeps a signed token, valid for 12 hours, in the page’s memory only. The IP address is checked on every request.
• The key doesn’t travel on. The panel sends Referrer-Policy: no-referrer and has a strict content security policy (CSP): scripts, styles and connections only from Nora.
• Replacing the key works at once. It ends the old URL and every open panel. The connection can be switched off at any time.
• Limits and deletion. By default 60 questions an hour per employee and 400 a day per connection. The history is deleted 4 months after its last message. Both can be changed.

Webhooks

When Nora doesn’t know the answer, or someone wants it checked, it hands the question to the right person. Instead of an e-mail, it can go to your own system: a helpdesk, a task system or your own service. You set the routes in Admin → Escalation routes. A route can serve selected departments only.

The body

Nora sends a POST request with a JSON body: who asked, the department, the question, Nora’s answer with its sources and the last few messages of the chat.

{
  "event": "escalation.raised",
  "severity": "normal",
  "company": "Your Company Ltd",
  "asker": { "id": 42, "name": "Jane Smith", "email": "jane.smith@yourcompany.com" },
  "department": { "id": 3, "name": "Store" },
  "question": "Can I give a discount on goods with damaged packaging?",
  "note": "The customer is waiting at the till.",
  "answer": {
    "outcome": "not_found",
    "text": "That isn’t in my documents, so I won’t make it up.",
    "sources": []
  },
  "conversation": [
    { "role": "user", "text": "Can I give a discount on goods with damaged packaging?" },
    { "role": "assistant", "text": "That isn’t in my documents, so I won’t make it up." }
  ],
  "reply": "Respond with JSON {\"answer\": \"...\"} to answer the asker right away, or with anything else to answer later in Nora.",
  "escalation_id": 1287
}

Checking the signature

When the route has a secret, check that the message came from your Nora before you process it. The signature is computed over the body exactly as it arrived, so check it before you parse the JSON.

<?php
$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, getenv('NORA_WEBHOOK_SECRET'));

if (!hash_equals($expected, $_SERVER['HTTP_X_NORA_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// Answer the person right away:
header('Content-Type: application/json');
echo json_encode(['answer' => 'Yes, up to 5% of the price. Note the reason at the till.']);

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post("/nora", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", process.env.NORA_WEBHOOK_SECRET).update(req.body).digest("hex");
  const received = req.get("X-Nora-Signature") || "";
  if (received.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  res.sendStatus(202); // received; answer later in Nora
});

import hashlib, hmac, os
from flask import Flask, abort, request

app = Flask(__name__)

@app.post("/nora")
def nora():
    body = request.get_data()
    expected = "sha256=" + hmac.new(os.environ["NORA_WEBHOOK_SECRET"].encode(), body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Nora-Signature", "")):
        abort(401)
    event = request.get_json()
    return "", 202  # received; answer later in Nora

Replies and retries

• Answer now or later. Return JSON {"answer": "…"} and the person gets the answer right away (up to 20,000 characters). Any other 2xx reply means “received”, and you can answer later in Nora.
• Retries. Nora waits 15 seconds for a reply. When a delivery fails, it tries again after 1, 5, 15 and 60 minutes. After the fifth failed attempt it marks the hand-over as not delivered, and you see that in Nora.
• No double processing. The X-Nora-Delivery header stays the same on retries. Use it to recognise a message you already have.
• The secret. It lives on your instance’s server, not in the admin screens. The Nora team sets and replaces it.

Documents from mailboxes and folders

Nora can pick up new documents by itself. You set the sources in Admin → Inbox checker; the Nora team stores the sign-in details on the server.

• Checks run at the times you set for each source, and whenever you start one by hand.
• Each item is imported only once. Afterwards Nora can move it to another folder; without one, messages are marked as read.
• What Nora finds in the documents waits for approval like any other upload.

Formats and limits

• Nora converts older formats (DOC, XLS, PPT, RTF and OpenDocument) when conversion is switched on for your instance. Otherwise it tells you how to save the file.
• A single file can be up to 2 GB. Up to 20 MB and 10 files at a time, Nora processes them right away; larger files and batches are saved first and processed in turn.

Security and data

• A separate instance for every company. Its own database, storage and settings. No database shared between customers.
• Hosted in the EU. The app runs in a data centre in Amsterdam and is reachable over HTTPS only.
• No training on your data. We don’t use your documents or questions to train models.
• Every connection has its own key. Replacing a key or a secret works at once and ends the old access.

Support

We set up connections together with you. Write to info@nora-labs.cz with the system you use, and we agree the steps, the keys and the testing.