Connect

Custom REST tools

Give your AI assistant a brand-new skill by pointing it at any HTTP endpoint — your database, your CRM, a SaaS API, an internal service. No code. A guided wizard walks you through it one step at a time, or you can let Describe it with AI draft the setup for a well-known service. This is the same mechanism that powers our own dashboard assistant’s abilities.

How a tool works

A custom tool is one HTTP request the assistant can make on its own. When the conversation calls for it, the model collects the inputs you defined, the platform fills them into the request, calls your endpoint, and hands the response back to the model to use in its reply.

1. You define a tool: a name, a description (so the model knows when to use it), the HTTP request, and the inputs to collect.
2. A visitor says something that needs it (“where’s my order?”).
3. The model gathers the inputs, the platform makes the call, and the model answers with the live result.

The Add wizard

Clicking Add custom tool opens a guided, no-code wizard. It starts with a choice screen — Describe it with AI (best for well-known systems like Jira, Stripe, or HubSpot) or Set it up manually (best for your own or in-house APIs). Either way you land in the same five-step builder; the AI path just pre-fills it first.

The manual builder has five steps you can jump between at any time:

1. Name — a short handle the model calls (e.g. track_shipment; lowercase letters, digits, and underscores, starting with a letter, up to 64 chars) and a plain-English description of what the tool does. The model reads the description to decide when to use the tool, so be specific about the inputs and outputs.
2. Fields — the information the tool needs, built visually (see The field builder below). No JSON, no brackets.
3. Address — the HTTP method (GET, POST, PUT, PATCH, or DELETE) and the full https:// URL. Tap a field to drop it into the URL — no typing brackets (see Placeholders). If the URL references a {{input.x}} that has no matching field, the step blocks you with a warning until you add the field.
4. Sign in — how the tool authenticates (see Sign in below). Secrets are stored encrypted.
5. Test — send one real request so you know it works before it goes live (see Test it).

Under the hood the visual builder assembles the exact same request shape the raw form produces, so nothing about how tools run changes — the wizard just hides the JSON.

The field builder

Step 2 is a visual list — one row per piece of information the tool collects. Click Add a field for each. Every row has:

Sign in

Step 4 is a segmented picker for how your endpoint authenticates. Pick one style and fill in its inputs; Quincer stores the secret encrypted and adds the right header to every request:

Send who the visitor is

A phone caller is not signed in, so there is no verified token and no {{identity.…}} to inject — but you usually still know something useful about them: the number they called from. Switch Send who the visitor is on for a tool and every call to it carries that identity as HTTP headers, so your endpoint can look the person up and answer with their own data.

The toggle is on the tool’s card in Integrations → Custom REST tools, and also inside the tool’s own edit screen next to Require verified visitor. It is off by default — sending your customers’ phone numbers and email addresses to a third-party endpoint is a decision you make, not one we make for you. It is per tool, so a tool that looks up an order can receive the caller’s number while a tool that fetches your public price list never sees it.

These are the same headers an MCP server receives, for the same reason: one behaviour, so a tool behaves the same way whichever kind it is. They are sent as headers and never as tool arguments, so the model cannot invent, alter, or omit them.

On an outbound call nothing is sent. The far end there is someone Quincer dialled, not a caller identifying themselves — reporting the number we just rang as “the caller” would tell your endpoint something it already knows, and would be an outright wrong-identity lookup if a switchboard or another person picked up.

Describe it with AI

The fastest way to build a tool for a well-known service. On the choice screen pick Describe it with AI, describe what you want in plain English, and click Draft the setup. Try a prompt like:

Create a Jira issue in our SUPPORT project

Look up a shipment by tracking number in our orders API

The assistant drafts the method, endpoint, fields, and sign-in for you using its knowledge of well-known APIs, then drops you into the wizard pre-filled so you review and finish — usually just pasting your real API token where it left a placeholder (it never invents secrets). Nothing goes live until you save.

It also knows Quincer’s own API, so prompts like “create a tool that builds a new Quincer persona” or “let the assistant list my leads” produce the real endpoint and the correct Bearer cw_dev_ developer-key auth automatically.

Advanced (raw JSON)

Some tools go beyond what the guided steps cover — anything that needs a request body, sets a custom timeout or rate limit, or restricts the tool to a verified visitor. For those, the choice screen has a third option below the two cards: Advanced — set it up with raw JSON. It opens the full field-by-field editor. You also land here automatically when an AI draft carries one of those (see above), pre-filled, with a note explaining which part the guided builder couldn’t show. (Extracting a field from the response — the response path — is handled right in the wizard’s Test step now, so it no longer sends you here.)

The Advanced form adds these fields on top of the basics:

Editing a tool

Click the pencil on any tool in the Custom REST list. Editing isn’t re-walking the wizard — you land on a review-and-edit accordion of collapsed cards and open just the part you want to change: Basics (name, method, description), Information it needs (the field builder), Address (method + URL + variable chips), and Sign in (the auth picker). A saved secret shows as •••• saved with a Replace button so you never have to re-enter it to tweak something else. An inline Test connection button runs a real request, and Save changes stays disabled until a section actually differs.

Tools that use fields the visual builder can’t hold — a request body, a response path, a custom timeout, verified-visitor requirements, HTTP Basic auth, or a schema/headers shape the builder doesn’t model — open in the Advanced (raw JSON) form instead, so a rich tool is never silently corrupted by editing it visually.

Placeholders

Use these in the Address (URL) and, in the Advanced form, the body template — substitution is deep (works inside nested JSON):

• {{input.field}} — the value the model collected for that field. In the wizard, tap a field’s chip on the Address step to insert it.
• {{identity.account_id}} — the signed-in visitor’s account id. This is the one identity token the wizard’s chip inserts for you (labeled + account_id).
• {{identity.sub}} — the verified visitor’s user id (requires Visitor sign-in + “require verified visitor”).
• {{identity.email}} / {{identity.<claim>}} — any claim from the verified token.
• {{identity.jwt}} — the raw verified JWT, to forward auth to a backend that re-verifies it.

The visual chip only inserts {{input.<field>}} and {{identity.account_id}}; the other {{identity.…}} tokens are still valid at runtime — type them into the URL, or use the Advanced form.

Example 1 — create an AI persona

Teach the assistant to spin up new personas on command, using Quincer’s own REST API. This one POSTs a body, so build it with Describe it with AI (“create a tool that builds a new Quincer persona”) or the Advanced form — the no-code steps don’t carry a body. First create a key under Integrations → API keys with the personas:write scope, then:

Input schema

{
  "type": "object",
  "properties": {
    "name":   { "type": "string", "description": "The new persona's name" },
    "prompt": { "type": "string", "description": "The persona's system prompt" }
  },
  "required": ["name", "prompt"]
}

Headers — the Quincer API uses a Bearer token (your key starts with cw_dev_):

{ "Authorization": "Bearer cw_dev_YOUR_KEY", "Content-Type": "application/json" }

Body template

{ "name": "{{input.name}}", "systemPrompt": "{{input.prompt}}" }

Now say “create a persona called Spanish Support that always replies in Spanish” and it appears under Personas.

Example 2 — look up a shipment in Postgres

Expose a read-only query over a Postgres table via a REST layer like PostgREST or Supabase. This one is a GET with no body, so you can build it end to end in the no-code wizard: one Text field tracking_number, the URL below (tap the field’s chip to drop it in), and Custom sign-in with the two Supabase headers.

Field

• tracking_number — type Text, Required on. “The shipment’s tracking number.”

Sign in — Custom, two header rows:

apikey:        YOUR_SUPABASE_ANON_KEY
Authorization: Bearer YOUR_SUPABASE_ANON_KEY

Tip: a REST layer returns an array of rows. To hand the model just the first match, set Response JSONPath to 0 in the Advanced form (a response path isn’t part of the no-code steps). Keep the role/key read-only and scoped with row-level security so the tool can only see what you intend.

Example 3 — open a Jira support ticket

Let the assistant file a Jira issue when it can’t resolve something. This is the ideal Describe it with AI case: say “create a Jira issue in our SUPPORT project” and the draft — including Jira’s nested Atlassian Document Format body — lands in the Advanced form for you to finish (the body means it can’t stay in the no-code steps). Auth is HTTP Basic with your Atlassian email + an API token, base64-encoded as email:token.

Input schema

{
  "type": "object",
  "properties": {
    "summary":     { "type": "string", "description": "Short issue title" },
    "description": { "type": "string", "description": "What the visitor reported" }
  },
  "required": ["summary", "description"]
}

Headers

{
  "Authorization": "Basic YOUR_BASE64_EMAIL_AND_TOKEN",
  "Content-Type": "application/json"
}

Body template

{
  "fields": {
    "project":   { "key": "SUPPORT" },
    "issuetype": { "name": "Task" },
    "summary":   "{{input.summary}}",
    "description": {
      "type": "doc", "version": 1,
      "content": [{ "type": "paragraph", "content": [
        { "type": "text", "text": "{{input.description}}" }
      ]}]
    }
  }
}

(Jira’s description uses Atlassian Document Format, hence the nested shape. Describe it with AI writes this for you if you’d rather not hand-roll it.)

Test it

The wizard’s final step — and an inline Test connection button on the edit accordion — sends one real request from Quincer to your endpoint, using a sample value for each field, and shows you the status, the latency, and the response body. Do this before it goes live.

1. On the Test step (or the edit screen), click Send a test request / Test connection. A green card confirms the connection and shows the returned body; a red one explains what failed.
2. Save the tool. It appears in the Custom REST list — toggle Enabled if it isn’t already.
3. Open your widget (or the preview) and ask something that should trigger it; watch the model collect the inputs, call your endpoint, and answer with the live result.

The test runs as you (the operator), not a signed-in chat visitor, so {{identity.…}} tokens can’t be filled in there — they’ll resolve in a real chat once a visitor is signed in. If the tool doesn’t fire in chat, tighten the Description so it’s unmistakable when the tool applies, and double-check required fields.

Security & limits

• Your secrets stay in headers — tokens are stored encrypted and added to the request server-side; the assistant never sees or speaks them. On edit they stay masked as •••• saved until you Replace them.
• Public endpoints only — the endpoint must resolve to a public address; requests to private/internal IPs are blocked.
• Per-tool timeout & rate limit keep a slow or chatty endpoint from affecting conversations (the timeout is adjustable in the Advanced form, 1000–30000 ms).
• Scope down — give the tool the narrowest credential that works (read-only key, single project, row-level security). The assistant can only do what the endpoint allows.
• Require verified visitor for any per-user action, and use {{identity.*}} so a visitor can only act on their own data. Injected claims can’t be spoofed by the model — they’re overwritten from the verified token.
• Calls are logged, secrets aren’t — each tool call is recorded (endpoint, status, latency) with the request sanitized so injected secrets stay as placeholders, not stored values. Deleting a tool removes its call logs.