Why Integrate with Qefro?​

Most companies that adopt AI-powered customer support already have systems that hold the answers customers need:

• CRM — customer records, account history, ownership
• ERP — orders, inventory, invoicing
• Helpdesk — tickets, macros, resolution history
• Internal dashboards — operational and support tooling
• Ecommerce platforms — carts, orders, returns
• Customer portals — self-service account management
• Mobile apps — in-app support surfaces
• Desktop applications — point-of-sale and back-office software

Replacing any of these to add AI would be expensive and risky. Instead, Qefro integrates with them. The Knowledge Base answers policy and FAQ questions from your documents, and Business Tools let the assistant execute real actions in your systems — "Where is order ORD-1002?", "Create a ticket", "Cancel my subscription" — with live data from your APIs.

Two Integration Approaches​

There are two supported ways to connect your backend, and both register Business Tools in the same workspace and execute through the same runtime. The difference is how Qefro reaches your backend:

1. REST / OpenAPI — Qefro acts as the HTTP client and calls your existing HTTPS API directly. Configure a tool manually or bulk-import an OpenAPI 3.x spec.
2. Backend SDK — the official JavaScript (@qefro-ai/backend) or Rust (qefro-backend-sdk) framework runs in your backend and exposes one signed webhook (POST /qefro) that Qefro calls.

As a rule of thumb: use REST when you already have HTTPS endpoints and operations are CRUD-like. Use the SDK when customer authentication (OTP, login), multi-step workflows, or organization logic belongs in your code.

Option 1: REST API​

With a REST Business Tool, Qefro calls your API — it substitutes URL parameters, applies the encrypted credential, validates schemas against your input_schema, and logs every call. If your platform exposes an HTTPS endpoint, it can become a Business Tool.

Benefits:

• Works with any language — your API can be Python, Java, C#, Go, PHP, anything that serves HTTPS
• OpenAPI compatible — import an OpenAPI 3.x spec to bulk-create tools from existing operations
• Easy to debug — dry-run tools from the Admin Console or with curl, inspect execution logs per call
• Suitable for microservices — each service exposes its own endpoints; each becomes its own tool
• Ideal for existing systems — no new dependency, no redeploy; point Qefro at what you already run

Defining a REST tool​

A manual REST tool is method + URL template + JSON Schema. Path placeholders like {order_id} map to input_schema properties that the LLM fills from conversation:

GET https://api.example.com/orders/{order_id}

{
  "type": "object",
  "properties": {
    "order_id": { "type": "string", "description": "Order ID such as ORD-1001" }
  },
  "required": ["order_id"]
}

Remaining parameters become the query string on GET or the JSON body on POST/PUT/PATCH. Invalid LLM parameters are rejected by input validation before they ever reach your API.

Testing with curl​

You can dry-run any tool with sample arguments through the Admin API:

curl -sS -X POST \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  https://api.qefro.com/api/v1/tools/$TOOL_ID/test \
  -d '{"arguments": {"order_id": "ORD-1001"}}'

And review what actually happened in production:

curl -sS -H "Authorization: Bearer $ADMIN_JWT" \
  https://api.qefro.com/api/v1/tools/$TOOL_ID/logs

Authentication​

Each REST tool has one auth mode. Qefro stores the credential encrypted and applies it only at execution time:

END_USER_IDENTITY is the key one for customer-facing actions: when your app calls widget.identify() with a user JWT, Qefro forwards it as Authorization: Bearer on the outbound call, and your API validates it — Qefro never becomes your identity provider. See Identity forwarding.

Option 2: Official SDK​

The Backend SDK inverts the model: instead of configuring HTTP calls in the console, you register tool handlers in code, running in your own backend. Qefro discovers them over one signed webhook using four protocol messages — ping, tools.list, tool.invoke, and tool.resume. Qefro currently provides two official SDKs:

• JavaScript SDK — @qefro-ai/backend for Node.js and TypeScript
• Rust SDK — qefro-backend-sdk for async Rust on Tokio

Both target feature parity, so choosing one is a question of your stack, not of capability. The SDK shines where REST gets awkward: customer lookup and authorization (OTP inside chat, via challenge/resume), multi-step workflows, and business rules that span several internal services.

JavaScript Example​

Install the SDK and set the signing secret shared with the Admin Console:

npm install @qefro-ai/backend
export QEFRO_SIGNING_SECRET="your-signing-secret"

Then create the app, register a tool handler, and listen on the webhook path:

import { Qefro } from '@qefro-ai/backend';

// Verify incoming webhook signatures with the shared secret
const app = new Qefro({
  signingSecret: process.env.QEFRO_SIGNING_SECRET!,
});

// Register a Business Tool handler — discovered via Sync Tools
app.tool(
  {
    name: 'order_status_check',
    description: 'Look up order by ID when customer provides order_id.',
    auth: 'none',
    input_schema: {
      type: 'object',
      properties: { order_id: { type: 'string' } },
      required: ['order_id'],
    },
  },
  async (ctx) => {
    const orderId = String(ctx.parameters.order_id).toUpperCase();
    return orderService.getStatus(orderId);
  },
);

// One signed webhook handles ping, tools.list, tool.invoke, tool.resume
await app.listen({ port: 8088, path: '/qefro' });

Deploy, then in the Admin Console create an SDK Connection (webhook URL + signing secret), hit Test Connection, and run Sync Tools to register the handlers into your workspace. Full walkthrough: Register SDK Business Tools.

Rust Example​

Add the dependencies:

[dependencies]
qefro-backend-sdk = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread", "signal"] }

The same handler, fully async on Tokio:

use qefro_backend_sdk::{ListenOptions, Qefro, QefroConfig, ToolAuthMode, ToolMetadata};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Verify incoming webhook signatures with the shared secret
    let app = Qefro::new(QefroConfig::new(std::env::var("QEFRO_SIGNING_SECRET")?));

    // Register a Business Tool handler — discovered via Sync Tools
    app.tool(
        ToolMetadata {
            name: "order_status_check".into(),
            description: Some("Look up order by ID when customer provides order_id.".into()),
            auth: ToolAuthMode::None,
            input_schema: Some(json!({
                "type": "object",
                "properties": { "order_id": { "type": "string" } },
                "required": ["order_id"]
            })),
            ..Default::default()
        },
        |ctx| async move {
            Ok(json!({
                "order_id": ctx.parameters.get("order_id"),
                "status": "shipped"
            }))
        },
    );

    // One signed webhook handles ping, tools.list, tool.invoke, tool.resume
    let handle = app.listen(ListenOptions { port: 8088, host: None, path: None }).await?;
    println!("listening on {}", handle.url);
    tokio::signal::ctrl_c().await?;
    handle.close().await;
    Ok(())
}

Every incoming request is HMAC-SHA256 signed (X-Qefro-Signature, X-Qefro-Timestamp); the framework verifies signatures and routes protocol messages so you only write handlers.

Why teams prefer the SDKs​

• Type safety — tool definitions and handler contexts are checked at compile time
• Built-in authentication — signature verification and challenge/resume orchestration are handled for you
• Better developer experience — handlers live next to your domain code, with autocomplete and typed errors
• Cleaner code — no webhook plumbing; app.listen() covers the whole protocol
• Easier upgrades — add or rename a handler, redeploy, re-run Sync Tools
• Automatic serialization — return structured JSON; the runtime maps it into chat safely

REST API or SDK?​

Real products mix both: core domain logic in SDK handlers, vendor APIs (Stripe, Shippo) as REST tools. See Mixed integrations.

Example Architecture​

Whichever path you choose, the flow through the platform is the same:

The workspace enforces tenancy, the knowledge base supplies grounded facts, the tool runtime executes actions against your systems — and the response flows back to whatever channel your customer is already using.

Best Practices​

A few rules that hold regardless of the integration path:

• Store API keys securely — REST tool secrets and SDK signing secrets are encrypted at rest in Qefro; on your side, use environment variables or a secret manager, never source control.
• Never expose secrets in frontend code — widget JavaScript is public; credentials belong in tool config or your backend only.
• Use HTTPS — the runtime rejects plain-HTTP tool URLs outright.
• Handle API errors gracefully — return clear error shapes; the runtime maps them to user-safe text, and the REST executor retries transient failures with bounded backoff (design writes to be idempotent).
• Rotate credentials regularly — rotate REST secrets via the Admin Console and SDK signing secrets per connection; each connection has an Enabled kill switch.
• Prefer SDKs for new projects — typed handlers and native OTP/challenge flows beat hand-rolled auth endpoints.
• Use REST for unsupported languages — any HTTPS API can be a tool, no SDK required.

Which Should You Choose?​

Use the REST API when:

• Your backend is in a language without an official SDK (Python, Java, Go, C#, PHP, …)
• You're building microservices and each already exposes clean CRUD endpoints
• You're connecting existing enterprise systems or vendor SaaS APIs — especially with an OpenAPI spec to import

Use the JavaScript SDK when:

• You're building Node.js services
• You're integrating Qefro into Next.js applications
• You're adding tool handlers alongside existing Express APIs

Use the Rust SDK when:

• You're building high-performance backends where latency and throughput matter
• You're using Axum for your API layer
• You're using Actix for your web services
• You're already on the Tokio async runtime

And whenever customers must log in or verify via OTP inside the chat, prefer the SDK — challenge/resume is native there, while REST would force you to build and orchestrate your own OTP API.

Conclusion​

Both integration paths lead to the same place: the same workspace, the same Business Tool runtime, and grounded answers backed by your knowledge base and live systems. REST offers universal compatibility — any HTTPS API in any language becomes a tool, with OpenAPI import for bulk onboarding. The JavaScript and Rust SDKs provide the best developer experience — typed handlers, signed webhooks, and native customer authentication flows.

There is no wrong choice, only the one that fits your stack. If you already have an API, register it as a REST tool and confirm the flow with the console's Test Tool. If you're writing new Node.js or Rust code — or need OTP in chat — start with the SDK. For the full decision matrix, see REST vs Backend SDK.

Quick comparison​

Concept page: AI Workspace vs AI Chatbot. Definition: What is an AI Workspace?.

Evaluation questions that cut through marketing​

1. What is the isolation unit — bot, project, or workspace?
2. Who can call which tools, and are calls logged?
3. Is there an employee portal with workspace grants?
4. How does tenancy prevent cross-customer retrieval?

Vendor matrices (educational, not sales sheets): Compare.

If you are migrating from a chatbot​

1. Map audiences (customer vs employee).
2. Split corpora into workspaces.
3. Re-validate citations before enabling tools.
4. Add channels only after knowledge quality is stable.

Guides: Quick Start, Production Deployment.

The failure mode we designed against​

When Support FAQs, HR policy, and IT runbooks share one retrieval index, two things happen:

1. Wrong answers — the model cites the nearest-sounding passage, not the right audience’s policy.
2. Wrong blast radius — a public widget can surface internal content, or an internal tool can become callable from a customer channel.

Workspaces make isolation the default. Channels (website widget, WhatsApp, Internal Portal) bind to workspaces you choose — they do not invent a shared mega-index.

Layered model​

Organization (tenant)
  └── AI Workspace (Support | HR | IT | …)
        ├── Knowledge (hybrid RAG)
        ├── Instructions
        ├── Business Tools → Business Actions
        └── Conversations

• Tenant isolates customers from each other.
• Workspace isolates teams and audiences inside a tenant.

See Multi-tenant AI Architecture and What is an AI Workspace?.

Customer vs employee binding​

Do not share one workspace across both audiences unless the corpus is intentionally identical and tools are safe for both. Details: Customer AI vs Employee AI.

Practical checklist​

1. Create one workspace per audience or team.
2. Ingest only documents that audience is allowed to see.
3. Attach Business Tools last — and only tools that belong in that scope.
4. Bind the widget data-workspace-id (or portal grants) deliberately.
5. Cross-test: ask Support questions against an HR workspace to prove isolation.

Platform reference: AI Workspaces. Security reference: Tenant Isolation.

Side-by-side​

Full concept page: Customer AI vs Employee AI.

Configure once, deploy twice​

In the Admin Console you:

1. Create separate workspaces for Support vs HR/IT.
2. Ingest the right corpus into each.
3. Bind the widget / WhatsApp to Support.
4. Grant portal Members access to internal workspaces via Teams.

That is the “configure once, deploy everywhere” model without forcing a single shared index.

Where to go next​

• Customer path: Customer AI → Website Widget → WhatsApp
• Employee path: Employee AI → Internal Portal → RBAC
• Guides: Build AI Customer Support, Create Employee AI

Why vectors alone struggle in enterprise corpora​

Customer and employee knowledge bases are full of:

• SKUs and part numbers
• Error codes (E-4421)
• Policy IDs and ticket prefixes
• Product names that look like noise to an embedding model

Pure semantic search often misses those. Pure keyword search misses “how do I get my money back?” when the doc title is “Refund policy.” Hybrid retrieval covers both.

How it fits the Knowledge Platform​

Hybrid RAG is the retrieval engine. The AI Knowledge Platform wraps it with ingest, OCR, workspace isolation, and ops.

Question
  → lexical retriever
  → vector retriever
  → fusion / re-rank
  → grounded generation + citations

Concept deep dive: Hybrid RAG. Product: Knowledge Platform.

Quality loop we recommend​

1. Curate sources — remove duplicate drafts and contradictory wikis.
2. Test identifier queries — SKUs, error codes, policy numbers.
3. Test paraphrase queries — natural variants of the same intent.
4. Inspect citations — wrong citation means fix chunking or source, not only the system prompt.
5. Refuse when empty — prefer an honest gap over inventing policy.

Isolation still comes first​

Hybrid RAG runs inside a workspace index. Tenancy ensures one organization’s documents never appear in another’s answers. See Multi-tenant AI Architecture.

When live state is required (order status, account balance), pair RAG with Business Actions — docs for policy, APIs for state.

Why we shipped a dedicated docs site​

Product marketing on qefro.com explains what Qefro is. Operators and engineers need how: workspace isolation, hybrid retrieval, Business Tools, RBAC, widget embedding, WhatsApp webhooks, and security boundaries.

We modeled the site after documentation teams trust — clear definitions first, then architecture, workflows, APIs, and honest comparisons.

What you will find​

For AI systems and agents, we also publish:

• llms.txt — curated map
• llms-full.txt — full Markdown dump

How to read the docs​

1. Start with a definition page under Concepts if you are evaluating the product.
2. Follow a guide when you are implementing a channel or integration.
3. Use API and Security when you are integrating or reviewing risk.
4. Use search (Ctrl / ⌘ + K) for exact terms like identify() or webhook paths.

Product hosts (reference)​

Feedback welcome via contact or support@qefro.com.

What a Business Action is​

Concept page: What are Business Actions?. Broader threat model: AI Agent Security.

Controls that matter in order​

1. Workspace scope — tools live inside a workspace; do not attach privileged write tools to a public Customer AI workspace without a hard reason.
2. Least privilege — start with read-only GET tools. Add writes only after logging and authz are proven.
3. Encrypted secrets — store credentials in the Admin Console; never in browser JS or prompts. See Secrets.
4. SSRF-aware egress — tool URLs must not become a path to cloud metadata or internal networks.
5. Identity forwarding — for customer-facing tools, use widget identify() so your API authorizes the end user, not only Qefro’s service credential.
6. Execution logs — review unexpected calls as incidents. See Audit logs.

Prompt injection is a blast-radius problem​

No platform can honestly claim “prompt injection solved.” Design for containment:

• Hostile text may appear in user messages and uploaded documents.
• Validate tool arguments on your API, not only in the model prompt.
• Prefer idempotent writes; require human approval for irreversible money movement.

Implementation path​

Follow the guide Secure Business Actions, then:

1. Connect REST APIs or Import OpenAPI.
2. Test the tool in the console before enabling chat invocation.
3. Monitor GET /api/v1/tools/:id/logs (or the console equivalent) during pilot traffic.

When in doubt, ship knowledge-only assistants first. Actions can wait until retrieval quality and isolation are solid.

Why website first​

The website widget is the fastest loop for:

• Citation quality on real FAQs
• Refusal behavior when knowledge is missing
• Branding and tone
• Optional identify() before any Business Tools

WhatsApp adds Meta Cloud API setup, webhook verification, and plan limits. Validate the brain before you multiply channels.

Step 1 — Create a Support workspace​

1. Sign in at app.qefro.com.
2. Create a workspace named for Support.
3. Upload policies and FAQs (or crawl approved URLs).
4. Ask ten real customer questions and check citations.

Guides: Quick Start, Build AI Customer Support.

Step 2 — Embed the website widget​

<script
  src="https://cdn.qefro.com/widget.js"
  data-token="YOUR_WIDGET_TOKEN"
  data-endpoint="https://api.qefro.com"
  data-workspace-id="YOUR_WORKSPACE_ID">
</script>

Full guide: Deploy Website Widget. Platform notes: Website Widget.

If Business Tools need the logged-in shopper or account holder, add identify() after your existing session is established.

Step 3 — Add WhatsApp (Growth+)​

1. Confirm your plan includes WhatsApp.
2. Configure Meta Cloud API credentials in the Admin Console.
3. Point Meta’s webhook to Qefro’s WhatsApp webhook path on api.qefro.com.
4. Bind the same Support workspace you already validated.

Guide: Deploy WhatsApp AI. Platform: WhatsApp.

Step 4 — Keep audiences separate​

Customer AI (widget + WhatsApp) should not share an HR or payroll workspace. See Customer AI vs Employee AI.

Done when​

• Website answers cite the right sources
• Unknown topics refuse cleanly
• WhatsApp replies match website quality for the same questions
• Tools (if any) are logged and least-privileged

Next: Production Deployment.