Guide til chatwidget

01Dit chat-ID

Ét id identificerer din chatbot. Du finder det i kodestykket under Kode til dit websted på fanen Hjem på din chatside, ved siden af Kopiér-knappen.

Det identificerer din chatbot og intet andet: ingen konto, ingen API-nøgle, intet login nogen steder på dit websted.

Må gerne offentliggøres. Det ligger i din sides HTML, hvor alle kan læse det. Det eneste, det kan, er at stille din chatbot et spørgsmål — og kun på de websteder, du har tilladt.

02Sæt den på dit websted

Tilføj begge linjer på en vilkårlig side, lige før det afsluttende body-tag.

<script src="https://www.obbo.me/obbochat.js" async></script>
<div data-obbo-chat="YOUR_CHAT_ID"></div>

Scriptet indlæses én gang pr. side og sætter en chatboble i hjørnet. Læg det i dit websteds skabelon, så har hver side den.

Tillad dit websted først.Din chatbot svarer kun på de websites, der står under fanen Navn og velkomst på chatsiden i dit Brand Center – til at begynde med dit Brand Centers eget website. Tilføj alle andre websites, der viser chatten, fx en testkopi. På andre websites afslår den høfligt, og chatsiden viser, hvilket website der prøvede.

Kommer koden efter sideindlæsningen? Scriptet leder efter den én gang, når siden er klar. Hvis dit websted indsætter chatten senere — en single-page-app, en tag manager, et samtykkebanner — så kald ObboChat.mount() bagefter.

03Sådan ser den ud

Vælg udseendet under Udseende i din chatbots indstillinger, og kopiér koden: den skriver disse attributter og stilværdier for dig. Kun chat-id’et er påkrævet, og resten kan du rette i hånden.

<script src="https://www.obbo.me/obbochat.js" async></script>
<div data-obbo-chat="YOUR_CHAT_ID"
     data-obbo-title="Acme Help"
     data-obbo-position="left"
     data-obbo-launcher="Ask us a question"
     style="--obbo-accent: #0f766e; --obbo-accent-text: #ecfdf5; --obbo-bottom: 96px"></div>

Har du ændret udseendet? Kopiér koden igen. Udseendet ligger i koden, så dit website beholder det gamle, indtil du erstatter den.

Farver

Farvetabellen sætter seks farver: en baggrund og en tekstfarve for dit brand, for chatbottens svar og for chatvinduet. Dit brand dækker alt, hvad en besøgende trykker på eller sender: chatknappen, Send-knappen, de foreslåede spørgsmål og deres egne beskeder. Chatvinduet dækker titlen, skrivefeltet, links og småt, og linjerne er en svag udgave af teksten. Tryk på et felt for at åbne farvevælgeren. Match mit website sætter din brandfarve og viser det, den fandt på din forside, som logoets farve, øverst i hver farvevælger.

Start fra Lys eller Mørk sætter alle farver, der står på Automatisk. Automatisk tekst er hvid eller sort, alt efter hvad der læses bedst på baggrunden. Hvert tekstfelt viser, hvor let det er at læse, og når en farve er svær at læse, tilbyder vælgeren Automatisk igen.

Egne stilarter

Hver farve, størrelse og afstand i widgetten læser sin egen stilværdi. Sæt en hvilken som helst af dem på chattens div eller i dit eget stylesheet, og dine går forud for dem i koden.

[data-obbo-chat] {
  --obbo-accent: #0f766e;
  --obbo-assistant-text: #1f2937;
  --obbo-font: "Inter", sans-serif;
  --obbo-radius: 0;
  --obbo-bottom: 96px;
}

Hvad der ligger fast

Panelets egne ord — hilsenen, send-knappen, bedømmelsen — er på engelsk i dag, og opbygningen er vores. Vil du have din egen kode hele vejen, så byg din egen brugerflade med den headless motor nedenfor — samme chatbot, din HTML og din CSS.

Svar har ét sprog. Din chatbot svarer på dit indholdscenters sprog, uanset hvilket sprog en besøgende skriver på: din virksomhed med sine egne ord frem for en oversættelse af dem.

04Byg din egen grænseflade

Boblen er valgfri. Samme script udstiller en headless motor: send spørgsmål, abonnér på samtalens tilstand, og vis den, som dit websted gør.

<script src="https://www.obbo.me/obbochat.js" async></script>
<script>
  addEventListener('load', function () {
    var chat = ObboChat.createChat({ widgetId: 'YOUR_CHAT_ID' });
    chat.subscribe(function (state) {
      // state.turns is the conversation; state.busy while answering.
    });
    chat.ask('What do you sell?');
  });
</script>

Én motor pr. chatbot. Alt det boblen gør — samtalen indtil nu, et foto til et prisoverslag, en indlogget besøgende — kommer til dig i den tilstand, du abonnerer på, så dit eget panel går ikke glip af noget.

05Prisoverslag

Din chatbot kan give en pris inde i samtalen, ud fra de spørgsmål og priser du opsætter.

Har din chatbot en prisberegner, bliver en besøgende, der spørger, hvad noget koster, bedt om at beskrive opgaven med få ord eller tilføje et foto. Fotoet læses op imod dine egne spørgsmål i beregneren – størrelsesintervallet, et antal, et omtrentligt spænd for en målt mængde – og det, der afgøres, vises for den besøgende til bekræftelse eller rettelse, før det tæller. Intet prissættes ud fra et foto alene: et tal fastsættes altid af den besøgende, og deres ord vejer tungere end billedet.

Hvad den besøgende får

Et specificeret prisinterval i din valuta med en linje for hver del af opgaven – eller, hvis du vælger det, ét beløb og hvad det bygger på – og din egen tekst under hvert overslag. Det er et overslag og aldrig et tilbud: beregningen bygger på dine priser, og det, dine priser ikke dækker, står som prissat separat.

Hvad du selv opsætter

Fem korte trin under Pristilbud på din chatside, og intet i kode:

1. Scan mit websted: dine priser, ekstra gebyrer og vilkår læses fra de sider, din chatbot allerede kender, og de spørgsmål, der ændrer beløbet, foreslås for dig.
2. Prisliste: alle priser i ét ark. Ret en celle, eller download arket, ret det i Excel eller Google Sheets, og upload det igen. Priser, der er regnet ud for dig, er markeret som Skøn, indtil du har tjekket dem.
3. Dine overslag: et eksempel på en opgave præcis, som en besøgende ser den. Ret, fjern eller tilføj en hvilken som helst linje, og vælg, hvad besøgende ser: hver linje eller ét beløb og hvad det bygger på.
4. Spørgsmål: det, en besøgende bliver spurgt om, i din rækkefølge: vælg én, vælg flere, et tal, en dato, ja eller nej, ord eller et foto. Hvert spørgsmål viser, hvad svaret gør ved beløbet.
5. Gebyrer og grænser: ekstra gebyrer og grænser, teksten under hvert overslag, hvor store opgaver du hellere selv vil give pris på, og kontakten, der slår overslag til.

Tallene er stadig dine. Hver pris, der er regnet ud for dig, er markeret som Skøn i din Prisliste, og hvert overslag under Kundesamtaler viser, hvor meget der kom fra typiske takster frem for dine egne priser. Et interval, du ikke ville stå inde for, er synligt i stedet for skjult.

Hvor overslagene lander

Hvert overslag vises under Kundesamtaler med de svar, det blev lavet ud fra – hvert markeret som læst fra den besøgendes ord, fra deres foto eller slået op – og med kontaktoplysninger, når de har efterladt dem. Du kan også få hvert færdigt overslag tilsendt på e-mail.

Fotos opbevares i 90 dage og kan slettes der, ét ad gangen. Hvert overslag noterer også, hvad et foto viste, som ingen spørgsmål spurgte om.

Intet at bygge. Både boblen og den headless motor har prisoverslaget med — din egen brugerflade får hvert overslag i samtalens tilstand — så der er ikke noget at bygge her.

Et “Få et tilbud”-link på dit website

Enhver knap eller ethvert link på en side med din chat kan åbne den direkte i et tilbud. Indsæt dette, hvor du vil have det, og giv det samme udseende som resten af dit website; området Hent koden på din chatside har det klar til at kopiere.

<a href="#get-estimate" data-obbo-estimate>Get an estimate</a>

Linket virker også alle andre steder fra — en anden side, en e-mail, en annonce eller et opslag på sociale medier. Tilføj #get-estimate til sidst i adressen på en side med din chat, så åbner chatten i et tilbud, når siden indlæses.

Din egen knap. Sæt data-obbo-estimate på et hvilket som helst element, eller kald ObboChat.startEstimate() fra din egen kode. En besøgende med et igangværende tilbud vender tilbage til det i stedet for at starte forfra, og en chatbot uden aktiv tilbudsberegner åbner bare.

06Fortæl chatten, hvem der er logget ind

Din server indestår for, hvem den besøgende er, og din chatbot svarer med personens egne oplysninger for øje.

Hvis besøgende logger ind på din side, kan chatten svare på spørgsmål om deres egen konto – »hvor er min ordre?« – ud fra de oplysninger, din side vælger at dele. Slå Indloggede besøgende til på chatsiden i dit Brand Center for at få din besøgsnøgle.

Din besøgendenøgle er en serverhemmelighed.Din besøgsnøgle hører kun hjemme på din server. Læg den aldrig i en webside, en app eller et kodearkiv. Hvis den slipper ud, så udskift den på chatsiden, og vælg at stoppe den gamle nøgle med det samme.

Sådan hænger det sammen

Hvad tokenet indeholder

Signér det som en JWT med HS256 med din besøgsnøgle som hemmelighed. Ethvert JWT-bibliotek kan det. I Node:

// Your server (Node + Express). npm install jsonwebtoken
import jwt from 'jsonwebtoken';

app.post('/chat-token', (req, res) => {
  res.set('Cache-Control', 'no-store');
  const user = req.user; // your own sign-in
  if (!user) return res.json({ token: null });
  const token = jwt.sign(
    {
      sub: String(user.id),
      name: user.firstName,
      account: { orders: recentOrdersFor(user) }, // whatever you choose to share
    },
    OBBO_VISITOR_KEY, // from your server's secret settings
    { algorithm: 'HS256', expiresIn: '10m' },
  );
  res.json({ token });
});

I Python:

# Your server (Python + Flask). pip install PyJWT
import time
import jwt

@app.post("/chat-token")
def chat_token():
    user = current_user()  # your own sign-in
    if user is None:
        return {"token": None}
    now = int(time.time())
    claims = {
        "sub": str(user.id),
        "name": user.first_name,
        "account": {"orders": recent_orders_for(user)},  # whatever you choose to share
        "iat": now,
        "exp": now + 600,
    }
    return {"token": jwt.encode(claims, OBBO_VISITOR_KEY, algorithm="HS256")}

På din side

Giv chatten en funktion, der henter et token fra din server. Chatten kalder den kun, når der stilles et spørgsmål, og den ikke har et gyldigt token – aldrig bare fordi en side blev indlæst.

<script>
  addEventListener('load', function () {
    ObboChat.identify(async function () {
      const res = await fetch('/chat-token', { method: 'POST' });
      return (await res.json()).token;
    });
  });
  // When the visitor signs out: ObboChat.identify(null);
</script>

Hvis din side logger besøgende ind med en cookie, klarer én attribut det samme: chatten sender en POST til den adresse på din egen side. Lad ruten kun acceptere POST, tjekke dit eget login, ikke sende CORS-headere og svare med et tomt token, når ingen er logget ind.

<script src="https://www.obbo.me/obbochat.js" async></script>
<div data-obbo-chat="YOUR_CHAT_ID" data-obbo-identity-url="/chat-token"></div>

Når en besøgende logger ud, så kald ObboChat.identify(null). Chatten rydder deres samtale med det samme, så den næste person ved samme computer starter forfra.

Tjek, at det virker

Hvert chatsvar fortæller din side, hvad der skete med tokenet: visitor.status er signed_in, anonymous eller refused, og et afvist token har en årsag med. Chatsiden i dit Brand Center viser også det seneste accepterede og afviste token.

Prøv det, før du går live. På fanen Prøv den på din chatside vælger du „en indlogget kunde“, skriver et navn og de kontooplysninger, dit websted ville sende, og testchatten spørger med et rigtigt token signeret med din nøgle — kontrolleret præcis som en besøgendes.

Hvad vi gemmer.Kontooplysningerne sendes til vores AI-udbyder for at skrive hvert svar. De gemmes ikke sammen med dine samtaler eller i vores logs, men et svar kan gentage dem.

07Svar på spørgsmål om en konto

„Hvor er min ordre?“ — besvaret fra dine egne systemer.

Din chat kan svare på spørgsmål om den besøgendes egen konto — hvor deres ordre er, om en betaling gik igennem — ved at spørge ét endepunkt på din egen server. Vi forbinder aldrig til dine systemer og har ingen nøgle til dem: vi sender en beskrivelse af, hvad ét spørgsmål kræver, og du bestemmer, hvad der returneres.

1. Slå indloggede besøgende til (afsnit 6). Din chatbot kan kun spørge om en person, dit eget websted har navngivet.
2. Byg ét endepunkt på din server. Et GET returnerer dit katalog; et POST svarer på én forespørgsel hentet fra det.
3. På fanen Navn og velkomst på din chatside åbner du For udviklere, og under Spørgsmål om kontoen indsætter du adressen i Dit dataendepunkt og trykker Forbind adresse – så læser den med det samme, hvad den kan svare på.
4. Tryk Slå til. Derefter viser panelet, hvor mange opslag der er lavet, hvor lang tid dit endepunkt tager, og det seneste problem i almindelige ord.

Afgræns hvert svar til tokenet.Afgræns hvert svar til sub i det besøgstoken, du har verificeret med din egen nøgle, og ignorér enhver identitet, der måtte fremgå af resten af forespørgslen. Det er det, der gør det umuligt at vise én besøgende en andens data.

Beskriv dine data

Et GET til dit endepunkt returnerer dit katalog: de typer data, du kan returnere, og felterne i hver. Derfor skal du aldrig liste de spørgsmål, dine besøgende kunne stille — chatten matcher selv spørgsmålet mod dit katalog, når det stilles.

// GET https://your-site.com/obbo-chat/data
// Describe the data you have. You never list the questions your visitors
// might ask — the chat matches a question to one of these itself.
{
  "version": 1,
  "resources": [{
    "name": "orders",
    "title": "Orders",
    "description": "Orders on this customer's account, newest first.",
    "scope": "visitor",
    "fields": [
      {"name": "status", "type": "string", "description": "Where it stands.",
       "values": ["paid", "shipped", "delivered"]},
      {"name": "ship_date", "type": "date", "description": "When it shipped."},
      {"name": "tracking", "type": "string", "description": "Carrier tracking link."}
    ],
    "filters": [{"field": "status", "ops": ["eq"]}],
    "default_request": {"fields": ["status", "ship_date", "tracking"], "limit": 10},
    "max_limit": 25
  }]
}

Besvar én forespørgsel

Et POST bærer én struktureret forespørgsel hentet fra dit katalog og det besøgendetoken, din egen server signerede. Alt i den kommer fra dit katalog — en forespørgsel, dit katalog ikke beskriver, bliver aldrig sendt.

// POST https://your-site.com/obbo-chat/data
// "Where is my order?" becomes this. Operators are only:
// eq, neq, gte, lte, contains, in. There is no SQL and no free text.
{
  "version": 1,
  "visitor_token": "<the token YOUR server signed for this visitor>",
  "request": {
    "resource": "orders",
    "filters": [{"field": "status", "op": "eq", "value": "shipped"}],
    "fields": ["status", "ship_date", "tracking"],
    "limit": 10
  },
  "request_id": "chat_9f2c41b8"
}

Svar med netop den del og intet andet. Hold svaret under 64 KB.

// Answer with that slice, and nothing else.
{
  "version": 1,
  "resource": "orders",
  "items": [
    {"status": "shipped", "ship_date": "2026-09-14",
     "tracking": "https://carrier.example/track/4471"}
  ],
  "item_count": 1,
  "truncated": false
}

Tjek af en forespørgsel

To kontroller, i denne rækkefølge: at forespørgslen er signeret med din besøgendenøgle, og hvem den handler om. Begge bruger den samme nøgle, du allerede signerer besøgendetokens med — der er intet nyt at installere. Begge kald er signerede, GET’et over en tom body.

X-Chat-Data-Signature: t=1760000000,v1=4b1f…9c   // hex, 64 chars
X-Chat-Key-Version: 3

signature = HMAC_SHA256(
  your_visitor_key,
  "<t>.<METHOD> <path and query>." + <raw request body>
).hex()

// GET  "1760000000.GET /obbo-chat/data."            + ""
// POST "1760000000.POST /obbo-chat/data."           + the bytes that arrived

const crypto = require('crypto');
const KEY = process.env.OBBO_VISITOR_KEY;   // the key from your chat page

// 1. Is this really from the chat service? The signature covers the method,
//    the path as sent, and the RAW body — so check before you parse.
function fromObbo(req, rawBody) {
  const fields = Object.fromEntries(
    (req.get('X-Chat-Data-Signature') || '').split(',').map(p => p.trim().split('='))
  );
  const t = Number(fields.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const mine = crypto.createHmac('sha256', KEY)
    .update(`${t}.${req.method} ${req.originalUrl}.`)
    .update(rawBody)
    .digest('hex');
  const a = Buffer.from(mine), b = Buffer.from(fields.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// 2. Who is it about? From the token YOU signed — never from the body.
function visitorId(token) {
  const [head, payload, sig] = String(token || '').split('.');
  if (!head || !payload || !sig) return null;
  const mine = crypto.createHmac('sha256', KEY)
    .update(`${head}.${payload}`).digest('base64url');
  if (mine !== sig) return null;
  const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
  if (!claims.exp || Date.now() / 1000 > claims.exp) return null;
  return claims.sub;
}

// Your catalog. Signed too, over an empty body.
app.get('/obbo-chat/data', (req, res) => {
  if (!fromObbo(req, '')) return res.sendStatus(403);
  res.set('Cache-Control', 'no-store').json(CATALOG);
});

// One request. express.text keeps the raw bytes the signature covers;
// express.json would re-encode them and the check would fail.
app.post('/obbo-chat/data', express.text({ type: '*/*' }), async (req, res) => {
  if (!fromObbo(req, req.body)) return res.sendStatus(403);
  const body = JSON.parse(req.body);
  const customer = visitorId(body.visitor_token);
  if (!customer) return res.sendStatus(403);

  const asked = body.request || {};
  if (asked.resource !== 'orders') return res.sendStatus(422);   // not mine to answer

  // Scope EVERY query by `customer`. Ignore any id in the request body.
  const rows = await db.orders.findAll({
    where: { customer_id: customer, ...where(asked.filters) },
    limit: Math.min(asked.limit || 10, 25),
  });

  // Return the fields that were asked for, and never a field you did not
  // declare: everything you send is read out to the visitor.
  const items = rows.map(row => pick(row, asked.fields));
  res.set('Cache-Control', 'no-store')
     .json({ version: 1, resource: 'orders', items, item_count: items.length });
});

Hvad du skal svare

Din statuskode er det, din chatside rapporterer til dig, så brug dem præcis sådan:

Fem fejl i træk, og vi holder op med at spørge. Opslag holder pause i fem minutter, og din chatside siger det med den seneste årsag. De starter igen af sig selv; et opslag, der lykkes, nulstiller tælleren, mens Læs hvad det kan svare på kun tester endepunktet. Din chatbot svarer på alt andet hele tiden.

Langsom tæller som slukket.En forespørgsel besvares inden for 2,5 sekunder, ellers svarer chatten uden den — den besøgendes spørgsmål fejler aldrig, fordi dit endepunkt var langsomt.

08Grænser og tider

Alt, kontrakten sætter grænser for, samlet på ét sted.

09Content Security Policy

Sætter dit websted en CSP, så tillad disse to. Der skal ikke mere til: ingen rammer, ingen skrifttyper, ingen billeder fra os.

Stilværdierne i koden sættes af widgettens script, så en politik, der blokerer inline-stilarter, bevarer dit udseende. Browseren kan stadig skrive en advarsel om style-attributten; den er harmløs.

Hvem bliver identificeret.Gæster identificeres aldrig: en tilfældig sessionsnøgle i deres browser samler én besøgendes spørgsmål i en samtale på dit dashboard, og det er alt, den gør. Indloggede besøgende identificeres kun ved det ID og navn, din side sender.

10Når den ikke virker

11Spørgsmål?

Giv os sideadressen, dit chat-id og det spørgsmål du stillede, så ser vi på præcis det, du ser på. Vi læser alt, der sendes til hello@obbo.me

Om Obbo-chatbotten