Connect

API & webhooks

Quincer AI is API-first. Everything you can do in the dashboard — take over a live chat, update a lead, read the activity log — you can do via REST. This page is the map. For request/response previews against your real workspace, open Developer APIs inside the dashboard, or try endpoints live with your key in the API Explorer (runs in your browser, so it isn’t affected by non-browser request filtering).

Authentication

All API requests use a workspace developer key. Generate one under Dashboard → Integrations → API keys, then Create key. In the dialog below, Key name is a label for you (“e.g. CRM Sync, Analytics Export”); the Scopes list is grouped by resource — tick a whole group or individual scopes like leads:read or conversations:takeover, and the key can only do what you check. An optional Expiry date auto-revokes it. Create key stays disabled until at least one scope is selected. Pass the key as a Bearer token:

Authorization: Bearer cw_dev_<your-key>

Two kinds of credentials exist: widget keys (cw_live_) are embedded in the page script and only identify a widget to the public chat endpoint. Developer keys (cw_dev_) are scoped to an organization, carry explicit scopes like leads:read or conversations:takeover, and must stay server-side.

A developer key can also be limited to specific brands. Choose “All brands” (the default, and what every existing key uses) or tick the brands it may reach when you create or edit the key.

Deleting is a separate permission from updating

A :write scope never authorizes a DELETE. Destructive operations have their own :delete scope — widgets:delete, knowledge:delete, leads:delete, personas:delete, locations:delete, playbook:delete, directory:delete, tasks:delete, phone:delete, suppressions:delete, webhooks:delete — so a key minted to keep your CRM in sync cannot erase what it syncs, and a key minted to restyle a brand cannot destroy it.

webhooks:manage still works and covers read, write and delete, so keys created before the split keep working. New keys should tick webhooks:read / webhooks:write / webhooks:delete individually.

Base URL

https://chat.quincer.com

POST /api/chat — widget-key chat

The widget/SDK chat endpoint is authenticated by a widget key (x-api-key: cw_live_…), not a developer key, and is CORS-open for browser + mobile clients. It is the same endpoint the JS widget and the React Native SDK use; most integrators embed the widget rather than calling it directly, but the response contract is documented here so mobile and custom clients can parse it consistently.

With stream: false the response is a single JSON body: { reply, personaName?, personaBubbleColor?, personaId?, conversationId?, messageId?, escalationPending?, secondMessage? }. With stream: true the response is a Server-Sent Events stream of frames data: {type:"text"|"handoff"|"done", …}:

• {type:"text", text} — a token chunk of the current reply.
• {type:"handoff", sourcePersonaName?, sourcePersonaId?, sourcePersonaBubbleColor?, personaName?, personaId?, personaBubbleColor?} — an immediate persona handoff: the current reply is finalized under the source persona and a new reply for the target persona begins in the following text frames. Clients should render this as a second, target-tinted bubble.
• {type:"done", personaName?, personaBubbleColor?, personaId?, conversationId?, messageId?, escalationPending?} — end of stream.

The non-streaming equivalent of the handoff frame is the additive secondMessage: { reply, personaName?, personaBubbleColor?, personaId? } field — the arriving persona's self-introduction, rendered as its own bubble after reply. Clients that read only reply (or only text frames) are unaffected.

POST /api/widget/visitor-info — visitor-supplied details

The submit target of the visitor-info form: when a brand requires identity details, the web widget renders a box per missing detail and posts them here, rather than the persona collecting them one question at a time. Widget key in x-api-key, CORS *.

POST /api/widget/visitor-info
x-api-key: <widget key>
Content-Type: application/json

{
  "conversationId": "cnv_123",       // optional, must belong to this widget
  "personaId": "per_456",            // optional, decides the lead's CRM destination
  "values": {
    "name": "Dana Ruiz",
    "email": "dana@acme.com",
    "company": "Acme",
    "phone": "+1 415 555 0134",
    "jobTitle": "Operations Lead"
  }
}

200 { "ok": true }
200 { "ok": true, "invalidEmail": true }   // address rejected, nothing saved for it

Only the five known fields are read; anything else in values is ignored rather than rejected, so a newer widget can talk to an older server. Values are trimmed and capped at 200 characters. Submissions persist through the same path as the agent’s own capture: one lead per conversation, identity mirrored onto the conversation, your team notified, CRM synced.

Conversations

Use these to let an outside AI (OpenClaw, a custom agent, or your own backend) discover, take over, reply on, and hand back live conversations. The takeover/reply/handback trio is how the OpenClaw integration works under the hood.

Leads

Tasks

Knowledge base

Personas

Each persona object carries two avatar fields: avatarUrl — the stored value (a preset path, an upload/generated storage key, or null) — and avatarKind — one of "preset", "upload", "generated", or null when the persona has no avatar. To render an avatar, use the resolved display URL: preset paths are served as-is, uploaded/generated images resolve to /api/persona-avatars/{persona_id}. The public embed config (/api/embed/config) and the chat frames already return a resolved, renderable URL; the /api/v1/personas objects return the raw stored avatarUrl + avatarKind.

Persona objects also include phoneNumbers (the inbound DIDs routed to the persona — manage them via the Phone numbers endpoints), status ("active" | "suspended" — suspend to pause a location; its inbound calls stop being answered), and externalRef (your own stable id for the persona, e.g. a location id, unique per widget). status and externalRef are settable on create/update, and you can filter the list by external_ref to make provisioning idempotent (find → create if absent, update if present). Knowledge scoping: knowledge added to a specific persona is answered only by that persona plus shared (unassigned) knowledge — other personas never retrieve it. Legacy note: addressing franchise locations via persona externalRef/status (one persona per location) is superseded by the first-class Locations resource, which keeps personas shared across locations — prefer it for multi-location brands.

Finding someone by phone, email or handle

Every channel now records who the visitor is, in one place, so a single query finds every conversation involving one person — whether they reached you by web chat, a phone call, SMS, WhatsApp, email, or a social DM. The same filters work on /api/v1/leads, which answers the same question the other way round (“who is this number?”).

# Every conversation involving a number, on any channel
GET /api/v1/conversations?phone=%2B14155550123

# The same, spelled generically
GET /api/v1/conversations?identity_value=%2B14155550123&identity_type=phone

# By email, or by a social handle
GET /api/v1/conversations?email=bob@example.com
GET /api/v1/conversations?identity_value=@bobsmith

# Who is this number?
GET /api/v1/leads?phone=%2B14155550123

Every call is channel=voice — an inbound or outbound phone call and a call started from the web widget or mobile SDK all land on that one channel. There is no channel=phone on conversations. A phone call is searchable by the caller's number; a web or mobile call has no number of its own, so it is findable only by an email or phone the visitor gave you during the call.

“Handle” means a username, not a display name. It matches where the platform gives us one — an Instagram @username, a WhatsApp username. It does not match a person's name: Google reviews carry the reviewer's display name (“Bob Smith”), Messenger and WhatsApp carry a profile name, and none of those are identifiers — indexing them would make a search for one common name return unrelated people. Search those threads by name in the dashboard instead. A value containing a space is rejected with a 400 rather than silently matching nothing.

Matching is on the whole value, not a fragment. There is no “last four digits” search. Phone numbers are compared after normalising away formatting, so +14155550123, 14155550123, (415) 555-0123 and 415-555-0123 all find the same conversation. Give numbers in full international form; a bare 10-digit number is accepted for the US and Canada only.

An unusable value is a 400, never an unfiltered list. If we cannot parse what you sent, you get an error explaining the format — we will not quietly drop the filter and return every conversation in the workspace.

GET /api/v1/conversations/:id returns an identities array ([{ "type", "value" }]) listing every handle a thread is reachable by, including the platform ids you need to line a thread up against your own webhook payloads. Staff conversations (Slack/Teams) are never returned by this API and are not reachable through identity search.

Locations

First-class locations for multi-location brands (franchises, chains). A location owns its local knowledge (items tagged location_id answer only for that location, alongside brand-shared items), its phone numbers, its lifecycle, and per-location overrides (spoken greeting, front-desk handoff number, timezone/hours and context notes injected into the AI's context) — while personas stay brand-level and shared across locations. Identity is external_ref (YOUR system's location id, unique per widget): POST with "upsert": true, or /bulk, and re-running your full location sync converges idempotently. status: "suspended" fails closed on every channel — calls to the location's numbers are rejected, its texts get no reply, and its web sessions are refused (location_suspended). Every plan includes one location, and creating a brand seeds it. That seeded row carries no external_ref, so your first upsert or /bulk sync adopts it rather than creating alongside it — you get 200, not 201, because no row was added. Multi-location is the plan-gated part: past your first, a net-new location returns 403 naming the cap. An update-only re-sync is never capped, however large.

Phone numbers

Inbound phone numbers (DIDs) mapped to a widget and, optionally, a persona and/or a location. An incoming call routes by the dialed number: the location is resolved first (a suspended location rejects the call), then the answering persona — the location's persona override, else the number's persona, else the widget default.

Sales playbook

Models

Widgets

Integrations

Connect/disconnect flows still require an interactive OAuth roundtrip and live under the dashboard at Dashboard → Integrations. This endpoint is read-only by design — programmatically minting OAuth grants from a dev key is a footgun.

Webhooks

Programmatic webhook subscription management. Previously dashboard-only; now a developer key with webhooks:write can provision a subscription end-to-end.

Delivery. Each delivery POSTs { "id", "event", "timestamp", "data" } to your URL. id is a stable delivery UUID (also sent as the Quincer-Delivery-Id header) that is the same across retries — dedupe on it for effectively-once processing. Verify Quincer-Signature (sha256=<hmac> of the raw body, keyed by your signing secret). Failed deliveries retry up to 3× with exponential backoff on transient failures (5xx / 429 / network / timeout); a 4xx is a permanent reject and is not retried. A subscription auto-disables after 10 consecutive failures.

Key events (full list + live “fires today” state under Dashboard → Integrations → Webhooks): conversation.message_received; conversation.ended — channel, persona/location, visitor, and the transcript, so you can reconstruct a whole conversation from one event (voice + text); conversation.escalated — fires the moment a conversation is handed to a human, with reason/target/source; conversation.takeover/handback; lead.*, task.*, and outbound.* (incl. outbound.call.completed with the call outcome).

Voice

Voice handoff (agent claim) remains seat-licensed and is initiated from Inbox → Live in the dashboard — it requires a User row with liveHandoffLicensed, not a service key, so it has no /api/v1 equivalent.

Outbound (email, SMS & suppressions)

Send outbound email and SMS through the unified dispatcher and manage the org-wide suppression (opt-out) list. Requires the Scale plan or the Outbound Campaigns add-on. Every send runs the full compliance pipeline server-side: the suppression list, TCPA quiet hours (SMS sent only during the recipient’s local 8am–9pm window), per-contact frequency caps, the CAN-SPAM mailing address (email), and per-persona daily mailbox limits. Email goes out from your connected Gmail/Outlook mailbox — never a shared Quincer address — with an unsubscribe footer appended automatically.

Sends are idempotent when you pass an Idempotency-Key header (or idempotency_key body field): replays return the original result — including refusals. Errors use { "error": { "code", "message", "retry_at"? } } with codes such as suppressed_recipient (409), quiet_hours (409 + retry_at), frequency_capped (429), no_mailbox_connected (409), no_consent_attested (403), invalid_destination (422), outbound_disabled (503), and provider_unavailable (503 — the mailbox provider or carrier rate-limited us or was down; nothing was sent, so the same request may be retried). Webhook events: outbound.email.sent/.failed, outbound.sms.sent/.failed, outbound.call.started, outbound.call.completed (payload carries the outcome).

All update operations use POST on the resource path (POST /api/v1/leads/:id). PATCH on the same path stays accepted for one major version so existing integrations don’t break, but POST is the canonical method going forward.

Resource type discriminator

Every resource response carries a read-only object field naming the resource type ("lead", "conversation", "task", "message"). List responses carry object: "list" at the envelope and per-item object fields inside data[]. Use it to deserialize polymorphic payloads (e.g., webhooks, mixed-resource responses).

{
  "object": "lead",
  "id": "clx...",
  "stage": "qualified",
  "temperature": "warm"
}

Pagination

List endpoints return a data array plus a has_more boolean and a url field naming the endpoint. Use cursor pagination via starting_after=<resource_id> — the API returns the next page of items created before that cursor. limit is bounded at 200 (default 50).

GET /api/v1/leads?limit=20&starting_after=clx_abc123

{
  "object": "list",
  "data": [ { "object": "lead", "id": "clx_xyz789", ... }, ... ],
  "has_more": true,
  "url": "/api/v1/leads",

  // Legacy fields surfaced alongside the new envelope for one major
  // version. New consumers should read `data` + `has_more`.
  "leads":  [ /* same items as data[] */ ],
  "total":  142,
  "limit":  20,
  "offset": 0
}

Naming conventions

Envelope / meta keys are snake_case (object, data, has_more, url). Resource field names are camelCase (widgetId, visitorId, takenOverBy, activePersonaId, createdAt, …) — read them exactly as they appear in the response examples on this page. Query parameters accept snake_case (widget_id, updated_since, starting_after), and the camelCase equivalents (widgetId, updatedSince, assignedTo, leadId) also continue to work as filter aliases.

Rate limits

Developer keys are rate-limited per key: 100 reads/min and 30 writes/min by default. Higher ceilings are available — if your integration needs them, ask support and we can raise them on your account without you changing anything. Every authenticated response carries the current state in headers so well-behaved clients can self-throttle, and Quincer-RateLimit-Limit always reports your ceiling rather than the default:

Quincer-RateLimit-Limit: 100
Quincer-RateLimit-Remaining: 87
Quincer-RateLimit-Reset: 1714435260

Over the limit returns 429 Too Many Requests with both the standard Retry-After header (seconds until reset) and the Quincer-RateLimit-* headers. The error body indicates the remaining count.

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Quincer-RateLimit-Limit: 100
Quincer-RateLimit-Remaining: 0
Quincer-RateLimit-Reset: 1714435260

{
  "error": "Rate limit exceeded. 0 read requests remaining. Retry after 42 seconds."
}

Webhooks

Subscribe to events under Dashboard → Integrations → Webhooks, then Add webhook. In the dialog below, Endpoint URL is where Quincer POSTs each event; the Events grid lets you tick exactly the events you want — Lead Created, Lead Stage Changed, Visitor Message Received, Conversation Ended, Task Completed, and the rest. On Create webhook, the signing secret is shown once — copy it before closing. Quincer AI signs every payload with HMAC-SHA256 using that secret. Requests include Quincer-Signature (sha256=...), Quincer-Event, and Quincer-Timestamp. The legacy X-Quincer-* variants are also sent for one major version (RFC 6648 deprecated the X- prefix — existing subscribers reading X-Quincer-* keep working unchanged).

Events

Verifying signatures

const signature = req.headers["quincer-signature"];
// (or "x-quincer-signature" if you set up your webhook before April 2026)
const expected = "sha256=" + crypto
  .createHmac("sha256", process.env.QUINCER_WEBHOOK_SECRET)
  .update(req.rawBody)
  .digest("hex");
if (signature !== expected) {
  return res.status(401).send("invalid signature");
}

OpenClaw integration

Quincer AI ships a first-class OpenClaw skill so any OpenClaw agent can take over Quincer AI conversations, query leads, and log activity. Setup takes about a minute. The Connect OpenClaw dialog below is step one — it explains that connecting creates a dedicated OpenClaw team member in your workspace and issues an API token bound to it, so takeovers and replies show up in your inbox under that member. The Agent display name field is what visitors see when OpenClaw replies in chat (defaults to “OpenClaw”); on Connect the token is shown once for you to copy:

1. In Quincer AI, open Dashboard → Integrations → OpenClaw and click Connect OpenClaw. This creates a dedicated "OpenClaw" team member in your workspace and issues an API token bound to it.
2. Download SKILL.md and drop it in ~/.openclaw/workspace/skills/quincer/.
3. Add the token to ~/.openclaw/openclaw.json under skills.entries.quincer.env.QUINCER_API_KEY.
4. Restart the OpenClaw gateway. The quincer tool is now available.

OpenClaw actions (takeovers, replies) appear in your Quincer AI inbox under the OpenClaw team member, with their own avatar and audit trail — not as a generic "external agent."