Tools

The Tools section of the project is where you define what the AI can do — fetch data, fire backend actions, ask the user to upload a file, render a card. Each tool you create here becomes available to the AI for matching against user messages.

This page is a field-by-field reference for the tool builder form. For the runtime side — how your mobile app handles a tool the AI invoked — see the Handling Tools guide.

Creating a Tool

1. Open Project → Tools
2. Click New Tool
3. Fill in at minimum: Name, Description, Execution mode
4. Save — the tool is enabled by default and immediately eligible for AI matching

The form is grouped into the sections below. Every field maps directly to runtime behavior described in the Handling Tools guide.

Identity & Matching

Description vs When-to-use

Tool invocation runs in two LLM phases, and the two fields target different phases:

Practical guidance:

• Always fill Description thoroughly. This is what governs how the tool actually behaves at runtime — multi-stage approval flows, “ask for missing detail before confirming” rules, response wording, etc.
• Fill When to use only when the Description is too long for the selector to skim quickly. Two-three short bullet-style lines of “fire when…” / “skip when…” are ideal. Adding whenToUse does not change chat-phase behavior — it only sharpens the selector.
• A common mistake is treating whenToUse as additive context for the main chat LLM. It isn’t. If the chat LLM needs to know something, it goes in Description.

Parameters

In the Parameters section, declare each input the AI should extract for this tool. For every parameter:

The AI pulls parameters from two places: the user’s message and whatever the SDK passes in its runtime context object. There’s no per-parameter “pull this key from context” wiring — if a value lives in context with a clear name, the AI will pick it up automatically.

Template Variables

Some parameters need values the AI shouldn’t generate — random tracking numbers, IDs, timestamps, fields pulled from the SDK’s userContext. Writing rules like “generate a random 10-digit number” in the description doesn’t work well: LLMs have heavy sample bias when asked for random values (you’ll see the same digit prefixes recurring). For these cases, write a template variable in the parameter’s Default value field — the server resolves it at runtime, then injects the resolved value into the AI’s prompt with a “use exactly this value” instruction.

Syntax: {{namespace.key}} (mustache style — distinct from the single-brace {paramName} substitution used in endpoint URLs).

Example: A complaint-tracking tool needs a stable reference number that’s unique per case and shown to the user in the chat reply. Set the parameter:

Name: trackingNo
Type: string
Default value: {{system.digits10}}

At runtime the server generates 4829105736, tells the AI “trackingNo is set to 4829105736 — use this exact value”, and the AI emits the same value in params.trackingNo plus naturally references it in the user-facing reply (“Your tracking number is 4829105736”). The same value is reused across all turns of the conversation (memoized per session) so the user never sees it change.

Use sites: Template variables work in any string field admins write — currently the parameter Default value, the email action’s Subject prefix, and the endpoint URL. More fields (webhook bodies, headers, deep links, loading messages) gain support as the system rolls out.

What to know:

• Recursion is disabled — values produced by token resolution aren’t re-scanned for tokens. Users can’t smuggle template syntax through their chat messages.
• {{user.*}} only reads keys the SDK already passed in userContext — no extra DB lookups, so adding a template token never widens the data the server can see.
• If the AI emits a different value than the server-generated one, the server silently overrides with its own value (and logs a warning so prompt drift can be detected).

Endpoint (Optional)

If the tool maps to a backend HTTP call, switch on Endpoint and fill in:

Execution Mode

The biggest behavioral choice — pick the mode based on where the tool actually runs and who writes the final reply.

The chosen mode is injected into the system prompt so the AI knows whether to write a final reply itself or just a bridge sentence.

Multi-Step Flows

Some tools collect data over several turns (e.g. “book an appointment” needs date, then service, then user confirmation). In the Steps section, add a row per milestone:

Step completion is reported to the SDK via the onStepCompleted callback.

File Input & Document Extraction

If the tool needs a file from the user (receipt photo, PDF invoice, etc.), switch on File Input and fill in:

To run AI extraction on the uploaded file, also switch on Document Extractor and add:

After upload, the backend runs the extraction LLM and emits structured data via the SDK’s onExtractionResult callback.

Backend Actions

In the Actions section, add side-effects that fire when the tool completes (or when a specific step completes — see Multi-Step Flows). Two action types:

Email

When the tool has a Tracking ID Format set (or the legacy params.no parameter), the email body’s details block auto-renders a tracking-number row with the resolved value at the top — no admin config required. To surface it in the inbox listing as well, include {{tool.trackingId}} in the Subject prefix.

Webhook

Webhook actions POST a JSON (or multipart) payload to a partner endpoint — typically a CRM, ticketing system, or workflow automation. Every webhook delivery is recorded in Action Logs with a full request/response snapshot so you can audit, debug, and reproduce locally.

URL & Method

Custom Headers

Add arbitrary headers as key/value pairs. Three common uses:

• Authentication — Authorization: Bearer xxx, X-API-Key: sk_live_.... Required for almost every real CRM.
• Routing metadata — X-Source: qafka, X-Environment: production. Helps the receiver classify or filter incoming requests.
• Tokenized values — header values support the same template tokens as the URL. Writing X-CRM-Reference: {{tool.trackingId}} puts the per-invocation tracking ID in a header so the receiver can route or de-duplicate without parsing the body.

Custom headers always win over the auto-set Qafka headers below — useful when you need to override User-Agent or replace the auto-attached metadata.

Auto-Set Qafka Headers

Every webhook request also carries these headers without admin config — receivers can rely on them for identification, idempotency, and signature verification:

Payload

The payload always includes a top-level trackingId field when the tool has a tracking ID set, regardless of these toggles. Receivers should rely on it for case correlation rather than parsing extraction.no (the legacy field).

File Delivery Format

When Include uploaded file is on, this dropdown picks how the file is sent:

User Info

Unlike the email action, webhook user context uses the raw key names (no localized labels) — receivers code against stable identifiers.

HMAC Signing Secret (optional)

When set, the runtime computes sha256(secret, payload) and sends the result in the X-Qafka-Signature header. The receiver verifies with the same secret to detect tampering and replay attacks. Recommended for any public-facing webhook; optional for internal CRMs.

The signed bytes are the JSON body for JSON-mode requests; for multipart requests the runtime signs a canonical formdata:<deliveryId>:<json-of-fields> string the receiver can recreate from the parsed parts. Implementation example for receivers:

const expected = 'sha256=' +
  createHmac('sha256', SHARED_SECRET)
    .update(rawRequestBody)
    .digest('hex');
 
if (req.headers['x-qafka-signature'] !== expected) {
  return res.status(401).end();
}

Rotate the secret periodically and prefer per-target secrets over a global one if the same Qafka project sends webhooks to multiple receivers.

Action Condition

Optional natural-language condition. AI decides whether to trigger this webhook based on the request context. See Conditional Actions.

Action results — success / failure / message — are delivered to the SDK via onActionResult. The full request and response snapshots (including masked auth headers, response status, response body) are captured in Action Logs for forensic auditing.

Conditional Actions

Both action types support an Action condition — free-form natural-language text the AI evaluates against the tool’s parameters, the SDK’s userContext, and the conversation. If the condition isn’t met, the action is skipped and an entry is written to Action Logs with the AI’s reasoning. Examples:

• "Only for complaint messages" — fire only when the AI judges the user is complaining
• "currentRegion = Europe" — deterministic field-equality form (admin friendly)
• "For users on the premium plan" — fuzzy semantic condition the AI resolves from userContext

The same evaluation happens in the same LLM call that produces the tool parameters — no extra round-trip, no extra latency. When no actions on a tool have conditions (and email actions are single-target), the condition decision payload is omitted from the prompt entirely, so cost is zero for tools that don’t use the feature.

Multi-Target Email Routing

A common case for email actions: route a single tool to different inboxes based on tenant or context. Add multiple Targets with per-target conditions; AI picks the matching ones at runtime. Single tool, single action, N inboxes.

Example — one support tool routing to different teams:

Targets are evaluated independently — write mutually-exclusive conditions for routing-style cases (one inbox), inclusive conditions for fan-out cases (notify multiple teams). When the AI cannot match any target on a multi-target email, the action is skipped (no broadcast) and the skip is logged. This is intentional KVKK behavior — empty conditions cannot leak data to all recipients by accident.

Per-target conditions also work with a single target: the AI decides whether that one address gets the email, equivalent to setting an action-level condition. Use whichever placement is more readable for the admin.

UI Rendering

The Response Configuration section tells the chat widget how to render the tool’s response. The outer settings (response type, data path, max items, layout, position) apply to BOTH renderer modes; the only choice is which renderer draws each item.

Common settings

Item renderer — pick one

Card mode

⚠️ Requires @qafka/react-native v1.1.0 or newer. Older SDK versions don’t know how to render a card and will silently fall through to the default renderer (plain text or basic list). Make sure your mobile app ships at least v1.1.0 before flipping a tool to Card mode in production.

Selecting Card opens an inline editor inside the section:

• Slug + Label — internal identifier and human-readable name. Slug is unique per tool.
• Card definition (JSON) — the schema is { schemaVersion: 1, root: <node> }. Each node has component plus its props at the same level (no props: {…} wrapping). Use fieldName to bind text/image leaves to fields in your tool result. Conditionally show ornaments with showIf.
• Sample data — paste a real example of what your tool returns. The preview binds against this; when you save the tool, the sample data persists alongside the card definition so the editor re-hydrates next session and the AI generate flow has a real shape to design around.
• Live preview — wrapped in an iPhone 16 Pro chrome so you see the card in roughly the same proportions partners will. Buttons inside the preview are inert; click handlers fire only inside the SDK.
• AI designer — Generate produces 2 variants (Compact + Detailed) from the tool description and sample data; Modify applies a natural-language change to the current JSON; ↶ Undo walks back through the last 10 AI edits.

Card buttons can fire one of seven CTA types: external_navigation, deep_link, suggest_message, copy, dismiss, share, tool_trigger. The SDK handles copy, dismiss, share, suggest_message, and external_navigation internally with sensible defaults. deep_link and tool_trigger cross the SDK boundary — the partner app registers a callback (see Card CTAs on the SDK side).

Tracking ID Format

The Tracking ID Format field (in the right sidebar, under Settings) generates a unique identifier per tool invocation. The same ID is shared across every action of that invocation — email subject, body, webhook payload, webhook headers, the AI’s user-facing reply, and the action log row — so one user-visible reference number traces a single transaction end-to-end.

Set it once on the tool. Reference it anywhere admin-authored strings live via the {{tool.trackingId}} token.

Examples

Where it shows up

• AI replies — write {{tool.trackingId}} inside the tool’s Description (e.g. “Your complaint has been filed under reference {{tool.trackingId}}”) and the AI quotes the same ID in its user-facing message.
• Email body — auto-rendered as a tracking-number row at the top of the details block; the admin doesn’t need to touch the email config to surface it.
• Email subject — write {{tool.trackingId}} inside the Subject prefix to put the ID in inbox listings (e.g. [Complaint] {{tool.trackingId}}).
• Webhook payload — sent as a top-level trackingId field on every webhook delivery, regardless of the action’s other config.
• Webhook headers — sent as X-Qafka-Tracking-Id automatically; admin headers can also reference {{tool.trackingId}} (e.g. X-CRM-Reference: {{tool.trackingId}}).
• Action log — stored in the tracking_id column with a B-tree index, so the Action Logs search box returns the row sub-millisecond.

Uniqueness

Tracking IDs are generated fresh per invocation — different complaints in the same chat session get different IDs (a session-wide cache earlier collapsed every complaint to one ID; that bug is fixed). Within a single invocation, every reference resolves to the same string by construction (resolved once when the prompt is built, then propagated). The IDs are not DB-unique; collision probability is governed by the random space of the format you choose. For {{system.digits10}} (10⁰¹⁰), birthday-paradox first collision at ~100k complaints, way past practical workloads. If you need stricter guarantees, add a unique index in your own migration.

Risk & Confirmation

Custom Data

The Custom Data field is a free-form JSON blob that travels with the tool to the SDK. Use it to pass partner-specific configuration (apiBaseUrl, brand strings, feature flags) so the mobile app’s onToolSuggested handler can stay generic across tools.

Loading Message

Enabled

Toggle a tool off without deleting it. Disabled tools are not sent to the AI for matching.