# Qefro Documentation (full)
> Complete Markdown export of https://docs.qefro.com for AI systems. Generated from the official Docusaurus sources. Prefer individual pages linked from /llms.txt when context is limited.
Generated: 2026-07-19
# Concepts (GEO)
# What is an AI Workspace?
Source: https://docs.qefro.com/docs/concepts/what-is-an-ai-workspace/
> An AI Workspace is an isolated AI environment with its own knowledge, instructions, tools, and conversations — the core unit of Qefro.
An **AI Workspace** is a scoped AI environment inside an organization. It owns its own **knowledge base**, **assistant instructions**, **Business Tools**, and **conversations**. Unlike a single shared chatbot, workspaces keep Support, HR, IT, and other teams from mixing policies, tools, and chat history.
In [Qefro](https://qefro.com), every Customer AI and Employee AI experience binds to one or more workspaces you configure in the [Admin Console](https://app.qefro.com).
## Short definition (citation-ready)
> An AI Workspace is an isolated context for retrieval-augmented assistants and tool calls: documents, instructions, connectors, and conversations stay inside that workspace unless you deliberately share them.
## Why AI Workspaces exist
Organizations rarely need “one bot for everything.” They need:
| Need | Workspace answer |
| --- | --- |
| Different audiences | Customer Support vs Internal HR |
| Different knowledge | Public FAQs vs confidential policy |
| Different tools | Order lookup vs payroll APIs |
| Different permissions | Widget visitors vs authenticated employees |
Without workspaces, a single chatbot index becomes a privacy and accuracy risk: internal docs leak into customer answers, or tools meant for staff become callable from a public widget.
## Core components
| Component | Role |
| --- | --- |
| **Knowledge** | Uploaded files, crawled sites, OCR — indexed for hybrid RAG |
| **Instructions** | Tone, language, refusal rules, product voice |
| **Business Tools** | REST / OpenAPI connectors with encrypted credentials |
| **Business Actions** | Runtime tool invocations during a conversation |
| **Conversations** | Channel-bound chat history for that workspace |
| **Channels** | Website widget, WhatsApp, Internal Portal |
## Architecture
```mermaid
flowchart TB
Org[Organization / tenant]
Org --> WS1[Workspace: Customer Support]
Org --> WS2[Workspace: HR]
Org --> WS3[Workspace: IT]
WS1 --> K1[Knowledge + hybrid RAG]
WS1 --> T1[Business Tools]
WS1 --> C1[Conversations]
Widget[Website Widget] --> WS1
WA[WhatsApp] --> WS1
Portal[Internal Portal] --> WS2
Portal --> WS3
```
## AI Workspace vs related ideas
| Concept | How it differs from an AI Workspace |
| --- | --- |
| **AI chatbot** | Often one bot + one knowledge dump; weak multi-team isolation |
| **Custom GPT / project** | Usually personal or single-team; not a multi-tenant org platform |
| **Helpdesk ticket bot** | Focused on tickets; may lack employee portal + general RAG workspaces |
| **Agent framework** | Code-first orchestration; Qefro workspaces are productized with Admin Console + channels |
See also: [AI Workspace vs AI Chatbot](/docs/concepts/ai-workspace-vs-ai-chatbot).
## How Qefro implements AI Workspaces
1. Sign up at [app.qefro.com](https://app.qefro.com) and create an **organization** (tenant).
2. Create workspaces for each use case (Support, HR, IT, …).
3. Ingest knowledge (`POST /api/v1/documents`) and configure instructions.
4. Attach [Business Tools](/docs/platform/business-tools) when the assistant must call APIs.
5. Bind channels: [website widget](/docs/platform/website-widget), [WhatsApp](/docs/platform/whatsapp), or [Internal Portal](/docs/platform/internal-portal).
Admin Console APIs expose workspaces under `/api/v1/org/workspaces`. Day-to-day console operations also use GraphQL on `api.qefro.com`.
## Workflow
## Best practices
- One primary audience per workspace (do not mix public FAQs with confidential HR).
- Prefer citations and refusals over guessing when knowledge is thin.
- Scope Business Tools to the minimum HTTP methods and paths required.
- Use Teams so Members only access granted Employee AI workspaces.
- Monitor analytics, feedbacks, and tool execution logs before expanding channels.
## Common misconceptions
| Myth | Reality |
| --- | --- |
| “An AI Workspace is just a chatbot skin.” | Workspaces isolate knowledge, tools, and conversations — not only UI. |
| “One workspace for the whole company is fine.” | Cross-team mixing increases leakage and wrong-tool risk. |
| “RAG alone is enough.” | Production assistants also need authz, SSRF controls, and identity forwarding for actions. |
## FAQ
For Admin Console workflows, APIs, and channel binding details, see the platform page [AI Workspaces](/docs/platform/ai-workspaces).
## Related topics
---
# AI Workspace vs AI Chatbot
Source: https://docs.qefro.com/docs/concepts/ai-workspace-vs-ai-chatbot/
> How AI Workspaces differ from traditional AI chatbots — isolation, tools, employee portals, and multi-tenant architecture.
**AI Workspace vs AI Chatbot** is the difference between a **scoped operating unit for assistants and actions** and a **conversational UI over one knowledge dump**. Chatbots answer questions. AI Workspaces organize knowledge, permissions, tools, and channels so customer and employee AI can run safely inside a company.
## Short definition (citation-ready)
> An AI chatbot is typically a conversational interface with a knowledge source. An AI Workspace is an isolated product unit — knowledge, instructions, tools, conversations, and channel bindings — designed for multi-team, multi-tenant use.
## Capability comparison
## When a chatbot is enough
Choose a simple chatbot when:
- One public FAQ site is the only surface
- No employee portal or internal tools are required
- No multi-team isolation or RBAC is needed
- You will not call privileged APIs from the assistant
## When you need an AI Workspace
Choose an AI Workspace platform when:
- Support, HR, and IT must not share one index
- Employees need a branded portal with workspace grants
- Assistants must call systems of record safely ([Business Actions](/docs/concepts/business-actions))
- You need hybrid RAG, citations, and audit-friendly tool logs
- You operate multi-tenant SaaS-style isolation ([Multi-tenant AI Architecture](/docs/concepts/multi-tenant-ai-architecture))
## Architecture contrast
```mermaid
flowchart LR
subgraph Chatbot["Typical chatbot"]
B[Bot] --> KB[One knowledge dump]
B --> UI[Chat UI]
end
subgraph Workspace["AI Workspace platform"]
Org[Organization]
Org --> WS[Workspaces]
WS --> K[Knowledge / hybrid RAG]
WS --> T[Business Tools]
WS --> Ch[Channels]
end
```
## How Qefro positions this
Qefro is an **AI Workspace Platform**, not a single-bot builder:
- [What is an AI Workspace?](/docs/concepts/what-is-an-ai-workspace)
- [Customer AI](/docs/platform/customer-ai) on widget + WhatsApp
- [Employee AI](/docs/platform/employee-ai) on Internal Portal
- [Business Actions](/docs/concepts/business-actions) via Business Tools
Vendor comparisons (Chatbase, Intercom, Zendesk, …) live under [Compare](/docs/compare/chatbase-vs-qefro).
## Evaluation workflow
## FAQ
Marketing one-liners blur these terms. When evaluating vendors, ask: What is the isolation unit? Who can call which tools? Is there an employee portal with RBAC?
## Related topics
---
# Customer AI vs Employee AI
Source: https://docs.qefro.com/docs/concepts/customer-ai-vs-employee-ai/
> Customer AI serves external users on website and WhatsApp; Employee AI serves organization members on the Internal Portal with RBAC.
**Customer AI** and **Employee AI** are the two audience modes of an AI Workspace Platform. Both can use the same underlying workspace technology (knowledge, tools, conversations), but they differ in **who** is talking, **where** the UI lives, and **what** identity and permissions apply.
## Short definition (citation-ready)
> Customer AI assists external users (visitors, shoppers, ticket askers) on public channels. Employee AI assists authenticated organization members on an internal portal with role- and workspace-scoped access.
## Side-by-side
| Dimension | Customer AI | Employee AI |
| --- | --- | --- |
| **Audience** | External customers / visitors | Organization members |
| **Primary surfaces** | Website widget, WhatsApp | Internal Portal (`*.qefro.com` or custom domain) |
| **Auth** | Widget token; optional `identify()` for end users | Email/password session JWT; Teams + workspace grants |
| **Knowledge** | Usually public or customer-safe docs | Often internal policies, runbooks, HR/IT |
| **Tools** | Order status, ticket create — careful scopes | Internal systems with stricter RBAC |
| **Risk if mixed** | Leaking internal docs to the public | Exposing customer tools without need |
## Architecture
```mermaid
flowchart TB
Org[Organization]
Org --> CWS[Customer Support workspace]
Org --> HWS[HR / IT workspaces]
CWS --> Widget[Website Widget]
CWS --> WA[WhatsApp]
HWS --> Portal[Internal Portal]
Member[Authenticated member] --> Portal
Visitor[Site visitor / WhatsApp user] --> Widget
Visitor --> WA
```
## Customer AI in Qefro
- Product page: [Customer AI](/docs/platform/customer-ai)
- Channels: [Website Widget](/docs/platform/website-widget) (`cdn.qefro.com/widget.js`), [WhatsApp](/docs/platform/whatsapp)
- Optional identity: [Identity Forwarding](/docs/platform/identity-forwarding) via `identify()` so Business Tools receive a verified end-user token
## Employee AI in Qefro
- Product page: [Employee AI](/docs/platform/employee-ai)
- Surface: [Internal Portal](/docs/platform/internal-portal)
- Access: [RBAC](/docs/platform/rbac) — Owner / Admin / Member; Members only see granted workspaces
- Branding & domains: [Branding](/docs/platform/branding), [Custom Domains](/docs/platform/custom-domains)
## Should they share a workspace?
| Approach | Use when |
| --- | --- |
| **Separate workspaces (recommended)** | Knowledge sensitivity differs (public FAQ vs internal HR) |
| **Shared workspace** | Rare — only when the corpus is intentionally identical and tools are safe for both audiences |
Use a Customer Support workspace for widget/WhatsApp and separate HR/IT workspaces for the Internal Portal. Shared indexes are a common source of accidental disclosure.
## Workflow
## FAQ
## Related topics
---
# What are Business Actions?
Source: https://docs.qefro.com/docs/concepts/business-actions/
> Business Actions are runtime AI invocations of Business Tools — authorized HTTPS calls with SSRF controls, identity forwarding, and execution logs.
A **Business Action** is what happens when an assistant **calls a Business Tool** during a conversation — for example looking up an order, creating a ticket, or reading account status from your system of record. Answers alone are not enough for many support and employee workflows; actions close the loop.
## Short definition (citation-ready)
> A Business Action is an authorized, logged runtime invocation of a configured Business Tool (REST/OpenAPI connector) during an AI conversation, subject to workspace scope, SSRF controls, and optional end-user identity forwarding.
## Business Actions vs Business Tools
| Term | Meaning |
| --- | --- |
| **Business Tool** | The connector definition: URL, method, auth credentials, schema |
| **Business Action** | One execution of that tool at conversation time |
Configure tools once; the model selects and runs actions when the dialog requires them.
## Why they matter for GEO and buyers
Search and AI assistants increasingly answer “can the AI *do* things, or only chat?” Business Actions are the product concept for:
- Order / shipment lookups
- Ticket or lead creation
- Internal runbook automation for Employee AI
- Any HTTPS API your organization already trusts
## Architecture
```mermaid
sequenceDiagram
participant User
participant Channel as Widget / WhatsApp
participant Qefro as Qefro runtime
participant Tool as Business Tool HTTPS API
User->>Channel: Message
Channel->>Qefro: Chat + workspace context
Qefro->>Qefro: RAG + tool selection
Qefro->>Tool: Authorized HTTPS (SSRF-safe)
Tool-->>Qefro: Result
Qefro-->>User: Answer with action outcome
Qefro->>Qefro: Execution log
```
Business Actions are not executed from the Internal Portal. Employees use the portal as a knowledge assistant (RAG / document Q&A). Live API actions remain on the Website Widget and WhatsApp until employee delegated authentication is available.
## Security properties (required for production)
| Control | Purpose |
| --- | --- |
| **Workspace binding** | Tools only exist inside a workspace |
| **Encrypted secrets** | Credentials stored encrypted at rest |
| **SSRF protections** | Block unsafe destinations / schemes |
| **Identity forwarding** | Optional end-user JWT/session to your API |
| **Execution logs** | Audit what was called and when |
| **Least privilege** | Prefer read-only methods in pilots |
Deep dive: [AI Agent Security](/docs/concepts/ai-agent-security) and [Secure Business Actions](/docs/guides/secure-business-actions).
## How Qefro implements Business Actions
1. Create a [Business Tool](/docs/platform/business-tools) under a workspace (REST, [OpenAPI import](/docs/guides/import-openapi), or [SDK Sync](/docs/guides/register-sdk-business-tools)).
2. Store credentials in the Admin Console (encrypted).
3. Test the tool before enabling it for the assistant.
4. On Customer AI, use [`identify()`](/docs/platform/identity-forwarding) when your API needs the end user.
5. Review tool execution logs after pilot traffic.
Platform reference: [Business Actions](/docs/platform/business-actions).
## Workflow
## Best practices
- Separate customer-facing tools from internal-only tools via workspaces.
- Never put long-lived admin secrets in the browser; use server-side tool credentials + optional end-user forwarding.
- Document idempotency for any write action the model can trigger.
- Fail closed: if authz fails, the assistant should explain limits — not invent success.
Treat every Business Action as production API traffic. Rate limits, auth failures, and PII in responses are your responsibility to design for.
## FAQ
## Related topics
---
# AI Knowledge Platform
Source: https://docs.qefro.com/docs/concepts/ai-knowledge-platform/
> An AI Knowledge Platform ingests documents, crawls, and OCR into workspace-isolated indexes for citation-backed RAG — the memory layer of Customer AI and Employee AI.
An **AI Knowledge Platform** is the system that turns your documents and sites into **retrievable, citable memory** for assistants. In Qefro it is workspace-scoped: each [AI Workspace](/docs/concepts/what-is-an-ai-workspace) has its own index so Support FAQs never silently merge with HR policy.
## Short definition (citation-ready)
> An AI Knowledge Platform ingests files and web content, chunks and indexes them (often with hybrid lexical + vector retrieval), and returns grounded passages so assistants can answer with citations inside an isolation boundary such as a workspace.
## What it includes
| Capability | Role |
| --- | --- |
| **Ingest** | Uploads, crawl jobs, OCR for scans/images |
| **Index** | Chunking, embeddings, lexical indexes |
| **Retrieve** | Hybrid search at question time ([Hybrid RAG](/docs/concepts/hybrid-rag)) |
| **Cite** | Point answers back to source passages |
| **Isolate** | Per-workspace corpora inside a tenant |
| **Govern** | Delete/re-ingest, access via RBAC on Employee AI |
## Architecture
```mermaid
flowchart LR
Docs[Documents / crawl / OCR] --> Ingest[Ingest pipeline]
Ingest --> Index[Workspace index]
Q[User question] --> Retrieve[Hybrid retrieval]
Index --> Retrieve
Retrieve --> LLM[Grounded generation]
LLM --> Answer[Answer + citations]
```
## Knowledge Platform vs “upload a PDF to a chatbot”
| Chatbot upload | AI Knowledge Platform |
| --- | --- |
| Convenient for demos | Built for ongoing ingest and re-index |
| Often one shared pile | Workspace (and tenant) isolation |
| Citations optional | Citations as a product expectation |
| Weak ops story | APIs, jobs, delete/replace, monitoring |
## How Qefro implements it
- Product page: [Knowledge Platform](/docs/platform/knowledge-platform)
- Upload / manage via Admin Console and `POST /api/v1/documents` on `api.qefro.com`
- Retrieval powers Customer AI (widget, WhatsApp) and Employee AI (Internal Portal)
- Isolation ties to [Organizations](/docs/platform/organizations) and workspaces
## Workflow
## Best practices
- Separate corpora by audience ([Customer AI vs Employee AI](/docs/concepts/customer-ai-vs-employee-ai)).
- Prefer fewer high-quality sources over noisy crawl-everything.
- Verify OCR quality for scans before relying on answers.
- Treat deletion and retention as security requirements, not afterthoughts.
## FAQ
For implementation detail (APIs, crawl, OCR), see [Knowledge Platform](/docs/platform/knowledge-platform). For retrieval mechanics, see [Hybrid RAG](/docs/concepts/hybrid-rag).
## Related topics
---
# Hybrid RAG
Source: https://docs.qefro.com/docs/concepts/hybrid-rag/
> Hybrid RAG combines lexical (BM25-style) and vector retrieval so AI assistants find exact terms and semantic matches — then ground answers with citations.
**Hybrid RAG** (Retrieval-Augmented Generation) mixes **lexical search** (exact tokens, SKUs, error codes, policy IDs) with **vector / semantic search** (paraphrases and conceptual similarity). The merged results ground the model so answers stay tied to your documents instead of free-form guessing.
## Short definition (citation-ready)
> Hybrid RAG retrieves supporting passages using both keyword-oriented and embedding-oriented search, fuses ranked results, and passes them to a language model to generate an answer — ideally with citations back to sources.
## Why hybrid beats “vectors only”
| Query type | Vectors alone | Lexical alone | Hybrid |
| --- | --- | --- | --- |
| “What is your refund policy?” | Strong | Medium | Strong |
| “Error E-4421 meaning” | Weak/medium | Strong | Strong |
| “SKU A12-900 warranty” | Weak | Strong | Strong |
| “How do I change billing email?” | Strong | Medium | Strong |
Enterprise corpora are full of **identifiers**. Pure semantic search misses them; pure keyword search misses paraphrase. Hybrid covers both.
## Architecture
```mermaid
flowchart TB
Q[User question] --> L[Lexical retriever]
Q --> V[Vector retriever]
L --> F[Fusion / re-rank]
V --> F
F --> CTX[Top passages]
CTX --> LLM[Grounded generation]
LLM --> A[Answer + citations]
```
## Hybrid RAG inside an AI Knowledge Platform
Hybrid RAG is the **retrieval engine**. An [AI Knowledge Platform](/docs/concepts/ai-knowledge-platform) wraps it with ingest, workspace isolation, OCR, and ops. In Qefro:
- Indexes are **per workspace** inside a tenant
- Customer AI and Employee AI both consume hybrid retrieval
- Citations help operators verify groundedness
Platform detail: [Knowledge Platform](/docs/platform/knowledge-platform).
## Quality loop
## Best practices
- Keep chunk sizes appropriate for your docs (too large → noisy; too small → broken identifiers).
- Re-index after major policy edits; do not rely on chat memory.
- Separate customer-safe and internal corpora ([Customer AI vs Employee AI](/docs/concepts/customer-ai-vs-employee-ai)).
- Pair RAG with [Business Actions](/docs/concepts/business-actions) only when live data is required — docs for policy, APIs for state.
## FAQ
For security of retrieval boundaries (tenant/workspace isolation), see [Multi-tenant AI Architecture](/docs/concepts/multi-tenant-ai-architecture) and [Tenant Isolation](/docs/security/tenant-isolation).
## Related topics
---
# AI Agent Security
Source: https://docs.qefro.com/docs/concepts/ai-agent-security/
> AI agent security covers tenant isolation, tool authorization, SSRF controls, encrypted secrets, identity forwarding, and audit logs for assistants that retrieve knowledge and take Business Actions.
**AI Agent Security** is the set of controls that keep assistants safe when they not only **read knowledge** but also **take actions**. Chat-only bots mainly risk bad answers. Agents that call APIs risk unauthorized data access, SSRF, secret leakage, and unaudited writes.
## Short definition (citation-ready)
> AI agent security is the practice of constraining retrieval and tool use with isolation boundaries, least-privilege credentials, network egress controls, identity propagation, and auditable execution — so assistants cannot become privileged backdoors.
## Threat model (practical)
| Risk | Example | Mitigations |
| --- | --- | --- |
| **Cross-tenant leakage** | Org A retrieves Org B docs | Tenant isolation, workspace indexes |
| **Cross-workspace leakage** | Customer widget reads HR PDFs | Separate workspaces; channel binding |
| **Over-privileged tools** | Public chat triggers refund API | Least privilege; separate tools; RBAC |
| **SSRF** | Tool URL points at cloud metadata | Allowlists, scheme/host checks |
| **Secret exposure** | API keys in browser or prompts | Encrypted server-side secrets |
| **Confused deputy** | Tool runs as admin, not end user | Identity forwarding (`identify()`) |
| **Unaudited actions** | Nobody knows what the bot changed | Execution + audit logs |
## Control layers
```mermaid
flowchart TB
subgraph Isolation
T[Tenant boundary]
W[Workspace boundary]
end
subgraph AuthZ
R[RBAC / Teams]
I[End-user identity forwarding]
end
subgraph Egress
S[Encrypted secrets]
N[SSRF-safe HTTPS]
end
subgraph Prove
L[Tool execution logs]
A[Audit trails]
end
User --> Isolation --> AuthZ --> Egress --> Prove
```
## How Qefro approaches agent security
| Area | Qefro capability |
| --- | --- |
| Tenant isolation | Organization boundary on `api.qefro.com` |
| Workspace isolation | Per-workspace knowledge and tools |
| Employee access | Owner / Admin / Member + Teams |
| Tools | Business Tools with encrypted credentials |
| Actions | Logged Business Actions, SSRF-aware egress |
| Customer identity | Widget `identify()` → tool headers |
| Docs | [Security overview](/docs/security/overview), [Tenant isolation](/docs/security/tenant-isolation), [Secrets](/docs/security/secrets), [Audit logs](/docs/security/audit-logs) |
Concept siblings: [Business Actions](/docs/concepts/business-actions), [Multi-tenant AI Architecture](/docs/concepts/multi-tenant-ai-architecture).
## Hardening workflow
## Best practices
- Treat the model as **untrusted input** to your tool layer — validate arguments server-side.
- Prefer idempotent writes and human approval for irreversible actions.
- Do not paste production secrets into prompts, tickets, or browser JS.
- Run a red-team script of prompt-injection attempts against tool-enabled workspaces.
Prompt injection is not solved by “better wording” alone. Assume hostile content in uploaded docs and user messages when tools are enabled.
## FAQ
## Related topics
---
# Multi-tenant AI Architecture
Source: https://docs.qefro.com/docs/concepts/multi-tenant-ai-architecture/
> Multi-tenant AI architecture isolates organizations (tenants) and AI Workspaces so knowledge, tools, conversations, and billing never cross customer boundaries.
**Multi-tenant AI architecture** is how a SaaS AI platform serves many organizations from one control plane without mixing their data, tools, or conversations. In Qefro the top boundary is the **organization (tenant)**; inside it, **AI Workspaces** isolate teams and use cases.
## Short definition (citation-ready)
> Multi-tenant AI architecture enforces hard isolation between customer organizations — and usually softer isolation between workspaces inside an organization — across knowledge indexes, tool credentials, conversations, and administrative APIs.
## Why it matters
Without tenancy:
- Customer A’s documents could appear in Customer B’s answers
- Tool credentials could be invoked across orgs
- Analytics and billing would be unreliable
- Enterprise buyers cannot pass security review
Tenancy is therefore both a **security** and a **product** requirement for AI Workspace platforms.
## Layered model
| Layer | Qefro unit | Isolates |
| --- | --- | --- |
| **Platform** | Qefro cloud (`api.qefro.com`, `app.qefro.com`) | Shared infra, per-tenant logical isolation |
| **Tenant** | Organization | Users, billing, branding, widget token |
| **Workspace** | AI Workspace | Knowledge, tools, conversations |
| **Access** | Teams + RBAC | Which members see which Employee AI workspaces |
| **Channel** | Widget / WhatsApp / Portal | How external or internal users attach |
```mermaid
flowchart TB
Platform[Qefro platform]
Platform --> OrgA[Org A tenant]
Platform --> OrgB[Org B tenant]
OrgA --> WSA1[Workspace Support]
OrgA --> WSA2[Workspace HR]
OrgB --> WSB1[Workspace Support]
WSA1 -.->|no shared index| WSB1
```
## Request path (conceptual)
1. Authenticate (user JWT, widget token, or channel webhook).
2. Resolve **tenant** from the credential / host.
3. Resolve **workspace** from channel binding or portal selection.
4. Retrieve only from that workspace’s knowledge index.
5. Allow only that workspace’s Business Tools.
6. Emit logs attributed to tenant + workspace (+ actor when known).
Security deep dive: [Tenant Isolation](/docs/security/tenant-isolation).
## Single-tenant / enterprise variants
Some enterprises require private deployment. Conceptually the isolation model stays the same; the difference is **where** the control/data planes run. See [Deployment](/docs/platform/deployment) and [Production Deployment](/docs/guides/production-deployment).
## Design workflow
## FAQ
Product entry points: [Organizations](/docs/platform/organizations), [AI Workspaces](/docs/platform/ai-workspaces), [Security Overview](/docs/security/overview).
## Related topics
---
# Getting Started
# Installation
Source: https://docs.qefro.com/docs/getting-started/installation/
> Create a Qefro organization at app.qefro.com — cloud hosted, no local RAG stack required.
**Installation** for Qefro cloud means signing up at [app.qefro.com](https://app.qefro.com), verifying email, and creating an organization (tenant). You do not install vector databases, LLM gateways, or RAG infrastructure yourself.
## Introduction
Qefro is a multi-tenant SaaS platform. Production hosts:
| Surface | URL |
| --- | --- |
| Marketing | https://qefro.com |
| Admin Console | https://app.qefro.com |
| API | https://api.qefro.com |
| Widget CDN | https://cdn.qefro.com/widget.js |
| Internal Portal | `your-company.qefro.com` (or custom domain) |
## Why it exists
Teams need Customer AI and Employee AI without operating embedding pipelines, hybrid search, or tool-execution sandboxes.
## Concepts
- **Organization / tenant** — billing and isolation boundary created at signup
- **Admin Console** — configure workspaces, knowledge, Business Tools, channels, RBAC
- **Workspace** — isolated knowledge + tools + conversations (e.g. Customer Support, HR)
- **Plan** — Free, Starter, Growth, Enterprise (Razorpay billing)
## Architecture
```mermaid
flowchart LR
Signup[app.qefro.com signup] --> Org[Organization / tenant]
Org --> Console[Admin Console]
Console --> WS[Workspaces]
WS --> API[api.qefro.com]
API --> Exp[Widget / Portal / WhatsApp]
```
## Workflow
## Code examples
```bash
# Health (no auth)
curl -sS https://api.qefro.com/health
# Ready (dependencies)
curl -sS https://api.qefro.com/ready
```
```typescript
const res = await fetch('https://api.qefro.com/health');
console.log(await res.text());
```
## Best practices
- Use a real company email for ownership and billing
- Enable MFA / strong passwords on Owner accounts before connecting production APIs
- Prefer separate workspaces for Customer Support vs internal HR/IT
## Security notes
Never put long-lived Business Tool secrets or Admin Console JWTs in website JavaScript. Widget embeds use a publishable widget token; tool credentials stay encrypted server-side.
## FAQ
## Related topics
---
# Quick Start
Source: https://docs.qefro.com/docs/getting-started/quick-start/
> Create a workspace, upload documents, test chat, then embed the website widget.
**Quick Start** gets you from an empty organization to cited answers in the Admin Console, then optionally to a live website widget.
## Introduction
In Qefro, knowledge is scoped to a **workspace**. Customer AI (widget / WhatsApp) and Employee AI (Internal Portal) both bind to workspaces you configure in the Admin Console.
## Why it exists
Validating retrieval quality before connecting Business Tools or public channels avoids shipping an inaccurate assistant.
## Concepts
- **Document** — PDF, DOCX, Markdown, TXT, or crawled pages; chunked and indexed with hybrid BM25 + vector retrieval
- **Citation** — answers include source references; the model is instructed to refuse when no relevant source exists
- **Widget token** — publishable embed key from **Widget** in the Admin Console (rotatable)
## Architecture
```mermaid
sequenceDiagram
participant You
participant Console as Admin Console
participant API as api.qefro.com
participant RAG as Knowledge Platform
You->>Console: Create workspace
You->>Console: Upload PDF / crawl site
Console->>API: GraphQL + POST /api/v1/documents
API->>RAG: Chunk, embed, index
You->>Console: Test chat
API->>RAG: Hybrid retrieve
RAG-->>You: Answer + citations
```
## Workflow
## Code examples
Website embed (values come from Admin Console → Widget):
```html
```
## Best practices
- Start with 5–20 high-quality docs, not a full drive dump
- Keep customer-facing and employee knowledge in separate workspaces
- Test refusal: ask something outside the corpus
## Security notes
Workspace knowledge is isolated. HR documents must not answer Customer Support widget questions.
## FAQ
## Related topics
---
# Platform
# AI Workspaces
Source: https://docs.qefro.com/docs/platform/ai-workspaces/
> Isolated AI contexts in a Qefro organization — knowledge, instructions, Business Tools, and conversations.
An **AI Workspace** is a scoped AI environment inside a Qefro **organization (tenant)**. Each workspace has its own knowledge base, assistant instructions, Business Tools, and conversations. Customer AI (website widget, WhatsApp) and Employee AI (Internal Portal) bind to workspaces you configure in the Admin Console.
## Introduction
In the product data model:
- **Organization / tenant** — top-level isolation and billing boundary (`app.qefro.com` signup)
- **Workspace** — team/use-case boundary (Customer Support, HR, IT, …)
- **Team (org RBAC)** — grants Members access to specific workspaces
Admin Console APIs expose workspaces under `/api/v1/org/workspaces` (list/get) and GraphQL for day-to-day console operations.
## Why it exists
Mixing customer FAQs with internal HR policy causes inaccurate answers and privacy risk. Workspaces make isolation the default: retrieval and Business Actions stay inside the selected workspace.
## Concepts
| Term | Meaning in Qefro |
| --- | --- |
| Organization | Tenant: users, billing, branding, widget token |
| Workspace | Isolated knowledge + tools + conversations |
| Instructions | System guidance (tone, language, refusal) |
| Business Tools | REST/OpenAPI connectors bound to a workspace |
| Experience | Widget, Internal Portal, or WhatsApp → workspace |
## Architecture
```mermaid
flowchart TB
Org[Organization / tenant]
Org --> WS1[Workspace: Customer Support]
Org --> WS2[Workspace: HR]
Org --> WS3[Workspace: IT]
WS1 --> K1[Knowledge index]
WS1 --> T1[Business Tools]
WS1 --> C1[Conversations]
Widget[Website Widget] --> WS1
Portal[Internal Portal] --> WS2
WA[WhatsApp] --> WS1
```
## Workflow
## Code examples
```html
```
```bash
curl -sS \
-H "Authorization: Bearer $USER_JWT" \
https://api.qefro.com/api/v1/org/workspaces
```
## Best practices
- One primary audience per workspace (customers vs employees)
- Start narrow on knowledge quality before bulk imports
- Cross-test: ask Support questions against HR knowledge to prove isolation
- Assign a human owner per workspace
## Security notes
Do not attach privileged write Business Tools to a public Customer AI workspace without identity forwarding (`identify()`) and least-privilege scopes.
## FAQ
## Related topics
---
# Customer AI
Source: https://docs.qefro.com/docs/platform/customer-ai/
> External assistants on the website widget and WhatsApp, grounded in a Support workspace with optional Business Tools and identify().
**Customer AI** is Qefro’s external assistant experience for end customers — primarily the **Website Widget** and **WhatsApp** (Growth+), bound to a workspace’s knowledge and Business Tools.
## Short definition (citation-ready)
> Customer AI serves external users on public channels using a publishable widget token (and Meta WhatsApp webhooks), retrieving only from the bound AI Workspace.
## Channels
| Channel | Host / entry | Guide |
| --- | --- | --- |
| Website widget | `cdn.qefro.com/widget.js` | [Deploy Website Widget](/docs/guides/deploy-website-widget) |
| WhatsApp | Meta → `api.qefro.com` webhook | [Deploy WhatsApp AI](/docs/guides/deploy-whatsapp-ai) |
Compare audiences: [Customer AI vs Employee AI](/docs/concepts/customer-ai-vs-employee-ai).
## Architecture
```mermaid
flowchart LR
Visitor --> Widget[Website widget]
Visitor --> WA[WhatsApp]
Widget --> API[api.qefro.com]
WA --> API
API --> WS[Support workspace]
WS --> RAG[Hybrid RAG]
WS --> Tools[Business Tools]
```
## Configure once
1. Create a **Support** workspace (customer-safe docs only).
2. Ingest FAQs; validate citations.
3. Embed the widget with token + workspace id.
4. Optionally add WhatsApp on Growth+.
5. Optionally add read-only Business Tools + [`identify()`](/docs/platform/identity-forwarding).
Playbook: [Build AI Customer Support](/docs/guides/build-ai-customer-support).
## Workflow
Never bind a public channel to an internal HR/IT workspace. Isolation failures become public disclosures.
## FAQ
## Related topics
---
# Employee AI
Source: https://docs.qefro.com/docs/platform/employee-ai/
> Internal assistants on the branded Internal Portal for organization members — Teams, RBAC, and workspace-scoped knowledge.
**Employee AI** is Qefro’s internal assistant experience. Employees sign in to the **Internal Portal** (`your-company.qefro.com` or a custom domain) and chat with workspaces their **Teams** grant.
## Short definition (citation-ready)
> Employee AI authenticates organization members and authorizes workspace access through RBAC and Teams, unlike Customer AI which uses public channel tokens.
## How it differs from Customer AI
| | Customer AI | Employee AI |
| --- | --- | --- |
| Users | External | Org members |
| Surface | Widget / WhatsApp | Internal Portal |
| Auth | Widget token (+ optional identify) | Session JWT |
| Access | Workspace id in embed | Team grants |
Concept: [Customer AI vs Employee AI](/docs/concepts/customer-ai-vs-employee-ai).
## Architecture
```mermaid
flowchart TB
Member[Member login] --> Portal[Internal Portal]
Portal --> RBAC[Role + Teams]
RBAC --> HR[HR workspace]
RBAC --> IT[IT workspace]
Admin[Admin Console] --> HR
Admin --> IT
```
## Workflow
Playbooks: [Create Employee AI](/docs/guides/create-employee-ai), [Configure RBAC](/docs/guides/configure-rbac).
Employee AI is not merely “Customer AI behind login.” Without Teams/grants, you either overshare workspaces or block users incorrectly.
## FAQ
## Related topics
---
# Knowledge Platform
Source: https://docs.qefro.com/docs/platform/knowledge-platform/
> Document ingest, crawl, OCR, hybrid BM25+vector retrieval, citations, and workspace isolation.
The **Knowledge Platform** indexes organizational content for retrieval-augmented generation (RAG). Uploads and crawls are chunked, embedded, and retrieved with **hybrid BM25 + vector** search. Answers include **citations**; the assistant is guided to refuse when no relevant source exists.
## Introduction
Ingest paths in the real API:
- `POST /api/v1/documents` — multipart upload (quota: `check_documents_limit`)
- `POST /api/v1/documents/text` — create from raw text
- `POST /api/v1/documents/:id/reindex` — rebuild index for a document
- GraphQL mutations for console workflows including **website crawl**
- `GET /api/v1/documents/:id/view` — authorized document view
Supported formats include PDF, DOCX, Markdown, TXT; OCR covers scans/images. Multilingual retrieval supports EN, AR, TA, HI and more.
## Why it exists
Customer AI and Employee AI must share one high-quality retrieval stack with hard **workspace isolation**.
## Concepts
- **Document / chunk / embedding** — indexed units
- **Hybrid retrieval** — lexical + vector
- **Citation** — source attribution in answers
- **Isolation** — workspace-scoped indexes
## Architecture
```mermaid
flowchart LR
Upload[Upload / Crawl / OCR] --> Chunk[Chunk]
Chunk --> Index[Hybrid index]
Query[User question] --> Retrieve[Retrieve]
Index --> Retrieve
Retrieve --> Gen[Generate + cite]
```
## Workflow
## Code examples
```bash
curl -sS -X POST \
-H "Authorization: Bearer $USER_JWT" \
-F "file=@policy.pdf" \
-F "workspace_id=$WORKSPACE_ID" \
https://api.qefro.com/api/v1/documents
```
## Best practices
- Separate customer vs employee corpora by workspace
- Re-test after every major document delete/replace
- Prefer crawl allowlists over unbounded domains
## Security notes
Deleting a document removes associated chunks/embeddings. Confirm before destructive operations in production workspaces.
## FAQ
## Related topics
---
# Business Actions
Source: https://docs.qefro.com/docs/platform/business-actions/
> Runtime AI invocation of Business Tools under authorization, SSRF controls, and execution logs.
A **Business Action** is the runtime execution of a **Business Tool** during a conversation — for example looking up an order or creating a ticket in your system of record.
## Introduction
Flow in production:
1. User message arrives (Website Widget or WhatsApp; Internal Portal is knowledge-only in V1)
2. Assistant retrieves workspace knowledge (hybrid RAG)
3. When appropriate, the model selects an allowed tool in that workspace (customer channels only)
4. Qefro authorizes the call, performs SSRF-safe HTTPS egress, and records an execution log
5. Result is folded into the assistant reply
### Channel support (V1)
| Channel | Business Tool execution |
| --- | --- |
| Website Widget | ✓ Supported |
| WhatsApp | ✓ Supported |
| Internal Portal | ✗ Not supported |
Internal Portal requests that would require a Business Tool receive a structured `BUSINESS_TOOLS_NOT_SUPPORTED` response. Knowledge search and RAG continue to work normally.
Future Portal support may use enterprise SSO, OAuth On-Behalf-Of, identity federation, employee identity delegation, and JWT forwarding — without removing the existing channel gate.
## Why it exists
Answers without actions force users to leave chat and dig through portals. Actions without isolation are unsafe. Qefro combines both under workspace + RBAC boundaries.
## Concepts
- **Tool selection** — only tools attached to the active workspace
- **Identity** — optional end-user forwarding via `identify()` on the widget
- **Execution log** — `GET /api/v1/tools/:id/logs`
- **Failure modes** — tool errors surface safely; they must not leak secrets
## Architecture
```mermaid
sequenceDiagram
participant User
participant AI as Qefro AI
participant Policy as AuthZ / SSRF
participant Tool as Customer API
User->>AI: "Where is order 123?"
AI->>AI: Retrieve knowledge
AI->>Policy: Authorize tool call
Policy->>Tool: HTTPS REST
Tool-->>AI: Payload
AI-->>User: Answer with live data
```
## Workflow
## Code examples
```bash
# Inspect recent executions
curl -sS -H "Authorization: Bearer $USER_JWT" \
https://api.qefro.com/api/v1/tools/$TOOL_ID/logs
```
## Best practices
- Separate “customer-safe” tools from “admin-only” tools via workspaces
- Prefer idempotent reads for auto-invoked actions
- Document expected side effects for write tools
## Security notes
Treat every new tool like a production integration: SSRF validation, encrypted secrets, and review after OpenAPI reimport.
## FAQ
## Related topics
---
# Business Tools
Source: https://docs.qefro.com/docs/platform/business-tools/
> REST, OpenAPI, and SDK connectors that power Business Actions — encrypted credentials, signed webhooks, test, and logs.
**Business Tools** are workspace-scoped connectors the assistant can invoke as **Business Actions**. There are two implementation paths:
| Path | How you add tools | Credentials |
| --- | --- | --- |
| **REST / OpenAPI** | Manual tool or OpenAPI import | Encrypted API key / bearer on the tool |
| **SDK** | `@qefro-ai/backend` / `qefro-backend-sdk` handlers + Sync Tools | Connection signing secret; customer auth in your code |
Qefro does not become your CRM/ERP — tools call *your* systems of record.
## Introduction
Admin Console → **Business Tools** (REST / OpenAPI / SDK Connections tabs). REST surface (authenticated with the user’s Admin Console JWT):
| Method | Path |
| --- | --- |
| GET/POST | `/api/v1/workspaces/:workspace_id/integrations` |
| POST | `/api/v1/workspaces/:workspace_id/integrations/import/preview` |
| POST | `/api/v1/workspaces/:workspace_id/integrations/import/preview/upload` |
| POST | `/api/v1/workspaces/:workspace_id/integrations/import/apply` |
| GET/PATCH/DELETE | `/api/v1/integrations/:id` |
| POST | `/api/v1/integrations/:id/reimport` |
| GET/POST | `/api/v1/workspaces/:workspace_id/tools` |
| GET/PATCH/DELETE | `/api/v1/tools/:id` |
| POST | `/api/v1/tools/:id/test` |
| GET | `/api/v1/tools/:id/logs` |
| GET/POST | `/api/v1/org/sdk-connections` |
| PATCH/DELETE | `/api/v1/org/sdk-connections/:id` |
| POST | `/api/v1/org/sdk-connections/:id/test` |
| POST | `/api/v1/org/sdk-connections/:id/sync-tools` |
Plan limits (from domain `PlanDefinition.business_tools_limit`):
| Plan | Business Tools |
| --- | --- |
| Free | 1 |
| Starter | 5 |
| Growth / Enterprise | Unlimited (`-1`) |
## Why it exists
Most chatbots only answer from documents. Qefro also executes configured actions (order status, ticket create, …) under RBAC, SSRF protections, and execution logs.
## Concepts
- **Integration** — connector grouping (REST, OpenAPI import, or auto-created `SDK: {name}`)
- **Tool** — invocable operation (`implementation_kind`: `rest` or `sdk`)
- **SDK Connection** — org webhook + signing secret for `@qefro-ai/backend` / `qefro-backend-sdk`
- **Execution log** — audit trail for tool runs (`/api/v1/tools/:id/logs`)
- **Test** — `POST /api/v1/tools/:id/test` (rate-limited)
## Business Tool Execution (channels)
| Channel | Status |
| --- | --- |
| **Website Widget** | Supported |
| **WhatsApp** | Supported |
| **Internal Portal** | Not supported (V1) |
**Reason:** Internal Portal Business Tool execution requires delegated employee authentication, enterprise identity integration, and user authorization models, which are planned for a future release.
Knowledge search, RAG, document Q&A, AI assistance, and internal documentation remain fully supported in the Internal Portal. The Internal Portal stays an AI Knowledge Assistant in V1.
Admin Console **Test Tool** continues to work for configuring connectors — that path is not a chat channel.
## Architecture
```mermaid
flowchart TB
OpenAPI[OpenAPI import] --> Integration
REST[Manual REST tool] --> Tool
SDK[SDK Sync Tools] --> Integration
Integration --> Tool
Tool --> Kind{implementation_kind}
Kind -->|rest| Secrets[Encrypted API credentials]
Kind -->|sdk| Webhook[Signed org webhook]
Secrets --> Exec[ToolExecutor]
Webhook --> Exec
Exec --> Logs[Execution logs]
```
## Workflow
## Code examples
```bash
# List tools for a workspace
curl -sS -H "Authorization: Bearer $USER_JWT" \
https://api.qefro.com/api/v1/workspaces/$WORKSPACE_ID/tools
# Test a tool
curl -sS -X POST -H "Authorization: Bearer $USER_JWT" \
https://api.qefro.com/api/v1/tools/$TOOL_ID/test \
-H 'Content-Type: application/json' \
-d '{}'
```
## Best practices
- Prefer read-only tools during pilots
- Re-import OpenAPI after upstream API changes (`/reimport`)
- Re-Sync SDK tools after you add or rename handlers
- Keep customer-facing tools separate from privileged internal tools (different workspaces)
## Security notes
Outbound tool URLs and SDK webhooks are SSRF-validated (HTTPS, blocked private/link-local targets). Do not disable these controls for convenience.
MCP connectors are on the roadmap — not required for REST/OpenAPI/SDK today.
## FAQ
## Related topics
---
# Internal Portal
Source: https://docs.qefro.com/docs/platform/internal-portal/
> The employee web app for Employee AI — default *.qefro.com host, branding bootstrap, RBAC-scoped workspaces, and optional custom domains.
The **Internal Portal** is the employee-facing web app for Employee AI. Default host: `https://{tenantSlug}.qefro.com`. Optional custom domains terminate via Cloudflare.
## Short definition (citation-ready)
> The Internal Portal is the authenticated UI where organization members select granted AI Workspaces and chat with Employee AI.
## Bootstrap
Public branding for the portal shell:
```bash
curl -sS "https://api.qefro.com/api/v1/public/tenant-branding?slug=YOUR_SLUG"
```
Authenticated chat and workspace lists require a Member/Admin/Owner session. See [Platform Authentication](/docs/platform/authentication).
## Architecture
```mermaid
flowchart LR
DNS[tenantSlug.qefro.com or custom domain] --> Portal
Portal --> Branding[Public branding]
Portal --> Auth[Member session]
Auth --> Workspaces[Granted workspaces]
Workspaces --> Chat[Employee AI chat]
```
## Workflow
## FAQ
## Related topics
---
# Website Widget
Source: https://docs.qefro.com/docs/platform/website-widget/
> Embed Customer AI with cdn.qefro.com/widget.js, workspace binding, WebSocket chat, and identify().
The **Website Widget** is Qefro’s embeddable Customer AI chat. It loads from `https://cdn.qefro.com/widget.js` (or your configured CDN), authenticates with a **publishable widget token**, and streams replies over WebSocket (`/ws/chat`) with HTTP fallback (`POST /api/v1/widget/chat`).
## Introduction
Configure appearance and copy the embed snippet from **Admin Console → Widget**. Select a **workspace** so the live preview and embed `data-workspace-id` stay aligned.
Supported surfaces in the widget implementation:
- Text chat with streaming
- Optional lead capture
- Message feedback
- Human handoff / ticket triggers
- Voice STT/TTS via `/api/v1/widget/stt` and `/api/v1/widget/tts`
- `setContext()` for page/product context
- `identify()` for end-user identity (Business Tools)
## Why it exists
Customer AI must ship on your website without hosting RAG infra. The widget is the public channel; knowledge and tools stay on `api.qefro.com` under your tenant.
## Concepts
| Concept | Detail |
| --- | --- |
| Widget token | Publishable embed key; rotatable in Admin Console |
| `data-endpoint` | Usually `https://api.qefro.com` |
| `data-workspace-id` | Binds chat to a workspace knowledge/tools set |
| Visitor session | Continuity cookie/header separate from `identify()` |
| End-user identity | Host-owned JWT/session via `identify()` |
## Architecture
```mermaid
sequenceDiagram
participant Site as Your website
participant CDN as cdn.qefro.com
participant API as api.qefro.com
Site->>CDN: Load widget.js
Site->>API: WS /ws/chat?token=WIDGET_TOKEN
Note over Site,API: Optional identify() → X-End-User-Token / WS fields
API-->>Site: Streamed assistant tokens + citations
```
## Workflow
.'},
{title: 'Optional identify', description: 'Call widget.identify() after your app login.'},
{title: 'Test', description: 'Anonymous + authenticated flows; rotate token if leaked.'},
]}
/>
## Code examples
```html
```
```bash
npm install @qefro-ai/widget
```
```javascript
const widget = new Widget({
token: 'YOUR_WIDGET_TOKEN',
endpoint: 'https://api.qefro.com',
theme: 'auto',
position: 'bottom-right',
workspaceId: 'YOUR_WORKSPACE_ID',
});
widget.open();
// Page context — NOT identity
widget.setContext({ page: '/checkout', productId: 'ABC123' });
// Authenticated end user — for Business Tools
widget.identify({
id: user.id,
email: user.email,
name: user.name,
auth: { mode: 'jwt', token: userJwt },
});
// Refresh JWT without restarting
widget.setAuthToken(newJwt);
// Logout
await widget.clearIdentity();
```
Identity transport (real widget behavior):
- JWT mode → HTTP header `X-End-User-Token`, WebSocket field `endUserToken`
- Session mode → `X-End-User-Session` / `endUserSession`
- Profile fields (`id`, `email`, `name`, `authMode`) go in the request body — **tokens are never placed in the JSON body**
## Best practices
- Always set `data-workspace-id` for production embeds
- Call `identify()` only after your own auth succeeds
- Rotate the widget token if it leaks; update every embed
- Use `clearIdentity()` on logout
## Security notes
The widget token is publishable but still site-scoped. Do not treat it as a server API key. Business Tool secrets stay encrypted in Qefro; never embed them in the page.
## FAQ
## Related topics
---
# WhatsApp
Source: https://docs.qefro.com/docs/platform/whatsapp/
> Customer AI over Meta Cloud API — webhook verify/incoming on api.qefro.com, Growth+ entitlement, and Support workspace binding.
**WhatsApp** connects Meta Cloud API messaging to a Qefro Customer AI workspace. Availability: **Growth+**.
## Short definition (citation-ready)
> Qefro WhatsApp Customer AI receives Meta Cloud API webhooks at `api.qefro.com`, runs the bound workspace’s RAG/tools, and sends replies back through Meta.
## API routes
| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/api/v1/whatsapp/webhook` | Meta verification challenge |
| POST | `/api/v1/whatsapp/webhook` | Inbound messages |
Tenant credentials and workspace mapping are configured in Admin Console (encrypted). Confirm exact field names in the console UI.
## Architecture
```mermaid
sequenceDiagram
participant U as WhatsApp user
participant M as Meta Cloud API
participant Q as api.qefro.com
participant W as Support workspace
U->>M: Message
M->>Q: Webhook POST
Q->>W: RAG / tools
W-->>Q: Reply
Q->>M: Send message
M-->>U: Delivery
```
## Workflow
Follow the full playbook: [Deploy WhatsApp AI](/docs/guides/deploy-whatsapp-ai).
WhatsApp threads often contain PII. Align retention, tools, and human escalation with your privacy policy before broad rollout.
## FAQ
## Related topics
---
# Platform Authentication
Source: https://docs.qefro.com/docs/platform/authentication/
> How Admin Console users, Internal Portal members, widget tokens, and APIs authenticate to Qefro.
**Authentication** in Qefro depends on the surface:
| Surface | Mechanism |
| --- | --- |
| Admin Console / Internal Portal users | Email+password (OTP verify on signup), session JWT |
| Website Widget | Publishable **widget token** (`Authorization: Bearer` / `?token=`) |
| End-user identity for tools | Host JWT/session via `identify()` headers |
| Super Admin | Separate `/api/v1/admin/auth/login` |
| GraphQL | Same user JWT on `POST /graphql` |
| Metrics | Optional `METRICS_AUTH_TOKEN` bearer when not public |
## Introduction
User auth routes live under the API (REST + GraphQL). Abuse controls rate-limit login/OTP/forgot/reset (e.g. login ~20 / 15 min per email). Sessions can be listed and revoked (`/api/v1/me/sessions`, org admin session revoke).
## Why it exists
Customer AI, Employee AI, and Admin Console have different trust levels. Mixing them would either over-expose tools or block legitimate embeds.
## Concepts
- **User JWT** — org member session for console/portal/REST
- **Widget token** — site embed key; rotatable
- **End-user token** — your customer’s JWT/session for Business Tools
- **Super Admin** — platform operator, not tenant Owner
## Architecture
```mermaid
flowchart TB
Console[Admin Console] --> UserJWT[User JWT]
Portal[Internal Portal] --> UserJWT
UserJWT --> GQL[POST /graphql]
UserJWT --> REST[REST /api/v1/*]
Widget[Website Widget] --> WToken[Widget token]
WToken --> WS["/ws/chat"]
Widget --> Identify[identify JWT/session]
Identify --> Tools[Business Tool egress]
```
## Workflow
## Code examples
```bash
# Health is public
curl -sS https://api.qefro.com/health
# Authenticated REST example
curl -sS -H "Authorization: Bearer $USER_JWT" \
https://api.qefro.com/api/v1/org/roles
```
## Best practices
- Never put User JWTs in the website widget snippet
- Use `identify()` only for customer end users, not to impersonate org Admins
- Review org audit logs after role changes
## Security notes
Super Admin credentials are platform-level. Tenant Owners cannot perform super-admin actions; Admins cannot transfer ownership or delete the Owner.
## FAQ
## Related topics
---
# Identity Forwarding
Source: https://docs.qefro.com/docs/platform/identity-forwarding/
> Forward verified end-user identity into Business Tools with widget.identify().
**Identity Forwarding** lets your host application tell Qefro who the website visitor is, so Business Actions can call your APIs in that user’s context. Qefro does **not** replace your auth system — you own JWT/session issuance.
## Introduction
Implemented in `@qefro-ai/widget` via:
- `widget.identify({ id, email?, name?, auth?: { mode, token } })`
- `widget.setAuthToken(jwt)` — refresh without restart
- `widget.clearIdentity()` — clears local identity and notifies `POST /api/v1/widget/identity/clear`
Auth modes:
| Mode | Token transport |
| --- | --- |
| `jwt` | Header `X-End-User-Token` / WS `endUserToken` |
| `session` | Header `X-End-User-Session` / WS `endUserSession` |
| `none` | Profile only (id/email/name) — no bearer secret |
## Why it exists
Order lookup, ticket creation, and account mutations must not run as a shared service account when the end user is logged into your product.
## Concepts
- **Host-owned identity** — your IdP / session store
- **Forwarded claims** — id, email, name + auth material for tool HTTP calls
- **Visitor session** — separate continuity key; clearing identity does not wipe chat history by default
## Architecture
```mermaid
sequenceDiagram
participant App as Your app
participant Widget as Qefro Widget
participant API as api.qefro.com
participant Tool as Your REST API
App->>Widget: identify(id, jwt)
Widget->>API: Chat + X-End-User-Token
API->>Tool: Business Tool call with forwarded identity
Tool-->>API: Authorized response
API-->>Widget: Grounded answer / action result
```
## Workflow
## Code examples
```javascript
widget.identify({
id: user.id,
email: user.email,
name: user.name,
auth: {
mode: 'jwt',
token: userJwt, // from YOUR auth system
},
});
// Later
widget.setAuthToken(refreshedJwt);
await widget.clearIdentity();
```
Anonymous visitors: **do not** call `identify()`.
## Best practices
- Use a stable opaque user id (not email alone) as `id`
- Keep JWT lifetimes short; refresh with `setAuthToken`
- Scope Business Tools to least privilege when identity is present
## Security notes
Never put end-user tokens in `setContext()`. Context is product/page metadata; identity is a separate API (`identify`).
Tokens are sent on headers / WebSocket auth fields. They are not duplicated into the public identity JSON body.
## FAQ
## Related topics
---
# Organizations
Source: https://docs.qefro.com/docs/platform/organizations/
> The organization (tenant) is Qefro’s top-level account boundary for members, workspaces, billing, branding, and channels.
An **Organization** (tenant) is the top-level Qefro account created at signup on [app.qefro.com](https://app.qefro.com). It owns members, workspaces, billing, branding, widget token, and channel configuration.
## Short definition (citation-ready)
> A Qefro organization is the multi-tenant isolation and billing boundary. All AI Workspaces, Teams, and channel credentials belong to exactly one organization.
## What an organization owns
| Asset | Notes |
| --- | --- |
| Members + roles | Owner / Admin / Member |
| Teams | Workspace grants for Employee AI |
| AI Workspaces | Knowledge, tools, conversations |
| Billing | Razorpay plans and entitlements |
| Widget token | Publishable Customer AI embed key |
| Branding | Portal/widget appearance |
| Channels | WhatsApp and related configs |
| Custom domains | Portal hostnames |
## Architecture
```mermaid
flowchart TB
Org[Organization / tenant]
Org --> Members
Org --> Teams
Org --> WS[Workspaces]
Org --> Billing
Org --> Branding
Org --> Channels
WS --> Knowledge
WS --> Tools
```
Concept: [Multi-tenant AI Architecture](/docs/concepts/multi-tenant-ai-architecture). Security: [Tenant Isolation](/docs/security/tenant-isolation).
## Lifecycle
## Best practices
- One legal customer / billing entity → one organization
- Use a separate staging organization for experiments when feasible
- Limit Owners; document break-glass access
- Never share one org across unrelated companies
Cross-tenant access is not available to tenant Admins. Platform Super Admin is a separate control plane.
## FAQ
## Related topics
---
# Teams
Source: https://docs.qefro.com/docs/platform/teams/
> Organize Members into Teams and grant AI Workspace access for Employee AI least-privilege access control.
**Teams** group organization Members and grant them access to specific [AI Workspaces](/docs/platform/ai-workspaces). They are the practical mechanism behind Employee AI least privilege.
## Short definition (citation-ready)
> A Team is an organization-scoped group of Members with attached workspaces. Members only see Internal Portal assistants for workspaces their Teams grant.
## How Teams relate to RBAC
| Concept | Role |
| --- | --- |
| Owner / Admin / Member | Who can configure vs who only chats |
| Team | Which workspaces a Member may use |
| Workspace | Isolated knowledge + tools |
See [RBAC](/docs/platform/rbac) and [Configure RBAC](/docs/guides/configure-rbac).
## API surfaces (org)
Typical REST routes (Owner/Admin JWT):
| Method | Path | Purpose |
| --- | --- | --- |
| GET/POST | `/api/v1/org/teams` | List / create teams |
| PUT | `/api/v1/org/teams/:id/members` | Set membership |
| PUT | `/api/v1/org/teams/:id/workspaces` | Grant workspaces |
Exact payloads: Admin Console + [REST APIs](/docs/api/rest-apis).
## Architecture
```mermaid
flowchart TB
Org[Organization]
Org --> T1[Team: People Ops]
Org --> T2[Team: IT]
Org --> HR[Workspace HR]
Org --> IT[Workspace IT]
T1 --> HR
T2 --> IT
Member[Member] --> Portal[Internal Portal]
Portal --> HR
Portal --> IT
```
## Workflow
Putting everyone on one mega-team defeats least privilege. Prefer function-based Teams.
## FAQ
## Related topics
---
# RBAC
Source: https://docs.qefro.com/docs/platform/rbac/
> Owner, Admin, and Member roles — teams, workspace grants, and document write flags.
**RBAC** in Qefro uses organization roles **Owner**, **Admin**, and **Member**, plus **Teams** that grant Members access to specific **workspaces** (and optional document write).
## Introduction
Canonical role definitions (from product `RoleDefinition`):
### Owner
- Manage billing and subscription
- Transfer ownership / delete organization
- Manage all teams, members, workspaces
- Configure integrations and AI assistants
- Access all workspaces
- Cannot be removed by Admins
### Admin
- Access all workspaces; create/delete workspaces
- Manage teams and invite members
- Configure integrations and AI assistants
- Change member roles (except Owner)
- Cannot transfer ownership, change subscription owner, or delete the Owner
### Member
- Use AI + integrations only in authorized workspaces
- View teams they belong to
- Upload/manage documents **only** when granted team write
- Cannot invite users, manage teams, billing, secrets, or promote roles
REST (Admin Console JWT):
- `/api/v1/org/roles`, `/api/v1/org/members`, `/api/v1/org/teams`, …
- `/api/v1/org/teams/:id/workspaces`
- `/api/v1/org/workspaces/:id/teams`
- `/api/v1/org/audit-logs`
- `/api/v1/team/invite`, `/api/v1/team/accept-invite`, …
## Why it exists
Employee AI and Admin Console need least privilege. Public Customer AI uses widget tokens instead of org roles.
## Concepts
- **Org role** — Owner / Admin / Member
- **Team** — group of members
- **Workspace grant** — which workspaces a team can use
- **Write flag** — per team member document write
## Architecture
```mermaid
flowchart TB
Owner --> Admin
Admin --> Member
Member --> Team
Team --> Workspaces
Owner --> Billing
```
## Workflow
## Code examples
```bash
curl -sS -H "Authorization: Bearer $USER_JWT" \
https://api.qefro.com/api/v1/org/roles
curl -sS -H "Authorization: Bearer $USER_JWT" \
https://api.qefro.com/api/v1/org/teams
```
## Best practices
- Prefer Admin over shared Owner logins
- Keep Customer Support tools off HR teams
- Audit role changes via `/api/v1/org/audit-logs`
## Security notes
Plan seat limits (`users_limit`) still apply on Free/Starter/Growth — RBAC does not bypass quotas.
## FAQ
## Related topics
---
# Analytics
Source: https://docs.qefro.com/docs/platform/analytics/
> Use tenant analytics and feedbacks on app.qefro.com to find knowledge gaps, tool failures, and channel performance after go-live.
**Analytics** in Qefro shows how Customer AI and Employee AI are used in your organization — conversations, messages, feedback, and related signals — so you can improve knowledge and tools with evidence.
## Short definition (citation-ready)
> Tenant analytics aggregates conversation and feedback signals for an organization; platform operators have separate admin analytics for fleet-wide usage.
## What you can see
| Signal | Why it matters |
| --- | --- |
| Conversation / message volume | Capacity and channel adoption |
| Feedback scores | Answer quality perception |
| Tool errors (via tool logs) | Broken Business Actions |
| Low-citation chats (spot check) | Knowledge gaps |
Admin Console exposes tenant views. APIs:
Platform Super Admin surfaces also exist under `/api/v1/admin/analytics/*` (not for tenant Admins).
## Architecture
```mermaid
flowchart LR
Widget[Website widget] --> Events
Portal[Internal Portal] --> Events
WA[WhatsApp] --> Events
Events --> Store[(Analytics store)]
Store --> TenantUI[Admin Console analytics]
Store --> API[tenant analytics APIs]
```
## Weekly review workflow
## Best practices
- Pair dashboards with manual citation spot-checks
- Track tool error rates in [Audit Logs](/docs/security/audit-logs) / tool logs
- Do not chase vanity message counts without quality review
- Keep Support and HR analytics interpreted separately (different workspaces)
## Security notes
Analytics APIs require an authenticated org user JWT — not the publishable widget token.
## FAQ
## Related topics
---
# Branding
Source: https://docs.qefro.com/docs/platform/branding/
> Customize Internal Portal and website widget appearance — logo, colors, theme, and welcome message — via Admin Console and public branding bootstrap.
**Branding** makes Employee AI and Customer AI feel like your product — logos, primary color, theme, and welcome copy — without changing model behavior.
## Short definition (citation-ready)
> Qefro tenant branding controls portal and widget presentation. Public clients bootstrap appearance via `GET /api/v1/public/tenant-branding`, while Admins configure assets in the Admin Console.
## What you can customize
| Surface | Typical controls |
| --- | --- |
| Internal Portal | Logo, colors, theme |
| Website widget | Primary color, theme, welcome message (`data-*` overrides) |
| Custom domain portal | Same branding on your hostname |
Public bootstrap:
```bash
curl -sS "https://api.qefro.com/api/v1/public/tenant-branding?slug=YOUR_SLUG"
```
Widget embed overrides (examples):
```html
```
## Workflow
## Best practices
- Keep WCAG-minded contrast for text on primary colors
- Align widget color with your site CTA color
- Do not put secrets in welcome messages
- Branding ≠ instructions — tone still lives in workspace instructions
Only use HTTPS logo URLs from origins you control. Untrusted image hosts are a supply-chain risk.
## FAQ
## Related topics
---
# Custom Domains
Source: https://docs.qefro.com/docs/platform/custom-domains/
> Serve the Internal Portal on your hostname using Cloudflare custom hostnames — DNS CNAME, TLS status, and tenant mapping.
**Custom domains** let employees open the Internal Portal on a hostname you own (for example `ai.yourcompany.com`) instead of only `your-company.qefro.com`.
## Short definition (citation-ready)
> Qefro portal custom domains use Cloudflare custom hostnames so your DNS CNAME terminates TLS and routes to your organization’s Internal Portal.
## Default vs custom
| Mode | Example |
| --- | --- |
| Default | `acme.qefro.com` |
| Custom | `ai.acme.com` → CNAME to console-provided target (commonly an `org.qefro.com`-style host) |
Step-by-step: [Enable Custom Domains](/docs/guides/enable-custom-domains).
## Architecture
```mermaid
flowchart LR
Browser --> DNS[CNAME on your DNS]
DNS --> CF[Cloudflare custom hostname]
CF --> Portal[Internal Portal for your tenant]
```
## Workflow
## Best practices
- Prefer a subdomain over apex (`@`) records
- Treat domain changes as security-sensitive (phishing risk if misconfigured)
- Keep branding aligned ([Branding](/docs/platform/branding))
A custom domain still maps to **one tenant**. Do not point multiple customers at one organization.
## FAQ
## Related topics
---
# Deployment
Source: https://docs.qefro.com/docs/platform/deployment/
> Qefro cloud is fully managed — production hosts, what you configure, and when Enterprise private deployment applies.
For most customers, **deployment** means configuring your tenant on Qefro cloud — not operating vector databases or LLM gateways yourself.
## Short definition (citation-ready)
> Qefro cloud hosts the Admin Console, API, widget CDN, and Internal Portal. Customers deploy by configuring workspaces, channels, and RBAC; Enterprise private deployment is a separate packaging discussion.
## Production hosts
| Component | Host |
| --- | --- |
| Marketing | https://qefro.com |
| Admin Console | https://app.qefro.com |
| API | https://api.qefro.com |
| Widget CDN | https://cdn.qefro.com/widget.js |
| Internal Portal | `your-company.qefro.com` or custom domain |
| Docs | https://docs.qefro.com |
## What you configure vs what Qefro runs
| You configure | Qefro operates |
| --- | --- |
| Workspaces + knowledge | RAG infrastructure |
| Business Tools + secrets | Tool egress + encryption |
| Widget / WhatsApp binding | Channel runtimes |
| Teams / RBAC | Auth service |
| Branding / domains | Portal edge / TLS |
Go-live checklist: [Production Deployment](/docs/guides/production-deployment).
## Workflow
## Enterprise / private options
If you need VPC-style or private packaging, contact Sales. Controls and tenancy concepts still apply; only the hosting boundary changes. See [Compliance](/docs/security/compliance).
## FAQ
## Related topics
---
# Guides
# Build AI Customer Support
Source: https://docs.qefro.com/docs/guides/build-ai-customer-support/
> Step-by-step: create a Support workspace, ingest FAQs, validate citations, embed the website widget, then optionally add WhatsApp and Business Tools.
This guide ships **Customer AI** for support: one Support workspace, grounded answers with citations, a website widget, and optional WhatsApp / Business Tools.
## Outcome
When you finish, you will have:
- A **Customer Support** AI Workspace on [app.qefro.com](https://app.qefro.com)
- Knowledge ingested and citation-checked
- The [website widget](/docs/platform/website-widget) bound to that workspace
- A clear path to WhatsApp (Growth+) and read-only tools
## Prerequisites
- Organization account at [app.qefro.com](https://app.qefro.com)
- Owner or Admin role
- Customer-safe documents (FAQs, policies, product docs) — **not** HR/payroll files
## Architecture
```mermaid
flowchart LR
Docs[FAQs / policies] --> WS[Support workspace]
WS --> RAG[Hybrid RAG]
WS --> Widget[Website widget]
WS --> WA[WhatsApp optional]
WS --> Tools[Business Tools optional]
Visitor --> Widget
Visitor --> WA
```
## Step 1 — Create the Support workspace
1. Open Admin Console → Workspaces.
2. Create a workspace named **Customer Support** (or similar).
3. Set instructions: tone, language, and “refuse when sources are missing.”
Platform background: [AI Workspaces](/docs/platform/ai-workspaces), [What is an AI Workspace?](/docs/concepts/what-is-an-ai-workspace).
## Step 2 — Ingest knowledge
1. Upload PDFs/docs or crawl approved public URLs.
2. Prefer canonical sources over stale wiki dumps.
3. Wait for indexing to finish; reindex if you replace a file.
Platform: [Knowledge Platform](/docs/platform/knowledge-platform), [Hybrid RAG](/docs/concepts/hybrid-rag).
## Step 3 — Validate answers
Ask at least ten real support questions in the console:
| Check | Pass criteria |
| --- | --- |
| Citations | Answer points at the right doc |
| Identifiers | SKUs / error codes resolve |
| Unknown topics | Assistant refuses instead of inventing policy |
| Isolation | HR canaries (if any) never appear |
## Step 4 — Embed the website widget
```html
```
Copy the token and workspace id from Admin Console → Widget. Full guide: [Deploy Website Widget](/docs/guides/deploy-website-widget).
## Step 5 — Optional: WhatsApp
On Growth+, bind the **same** Support workspace to WhatsApp so answers stay consistent. Guide: [Deploy WhatsApp AI](/docs/guides/deploy-whatsapp-ai).
## Step 6 — Optional: Business Tools
Only after citations are solid:
1. Add a **read-only** tool (e.g. order status).
2. Use [`identify()`](/docs/platform/identity-forwarding) when the API needs the logged-in customer.
3. Monitor tool logs for a week before enabling writes.
Guides: [Connect REST APIs](/docs/guides/connect-rest-apis), [Secure Business Actions](/docs/guides/secure-business-actions).
## Workflow checklist
Keep HR, payroll, and internal incident docs out of this workspace. Use a separate Employee AI workspace for those.
## FAQ
Next: [Production Deployment](/docs/guides/production-deployment) before inviting real traffic.
## Related topics
---
# Create Employee AI
Source: https://docs.qefro.com/docs/guides/create-employee-ai/
> Stand up Employee AI on the Internal Portal: workspaces, Teams, RBAC grants, and branding.
This guide ships **Employee AI**: authenticated organization members use the [Internal Portal](/docs/platform/internal-portal) to chat with workspaces they are granted — not the public widget.
## Outcome
- One or more internal workspaces (HR, IT, Ops, …)
- Members invited and placed in Teams
- Workspace grants so Members only see allowed assistants
- Portal reachable on `your-company.qefro.com` (or a custom domain later)
## Prerequisites
- Owner or Admin on [app.qefro.com](https://app.qefro.com)
- Internal documents approved for employee access
- Decision on who may configure tools for customer channels (usually Admins only)
## Architecture
```mermaid
flowchart TB
Org[Organization]
Org --> HR[Workspace HR]
Org --> IT[Workspace IT]
Org --> Team[Team: People Ops]
Team --> HR
Member[Member login] --> Portal[Internal Portal]
Portal --> HR
Portal --> IT
```
## Step 1 — Create internal workspaces
Create separate workspaces per audience (HR vs IT). Do **not** reuse the public Support workspace.
Background: [Employee AI](/docs/platform/employee-ai), [What is an AI Workspace?](/docs/concepts/what-is-an-ai-workspace).
## Step 2 — Ingest internal knowledge
Upload runbooks and policies that employees are allowed to see. Re-test citations and refusals the same way you would for Customer AI.
## Step 3 — Configure RBAC
1. Invite users (email/password signup + verification flow).
2. Create a Team (e.g. People Ops).
3. Add Members to the Team.
4. Attach the HR workspace to that Team.
Owners and Admins can typically access all workspaces; Members only see grants. Guide: [Configure RBAC](/docs/guides/configure-rbac). Platform: [RBAC](/docs/platform/rbac), [Teams](/docs/platform/teams).
## Step 4 — Brand and open the portal
1. Set logo/colors under Branding.
2. Note your `*.qefro.com` portal hostname.
3. Have a Member sign in and confirm they only see granted workspaces.
Optional later: [Enable Custom Domains](/docs/guides/enable-custom-domains).
## Step 5 — Business Tools (customer channels only)
In V1, Business Tool execution is **not** available from the Internal Portal. Configure tools for Website Widget and WhatsApp if needed; the portal stays a knowledge assistant.
See [Business Tools](/docs/platform/business-tools) and [Secure Business Actions](/docs/guides/secure-business-actions).
## Workflow checklist
Employee AI is not “Customer AI behind a login.” It requires membership, Teams, and workspace grants. See Customer AI vs Employee AI.
## FAQ
## Related topics
---
# Connect REST APIs
Source: https://docs.qefro.com/docs/guides/connect-rest-apis/
> Create a workspace Business Tool that calls your HTTPS API — method, URL, encrypted auth, test, and execution logs.
This guide creates a **Business Tool** that calls your HTTPS API so the assistant can run **Business Actions** during chat.
## Outcome
- A REST tool bound to one workspace
- Credentials stored encrypted (not in the browser)
- A successful console test
- Awareness of SSRF limits and logging
## Prerequisites
- Owner/Admin access
- An HTTPS endpoint you control (or vendor API with a scoped key)
- Decision: which workspace may use this tool (Support vs HR, etc.)
## Concepts
| Term | Meaning |
| --- | --- |
| Business Tool | Connector definition |
| Business Action | One runtime invocation |
Read: [What are Business Actions?](/docs/concepts/business-actions), [Business Tools](/docs/platform/business-tools).
## Architecture
```mermaid
sequenceDiagram
participant User
participant Qefro
participant API as Your HTTPS API
User->>Qefro: Chat in workspace
Qefro->>Qefro: Select allowed tool
Qefro->>API: HTTPS + secrets + optional end-user headers
API-->>Qefro: JSON result
Qefro-->>User: Grounded reply
```
## Step 1 — Pick a safe first endpoint
Prefer **read-only** `GET` (order status, ticket status). Avoid refunds, deletes, or bulk exports on day one.
## Step 2 — Create the tool in the workspace
In Admin Console → workspace → Business Tools / integrations:
1. Choose REST.
2. Set method + URL template.
3. Add encrypted auth (Bearer, header API key, etc.).
4. Describe parameters the model may fill.
## Step 3 — Test
Use the console test action or:
```bash
curl -sS -X POST \
-H "Authorization: Bearer $USER_JWT" \
-H "Content-Type: application/json" \
https://api.qefro.com/api/v1/tools/$TOOL_ID/test \
-d '{"arguments":{"order_id":"123"}}'
```
## Step 4 — Review logs
```bash
curl -sS -H "Authorization: Bearer $USER_JWT" \
https://api.qefro.com/api/v1/tools/$TOOL_ID/logs
```
See [Audit Logs](/docs/security/audit-logs).
## Step 5 — Enable for chat carefully
- Customer AI: add [`identify()`](/docs/platform/identity-forwarding) if your API authorizes end users
- Employee AI: ensure only internal workspaces have internal tools
## Workflow checklist
Tool URLs are SSRF-checked. Private IPs, link-local, and many metadata endpoints are blocked. Use public HTTPS APIs or approved allowlisted destinations.
## FAQ
## Related topics
---
# Import OpenAPI
Source: https://docs.qefro.com/docs/guides/import-openapi/
> Preview and apply an OpenAPI document into workspace integrations/tools — review operations, auth, and least privilege before enabling chat.
This guide imports an **OpenAPI** document so Qefro can create or update Business Tools from your API spec — instead of hand-defining every operation.
## Outcome
- OpenAPI uploaded/previewed for a workspace
- Operations reviewed (especially writes)
- Tools applied with encrypted auth
- Chat enablement deferred until tests pass
## Prerequisites
- OpenAPI 3.x document (URL or file) that describes **HTTPS** APIs
- Scoped API credentials for the environments you will call
- Owner/Admin role
## Why preview matters
OpenAPI imports can expose dozens of operations, including `DELETE` and admin paths. Always **preview**, deselect dangerous operations, then apply.
## Step 1 — Prepare the spec
- Prefer a trimmed spec for the assistant (order read APIs ≠ full admin API)
- Remove internal-only servers you cannot expose
- Confirm security schemes match credentials you will store
## Step 2 — Preview in Admin Console
1. Open the target workspace → integrations / OpenAPI import.
2. Provide the spec URL or upload.
3. Review the operation list Qefro proposes.
## Step 3 — Apply selectively
1. Keep read operations first.
2. Attach encrypted credentials.
3. Apply/create tools.
4. Run per-tool tests (see [Connect REST APIs](/docs/guides/connect-rest-apis)).
## Step 4 — Reimport discipline
When the upstream API changes:
1. Re-preview the new spec.
2. Diff newly added write operations.
3. Rotate credentials if the vendor rotated keys.
4. Re-test before production chat.
## Workflow checklist
An OpenAPI import is a security change. Treat it like granting a new OAuth scope to an automation user.
## FAQ
## Related topics
---
# Deploy WhatsApp AI
Source: https://docs.qefro.com/docs/guides/deploy-whatsapp-ai/
> Connect Meta Cloud API to Qefro WhatsApp webhooks on Growth+, bind a Support workspace, and validate the same grounded answers as your website widget.
This guide enables **Customer AI on WhatsApp** using Meta Cloud API and Qefro’s WhatsApp webhook endpoints.
## Outcome
- WhatsApp channel configured for your organization
- Webhook verification succeeding against `api.qefro.com`
- Conversations bound to your Support workspace
- Parity checks against website widget answers
## Prerequisites
- **Growth plan or higher** (WhatsApp is plan-gated)
- Meta Business / Cloud API app with a phone number
- Support workspace already cite-tested on the website
- Owner/Admin access
Platform: [WhatsApp](/docs/platform/whatsapp).
## Architecture
```mermaid
sequenceDiagram
participant User as WhatsApp user
participant Meta as Meta Cloud API
participant Qefro as api.qefro.com
participant WS as Support workspace
User->>Meta: Message
Meta->>Qefro: Webhook
Qefro->>WS: RAG / tools
WS-->>Qefro: Reply
Qefro->>Meta: Send response
Meta-->>User: WhatsApp message
```
## Step 1 — Confirm plan and workspace
1. Confirm WhatsApp is available on your plan in Billing.
2. Choose the **same** Support workspace used by the website widget (recommended for consistency).
## Step 2 — Configure Meta Cloud API
1. Create/select a Meta app with WhatsApp product.
2. Note phone number id, business account id, and access token (store the token as a secret in Qefro — not in git).
3. Prepare the webhook callback URL and verify token as shown in Admin Console → WhatsApp (source of truth for the exact path).
Typical Qefro webhook base: `https://api.qefro.com/api/v1/whatsapp/webhook` (confirm in console if paths evolve).
## Step 3 — Connect in Admin Console
1. Open WhatsApp settings for the organization/workspace mapping.
2. Paste Meta credentials into encrypted fields.
3. Complete webhook verification (Meta challenges Qefro; Qefro responds with the verify token).
## Step 4 — Send test messages
| Test | Expected |
| --- | --- |
| Known FAQ | Grounded answer + consistent with website |
| Unknown topic | Refusal / safe fallback |
| Tool-backed question | Only if tools enabled; check logs |
## Step 5 — Operational readiness
- Train support staff on escalation paths
- Monitor conversation analytics and tool logs
- Document opt-out / business hours policy for WhatsApp
## Workflow checklist
WhatsApp messages may include PII. Align retention and tool design with your privacy policy before broad rollout.
## FAQ
## Related topics
---
# Deploy Website Widget
Source: https://docs.qefro.com/docs/guides/deploy-website-widget/
> Embed cdn.qefro.com/widget.js with token, API endpoint, and workspace id — then optionally add identify() for authenticated customers.
This guide embeds **Customer AI** on your website using the Qefro widget script.
## Outcome
- Widget loads from `https://cdn.qefro.com/widget.js`
- Conversations hit `https://api.qefro.com`
- Chat is bound to a specific Support workspace
- Optional `identify()` for logged-in users
## Prerequisites
- Support workspace with validated knowledge ([Build AI Customer Support](/docs/guides/build-ai-customer-support))
- Widget token from Admin Console
- Ability to edit your site HTML / tag manager
## Step 1 — Copy embed values
From Admin Console → Widget:
| Attribute | Purpose |
| --- | --- |
| `data-token` | Publishable widget token |
| `data-endpoint` | `https://api.qefro.com` |
| `data-workspace-id` | Support workspace id |
Platform: [Website Widget](/docs/platform/website-widget).
## Step 2 — Add the script
```html
```
Place it before `` on pages where chat should appear (or load via your tag manager).
## Step 3 — Verify in production-like preview
1. Open the page in a private window.
2. Ask a known FAQ; confirm citations.
3. Ask an unknown topic; confirm refusal.
4. Confirm the widget is **not** bound to an HR workspace.
## Step 4 — Optional identify()
When Business Tools must act as the logged-in customer:
```html