Link a product to the help desk

What you get

A round Help chat bubble on your product's pages. Your users ask how to do things and an AI (Claude) answers only from your user guide; they can report problems, which become GitHub issues for the developer, and see the answers to their reports. The help desk at https://helpdesk-test.cirms.ph runs the chat, keeps the conversations and has the owner's dashboard. Your product only tells it who is asking, with a short signed token. No passwords or user accounts are shared.

Two steps: 1. link your product with the linking password (the help desk's owner gives it to you) — you get your secret at once; 2. add a token endpoint and the widget to your product.

Claude Code: ask your user for the linking password (never guess it, never save it anywhere), show them the details you are about to send (step 1) and send them when they agree. Never put the secret in code or in the repository: it goes in the product's .env (or its usual secret store). If your project's rules say not to write .env, give the value to your user to put there.

1. Link your product

Send your product's details with the linking password. The product is linked at once and the answer holds its secret — shown only this once: put it in .env as HELPDESK_SECRET right away.

POST https://helpdesk-test.cirms.ph/api/connect
Content-Type: application/json

{
  "password": "the linking password",
  "app_id": "stock-counter",
  "name": "Stock Counter",
  "description": "a phone app for counting stock in warehouses, with an admin page",
  "guide_url": "https://stock.example.com/help/guide.html",
  "guide_name": "user guide",
  "support_name": "Stock Counter support",
  "instructions": "Users are warehouse staff (role counter) and managers (role manager)...",
  "tenant_label": "Company",
  "timezone": "Asia/Manila",
  "github_repo": "acme/stock-counter",
  "origins": ["https://stock.example.com"],
  "contact": "Ana, ana@example.com"
}

→ 201 {"app": "stock-counter", "helpdesk_url": "https://helpdesk-test.cirms.ph", "secret": "…64 characters…", "replaced": false, "next": "…"}
   400 {"detail": "Please check these fields", "errors": {"guide_url": "…"}}
   401 wrong linking password      403 linking is switched off on this help desk

Linking again — to change the details (a new guide address, better instructions…) or when the secret was lost: send the same request with "replace": true. The details are updated and there is a new secret (the old one stops working at once), so update HELPDESK_SECRET too. Without "replace", an id that is already linked is refused — never replace an id that isn't your product's.

2. Add it to your product

Settings (.env, never in code)

HELPDESK_URL=https://helpdesk-test.cirms.ph
HELPDESK_APP=stock-counter          # your app_id
HELPDESK_SECRET=                    # from step 1; blank = no Help bubble

Add these lines (blank) to your .env.example. With HELPDESK_URL or HELPDESK_SECRET blank the product must work exactly as before, just without the bubble.

A token endpoint (your server, signed-in users only)

For example GET /api/helpdesk-token → {"url": "https://helpdesk-test.cirms.ph", "token": "…", "expires": 1760000000}, or {"url": null} when not set up. It needs the user's normal sign-in; anyone else gets your usual 401. The token:

token = "v1." + base64url(JSON(claims)) + "." + base64url(HMAC-SHA256(HELPDESK_SECRET, "v1." + base64url(JSON(claims))))
        (base64url without "=" padding; the HMAC is over the exact string "v1.<claims>")

A token the help desk refuses gets 401 {"detail", "hint"}: hint says what exactly is wrong (no iat, the signature, the tenant's format…). Check it with POST https://helpdesk-test.cirms.ph/api/status {"token": "…"}.

PHP:

$b64 = fn(string $raw) => rtrim(strtr(base64_encode($raw), '+/', '-_'), '=');
$body = 'v1.' . $b64(json_encode($claims, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));
$token = $body . '.' . $b64(hash_hmac('sha256', $body, getenv('HELPDESK_SECRET'), true));

Node.js:

const crypto = require("crypto");
const b64 = (b) => Buffer.from(b).toString("base64url");
const body = "v1." + b64(JSON.stringify(claims));
const token = body + "." + crypto.createHmac("sha256", process.env.HELPDESK_SECRET).update(body).digest("base64url");

Python:

import base64, hashlib, hmac, json, os
b64 = lambda b: base64.urlsafe_b64encode(b).rstrip(b"=").decode()
body = "v1." + b64(json.dumps(claims, ensure_ascii=False).encode())
token = body + "." + b64(hmac.new(os.environ["HELPDESK_SECRET"].encode(), body.encode(), hashlib.sha256).digest())

The widget (on the pages where users need help, once signed in)

// after sign-in:
const first = await (await fetch("/api/helpdesk-token")).json();   // your endpoint (with your usual auth)
if (first.url) {
  await new Promise((ok, fail) => { const s = document.createElement("script");
    s.src = first.url + "/widget.js"; s.onload = ok; s.onerror = fail; document.head.append(s); });
  let pending = first.token;
  window.HelpdeskWidget.mount({
    server: first.url,
    token: async () => { if (pending) { const t = pending; pending = ""; return t; }
                         return (await (await fetch("/api/helpdesk-token")).json()).token; },
    lang: "en",                            // or "zh" (简体中文) — the widget's own texts come in both
    text: {                                // optional, in the page's language
      subtitle: "Ask how to use Stock Counter, or report a problem.",
      intro: "Hi! Ask how to do something. Answers come from an AI assistant: check before changing anything important.",
      support: "Stock Counter support",
      historyGroup: "Questions asked at this site in the last 90 days.",
      historyTenant: "Questions asked anywhere in your company in the last 90 days.",
    },
    roleNames: { counter: "counter", manager: "warehouse manager" },
    // screen: false,                      // never send what's on the page (turns "Show me" off)
    // pageData: false,                    // the person can never share the page's data (turns "Share this page" off)
  });
}
// on sign-out:
if (window.HelpdeskWidget) window.HelpdeskWidget.forget();

Colours: set --hdw-brand, --hdw-brand-dark, --hdw-brand-soft, --hdw-ink, --hdw-ink-2, --hdw-line, --hdw-bg, --hdw-card, --hdw-danger, --hdw-font on .hdw-root to match your design. To keep the bubble above a fixed bar at the bottom of your page, set --hd-lift: 76px (the bar's height) on body while the bar shows. If your pages have a Content-Security-Policy, allow https://helpdesk-test.cirms.ph in script-src, style-src and connect-src.

Show me on the screen (nothing to do; markers optional)

With each question the widget sends what can be clicked or typed in on the page: kind and visible label only, never what is typed in fields. When an answer says where to click, a Show me on the screen button highlights each step. To make it dependable, add data-help="<name>" to key controls (letters, digits, _ . -, e.g. data-help="new-item"): they are found again after the page changes, also inside a closed menu. Add data-help-skip to parts whose link texts are customers' data (a list of names…): nothing inside is sent.

Share this page (nothing to do; one marker for private parts)

When an answer depends on the user's own data, the AI asks to see the page and a Share this page button appears. Only when the user presses it does the widget send the text the page shows (fields' values and tables too), with that one question; it is not kept. Passwords, card and one-time-code fields are never read, and long numbers are hidden. Add data-help-private to anything that must never reach the AI (salaries, private notes…), and data-help-skip parts are left out too. The help desk never needs an API into your data for this.

Tests

For the token endpoint: it needs sign-in; the signature checks out with the secret (compute the HMAC in the test); the claims are right for each kind of user (tenant, group, whole, role, context); blank settings give {"url": null}. Never call the real help desk from tests.

Then restart your product: the Help bubble appears for signed-in users.

Good to know

• The guide is the AI's only source. A question it can't answer ends with "Report this problem" — the answer then belongs in your guide. Whenever your pages change, update the guide.
• Users mark answers Resolved / Not resolved; the owner's dashboard groups similar questions and lists the unresolved ones, to improve the guide and the product.
• Reports become issues in github_repo. Answer on the issue with a comment starting with Reply: (by the repo's owner, a member or a collaborator) — users see it; other comments stay internal. Close as completed → Done, not planned → Declined.
• Questions, reports and clicks per tenant per day are limited (100, 20, 500 unless the owner changes them).
• The token endpoint and its secret are the only trust between your product and the help desk: keep the secret out of logs, pages and the repository.