Welcome to Qaqnuz

Qaqnuz is an AI-powered Instagram automation platform built for Uzbekistan's top brands. It runs every DM, comment, and story reply through an 8-stage AI pipeline with human oversight at every step — so your brand always sounds like your brand.

This documentation covers brand onboarding, the Mission Control dashboard, the AI pipeline, and the developer API.

Brand onboarding

Each brand you manage in Qaqnuz goes through a 4-step onboarding process:

1. 1
   Connect Instagram — Link your Instagram Business or Creator account via the official Meta API. Qaqnuz needs Read + Respond permissions on messages and comments.
2. 2
   Build your brand profile — Upload your brand voice, product catalog, FAQs, pricing, delivery policies, and payment methods (Click, Payme, Uzum, Humo). The AI uses this as its knowledge base.
3. 3
   Set Trust Level — Choose L1 (all drafts reviewed), L2 (FAQs auto-published, complex queued), or L3 (full automation with guardrails). You can change this at any time.
4. 4
   Go live — Flip the toggle in Mission Control → Brands. The pipeline starts processing incoming messages within seconds.

Trust levels

Trust levels control how much the AI can publish without human review. You set the level per brand and can change it at any time.

Your first AI reply

Once your brand is live, here's what happens when a customer sends a DM:

1. 01Message arrives → pipeline starts within 200ms
2. 02Qualify stage checks if it's spam/bot/irrelevant
3. 03Classify stage identifies intent (price inquiry, order status, complaint…)
4. 04Retrieve stage pulls relevant facts from your brand knowledge base
5. 05Compose stage writes the reply in your brand voice
6. 06Guard stage runs 9 safety checks
7. 07Evaluate stage scores quality and confidence
8. 08Trust stage routes: auto-publish (L2/L3) or send to Review Queue (L1)
9. 09Publish stage sends the reply via the Instagram API

Mission Control dashboard

Mission Control is the operator workspace where you review queued replies, monitor pipeline health, manage brands, and analyze performance.

Inbox

The Inbox shows all active conversations across all your brands. Each row displays the customer handle, the brand they contacted, the AI's latest draft, and the current status.

• Auto-replied — the AI published a reply autonomously (L2/L3 brands).
• Pending review — the reply is in your queue, waiting for approval.
• Escalated — the pipeline flagged this conversation for immediate human attention.
• Taken over — an operator is handling this conversation manually.

Brands

The Brands panel lists all Instagram accounts connected to your workspace.

• Toggle a brand live/paused without disconnecting it.
• Set or change the Trust Level per brand.
• Update the brand knowledge base (FAQs, catalog, policies).
• View per-brand stats: DMs/day, auto-rate, avg response time.

Review Queue

The Queue shows all AI-composed replies waiting for human approval. For each item you can:

• Approve — publish the reply as-is.
• Edit & Approve — modify the text before publishing.
• Reject — discard the draft; the conversation stays open.
• Take Over — claim the conversation and handle it manually.

Each queued item shows the AI's confidence score, the pipeline stage it was held at, and the reason for review (low confidence, policy flag, escalation keyword, etc.).

Analytics

The Analytics panel tracks these key metrics:

Monitor

The Monitor panel shows real-time pipeline health. It displays per-stage latency, error rates, queue depth, and the status of all 9 AMT (Automated Message Triage) services.

AI Pipeline

Every message processed by Qaqnuz passes through 8 sequential stages. Each stage adds context, applies checks, and passes a structured payload to the next stage.

Pipeline overview

Total pipeline latency target: under 2 seconds end-to-end for standard messages.

Stage 1 — Qualify

Determines whether the incoming message is worth processing. Filters out spam, bot messages, gibberish, duplicate messages, and content outside the brand's defined scope.

• Spam / bot detection (pattern matching + ML classifier)
• Language detection — routes non-Uzbek/Russian messages to escalation
• Duplicate detection — deduplicates messages sent multiple times
• Out-of-scope detection — marks messages for human review if they fall outside the brand topic

Stage 2 — Classify

Identifies the intent and entity structure of the message. Classification is used to route the message to the correct response template and knowledge base section.

• Intent: price inquiry, availability, order status, complaint, compliment, return, custom order, general question
• Entity extraction: product name, SKU, size, color, quantity, delivery location
• Sentiment: positive, neutral, negative (used for priority routing)
• Urgency: normal, high, critical (complaints and payment issues are always high)

Stage 3 — Retrieve

Pulls the most relevant facts from the brand's knowledge base using semantic search. The retrieved context is injected into the prompt for Stage 4.

• Vector search over product catalog, FAQs, policies
• Payment method lookup (Click, Payme, Uzum, Humo links/instructions)
• Order status lookup (if CRM integration is active)
• Confidence score: if retrieval confidence < 0.65, the message is flagged for human review

Stage 4 — Compose

Generates the reply using Claude Opus 4.7 with a brand-specific system prompt. The compose stage uses the classification, retrieved context, and full conversation history to write a reply in the brand's voice.

System prompt structure:
- Brand identity & voice (tone, vocabulary, formality)
- Product knowledge (injected from Retrieve stage)
- Conversation history (last 10 messages)
- Reply constraints (max length, emoji policy, CTA rules)
- Current date/time and brand timezone

Stage 5 — Guard

Nine safety guardrails run in parallel before a reply can proceed:

If any guardrail fails, the message is held in the Review Queue with a detailed failure reason.

Stage 6 — Evaluate

Scores the composed reply across 4 dimensions. If the aggregate score falls below the brand's configured threshold, the message is routed to the queue.

• Helpfulness — does the reply actually answer the question?
• Accuracy — are all facts correct and grounded?
• Brand alignment — does it sound like the brand?
• Completeness — does it handle all entities in the message?

Stage 7 — Trust

Routes the reply based on the brand's Trust Level and the aggregate score from Stage 6.

L1 brand:  → always route to Review Queue
L2 brand:  score ≥ 0.90 AND all guardrails pass → auto-publish
           score <  0.90 OR any guardrail warn   → Review Queue
L3 brand:  all guardrails pass                  → auto-publish
           any guardrail fail                    → Review Queue

Stage 8 — Publish

Sends the approved reply via the Instagram Graph API. Handles rate limiting, retry logic (3 attempts with exponential backoff), and delivery confirmation.

• DMs: send via POST /me/messages
• Comments: reply via POST /{comment_id}/replies
• Stories: send DM response to story mention
• Delivery receipt stored in analytics_events table

API Reference

The Qaqnuz API lets you push custom events, sync your product catalog, query conversation history, and receive real-time webhooks for pipeline events.

Base URL

https://api.qaqnuz.uz/v1

All requests must include an Authorization: Bearer YOUR_API_KEY header. Responses are JSON. Timestamps are ISO 8601 UTC.

Authentication

Get an API key

API keys are issued per workspace. Generate one in Mission Control → Settings → API Keys. Keys are prefixed qn_live_ for production and qn_test_ for sandbox.

curl https://api.qaqnuz.uz/v1/brands \
  -H "Authorization: Bearer qn_live_xxxxxxxxxxxx"

Webhooks

Register a webhook URL in Mission Control → Settings → Webhooks to receive real-time events. Qaqnuz signs every request with an X-Qaqnuz-Signature header (HMAC-SHA256 of the raw body using your webhook secret).

Event types

Endpoints

List brands

GET /v1/brands

Response:
{
  "brands": [
    {
      "id": "brand_abc123",
      "name": "KadrBeauty",
      "ig_username": "kadrbeauty",
      "trust_level": "L2",
      "status": "live",
      "stats": { "dms_today": 142, "auto_rate": 0.82 }
    }
  ]
}

Get conversations

GET /v1/brands/:brand_id/conversations?status=pending&limit=20

Response:
{
  "conversations": [
    {
      "id": "conv_xyz",
      "customer_handle": "@aziza_m",
      "last_message": "Narxi qancha?",
      "status": "pending_review",
      "draft_reply": "Assalomu alaykum! ...",
      "confidence": 0.87,
      "created_at": "2026-05-12T10:34:00Z"
    }
  ]
}

Push catalog update

POST /v1/brands/:brand_id/catalog

Body:
{
  "products": [
    {
      "sku": "DRESS-001",
      "name": "Lola Kuz Ko'ylagi",
      "price_uzs": 320000,
      "available": true,
      "description": "...",
      "tags": ["dress", "autumn", "size-S", "size-M", "size-L"]
    }
  ]
}

Response: { "updated": 1, "indexed": true }