πŸš€ Nova Chat API Quick Start

Integrate Nova Chat into your website or app in minutes. All examples use https://novailink.com β€” replace with your Nova Chat domain.

1 Register & Get Token

Register a new account

# Create account (Free plan, 14-day trial)
curl -X POST https://novailink.com/nc-api/v1/accounts \
  -H "Content-Type: application/json" \
  -d '{"name":"My Company","email":"admin@mycompany.com","password":"MyPass123!","plan":"starter"}'

Login to get JWT token

# Returns JWT token β€” save this for all subsequent requests
curl -X POST https://novailink.com/nc-api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@mycompany.com","password":"MyPass123!"}'

# Response:
{ "token": "eyJhbG...", "user": { "id": 17, "email": "admin@mycompany.com" } }
Store the token. All API calls below use: Authorization: Bearer <token>

2 Check Account & Plan

# Get your account status, plan limits, and widget info
curl https://novailink.com/nc-api/v1/account/status \
  -H "Authorization: Bearer $TOKEN"

# Response includes:
{
  "plan": "starter",
  "limits": { "domains": 1, "agents": 3, "kb_items": 50 },
  "agentic_rag_enabled": false,
  "domains": [{
    "id": 118,
    "website_url": "https://mycompany.com",
    "website_token": "wk_live_abc123...",
    "chatwoot_inbox_id": 119
  }]
}

3 Bind a Website Domain

# Add a new domain to your account
curl -X POST https://novailink.com/nc-api/v1/account/bind-domain \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"website_url":"https://mycompany.com","label":"Main Site"}'

# Response returns website_token β€” this is your widget key
{
  "domain_id": 118,
  "website_token": "wk_live_abc123...",
  "widget_code": "<script>...</script>"
}
You can also manage domains via the Dashboard at /app/settings/websites

4 Embed the Chat Widget

Copy the widget snippet from the bind-domain response, or use this template:

<!-- Add to your website's <head> -->
<script>
window.novaChatSettings = {
  websiteToken: "wk_live_YOUR_TOKEN",
  position: "bottom_left"
};
</script>
<script src="https://novailink.com/widget.js"></script>

Or use the Nova Widget SDK (v2, lighter)

<script src="https://novailink.com/nova-widget-sdk-v2.js"
  data-token="wk_live_YOUR_TOKEN"></script>
The widget appears in the bottom-left corner. Visitors can start chatting immediately.

5 Configure AI Bot

Get or create AI agents

# List existing agents (AI + Human)
curl https://novailink.com/nc-api/v1/agents \
  -H "Authorization: Bearer $TOKEN"

# Create a new AI agent
curl -X POST https://novailink.com/nc-api/v1/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_name":"SupportBot","greeting_message":"Hi! How can I help?","system_prompt":"You are a helpful support agent. Be friendly and concise."}'

Assign AI to a domain

# Configure AI for a specific domain
curl -X POST https://novailink.com/nc-api/v1/account/domains/118/ai-config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ai_bot_config_id":1,"is_active":true}'

6 API Keys (Programmatic Access)

For server-side integrations, generate an API Key:

# Generate a new API key
curl -X POST https://novailink.com/nc-api/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Integration","permissions":["read"]}'

# Response β€” save full_key immediately, it won't be shown again
{
  "key": { "name": "My Integration" },
  "full_key": "nc_live_abc123def456..."
}
Use Authorization: Bearer nc_live_xxx with the API Key for server-to-server calls.

7 Conversations via API (App Integration)

Use the Widget API to create and manage conversations from your app:

Create a new conversation

curl -X POST "https://novailink.com/api/v1/widget/conversations?website_token=wk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contact":{"name":"John","email":"john@example.com"},"message":"I need help with my order"}'

# Response:
{ "id": 360, "status": "open", "contact": { ... } }

Send a message

curl -X POST "https://novailink.com/api/v1/widget/messages?website_token=wk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":360,"content":"My order #12345"}'

Poll for new messages

curl "https://novailink.com/api/v1/widget/messages?website_token=wk_live_YOUR_TOKEN&conversation_id=360"

8 Webhooks (Real-time Events)

Nova Chat can notify your server when conversations are created or updated:

# Configure in your Nova Chat Dashboard β†’ Settings β†’ API Keys β†’ External API
# Your webhook endpoint receives POST requests with:
{
  "event": "conversation_created",
  "conversation_id": 360,
  "account_id": 17,
  "contact": { "name": "John", "email": "john@example.com" }
}

9 Knowledge Base API

# List knowledge base items
curl https://novailink.com/nc-api/v1/knowledge_base/items \
  -H "Authorization: Bearer $TOKEN"

# Add a KB item
curl -X POST https://novailink.com/nc-api/v1/knowledge_base/items \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"How to reset password?","content":"Go to Settings β†’ Change Password...","category":"After-sales","tags":["password","account"]}'

10 Bulk Import & Automated RAG

Import knowledge in bulk β€” ideal for AI scraping docs, CI/CD pipelines, or migrating existing FAQ systems.

Bulk import JSON

# POST an array β€” use the import endpoint for bulk
curl -X POST https://novailink.com/nc-api/v1/knowledge_base/items/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
  {"title":"What is your return policy?","content":"30-day returns, free shipping label.","category":"After-sales","tags":["return","refund"]},
  {"title":"How to track my order?","content":"Login β†’ Orders β†’ Track. Or email support with order #.","category":"Pre-sales","tags":["order","shipping"]}
]'

# Response: array of created items with IDs
[{"id":42,"title":"What is your return policy?",...}, ...]

Import from JSON file

# Upload a JSON file of Q&A pairs (max 500 items per batch)
curl -X POST https://novailink.com/nc-api/v1/knowledge_base/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @faq_export.json

AI auto-extract RAG from conversations (Agentic RAG)

# Trigger AI analysis of a conversation to extract Q&A pairs
curl -X POST https://novailink.com/nc-api/v1/agentic-rag/analyze \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":358}'

# Response: number of drafts generated
{"drafts":[...],"count":3,"message":"3 Q&A pairs extracted"}

Pipeline automation example (Node.js)

// Example: CI/CD pipeline pushes docs to Nova Chat KB
const TOKEN = process.env.NOVA_CHAT_TOKEN;
const docs = [
  { title: "API Rate Limits", content: "1000 req/min per account...", category: "Product Features", tags: ["api","limits"] },
  { title: "Webhook Setup", content: "Configure in Settings β†’ API Keys...", category: "Product Features", tags: ["api","webhook"] },
];

await fetch('https://novailink.com/nc-api/v1/knowledge_base/items/import', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
  body: JSON.stringify(docs),
});
console.log('KB synced:', docs.length, 'items');

Auto-scrape FAQ page (Python example)

# Example: AI scrapes your FAQ page and pushes to Nova Chat KB
import requests

FAQ_URL = "https://mycompany.com/faq"
TOKEN = "nc_live_xxx"  # Your API Key

# 1. Scrape content (use your own HTML parser)
# 2. Convert to Q&A pairs with AI
pairs = [
  {"title":"Shipping time?","content":"3-5 business days","category":"Pre-sales"},
  {"title":"Payment methods?","content":"Visa, MC, PayPal","category":"Pricing"},
]

# 3. Bulk push to Nova Chat
resp = requests.post(
  'https://novailink.com/nc-api/v1/knowledge_base/items/import',
  headers={'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json'},
  json=pairs,
)
print(f"Imported {len(resp.json())} items")

πŸ“‹ Endpoint Reference

EndpointDescription
POST /nc-api/v1/accountsRegister new account
POST /nc-api/v1/auth/loginLogin, get JWT
GET /nc-api/v1/account/statusAccount status & limits
POST /nc-api/v1/account/bind-domainAdd website domain
GET /nc-api/v1/account/domainsList domains
GET/POST /nc-api/v1/agentsManage agents
POST /nc-api/v1/account/domains/:id/ai-configConfigure AI for domain
GET/POST/DELETE /nc-api/v1/api-keysManage API keys
GET/POST/PUT/DELETE /nc-api/v1/knowledge_base/itemsKnowledge base CRUD (single)
POST /nc-api/v1/knowledge_base/items/importBulk import Q&A pairs (JSON array, max 200)
POST /nc-api/v1/agentic-rag/analyzeAI extracts Q&A from conversation
GET/POST /nc-api/v1/conversationsAgent conversation management
POST /api/v1/widget/conversationsCreate customer conversation
GET/POST /api/v1/widget/messagesRead/send customer messages
GET /api/v1/sla/statusSLA status overview

Nova Chat API Quick Start Β· Full docs at /developers/docs