Custom apps
Show data from your own systems in the Desk side panel. QuantCX POSTs the contact to your endpoint, signed, and draws the card your endpoint returns.
When someone on your team opens a conversation or a ticket in the Desk, QuantCX calls your endpoint with the contact and draws the card your endpoint returns in the side panel's Apps. Your team sees it; the AI and the customer never do.
Setting up
Owners and admins add apps under Settings > Integrations > Custom apps: give the app a name and your endpoint URL, then copy the signing secret (it starts with qcx_app_). It is shown once, when the app is made or its secret is rotated. Up to 10 apps per workspace. Send test calls your endpoint with a sample contact.
The request
POST to your endpoint, Content-Type: application/json:
contact.verifiedistrueonly when your site proved who the contact is with a signed identity token.externalIdis then your own user id (the token'ssub). When it isfalse, the email is the contact's own word: show only what is safe to show about an address someone typed.conversationisnullwhen the panel is opened from a ticket.testistruefor Send test, with the sample contacttest.contact@example.com.
| Header | Value |
|---|---|
X-QuantCX-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with your signing secret> |
X-QuantCX-App | The app's id |
User-Agent | QuantCX-Apps/1.0 |
Limits
QuantCX waits 5 seconds, reads at most 64 KB, does not follow redirects, and only calls public https:// addresses on port 443. Answers are cached for a minute per contact; the panel's Refresh asks again.
Checking the signature (Node)
<code>import { createHmac, timingSafeEqual } from "node:crypto"; // header: the X-QuantCX-Signature value, rawBody: the request body exactly as received export function fromQuantCX(rawBody, header, secret, toleranceSeconds = 300) { const parts = Object.fromEntries(header.split(",").map(p => p.trim().split("=", 2))); const t = Number(parts.t); if (!Number.isInteger(t) || !parts.v1 || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false; const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest(); const given = Buffer.from(parts.v1, "hex"); return given.length === expected.length && timingSafeEqual(given, expected); }</code>Use the raw request body, before any JSON parsing, and refuse anything that fails with 401. The default tolerance of five minutes protects against replays.
The response
Answer 200 with JSON, or 204 (or a card with no sections) when you have nothing for this contact: the app is then not listed for them. Any other status shows the app as unavailable to your team with the status code, never your body.
| Field | Meaning |
|---|---|
status | One badge on the app in the dock and the Apps list. amber and red also put a dot on it. Optional. |
fact | The one key fact, shown in the conversation's Details. Optional. |
summary | One line under the app's name in the Apps list. Optional. |
sections[].title | Section heading. |
sections[].items[] | field (label and value, optional tone), badge, stats (up to 6), list (up to 20 rows: title, optional subtitle, meta, badge), text, link (https:// only, opens in a new tab). |
Tones: green, amber, red, blue, gray (an unknown tone on a badge becomes gray).
Limits: 8 sections, 20 items per section, labels 60 characters, values 200, titles 80, text 1,000. Longer strings are cut, unknown item types and fields are ignored, and everything is shown as plain text: HTML and Markdown are not rendered.
Who can see what
- Members of the workspace see the cards, for the workspace's own conversations and ticket requesters only.
- Owners and admins add, rename, re-point, switch off, rotate and delete apps.
- The signing secret is stored encrypted, and only the server that calls your endpoint can read it.