🚀 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...",
    "novachat_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"}'

Get messages (Platform API)

⚠️ Widget API cannot retrieve messages. To read messages, use the Platform API with your nc_live_ key:

# Get all messages in a conversation
curl "https://novailink.com/nc-api/v1/conversations/360/messages"   -H "Authorization: Bearer nc_live_YOUR_KEY"

# Response:
[{ "id": 123, "content": "Hello!", "sender_type": "Agent", ... }, ...]

Recommended Architecture

For app integrations:
• Widget API (website_token) → Create conversations, send messages (client-side)
• Platform API (nc_live_ key) → Read messages, manage accounts (server-side)
• Webhooks → Real-time event notifications

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")

11 Widget Translation

Enable automatic translation for the chat widget, supporting 8+ languages including English, Chinese, French, Japanese, Spanish, Korean, German, and Portuguese.

Enable translation via API

# Toggle widget translation on
curl -X PUT https://novailink.com/nc-api/v1/account/translation \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# Response:
{ "success": true, "translation_enabled": true }

Disable translation

# Toggle widget translation off
curl -X PUT https://novailink.com/nc-api/v1/account/translation \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Translation can also be toggled from Settings → Translation in the Dashboard UI. When enabled, widget UI text adapts to the visitor's browser language automatically. 聊天窗口支持中/英/日/法/西/韩/德/葡等语言自动切换。

12 Notification Settings

Configure real-time notification preferences for the agent dashboard. Three notification types are available:

Notification types

Type	Key	Description
🔔 Sound	`sound_enabled`	Plays a chime when a new message arrives
💬 Popup	`popup_enabled`	Shows a desktop popup for new conversations
🌐 Browser	`browser_notif_enabled`	Uses browser Notification API (requires permission)

Configuration (client-side only)

Notification preferences are stored in the browser's localStorage under the key nc_notif_settings. No API call is needed — configure them directly from the Dashboard UI.

// localStorage key: nc_notif_settings
{
  "sound_enabled": true,
  "sound_volume": 0.8,
  "popup_enabled": true,
  "browser_notif_enabled": false
}

Configure notifications in the Dashboard under Settings → Notifications. Sound volume is a float from 0.0 (muted) to 1.0 (max). Browser notifications require the user to grant permission on first use.

13 Widget Style Customization

Customize the chat widget's appearance — button text, colors, position, and more — to match your brand.

Update widget style via API

# Customize button text, color, and position
curl -X PUT https://novailink.com/nc-api/v1/widget/style \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"button_text":"Chat Now","button_bg_color":"#1e40af","position":"bottom_right"}'

# Response:
{ "success": true, "style_updated": true }

Available style options

Option	Example	Description
`button_text`	"Chat Now"	Text on the chat bubble button
`button_bg_color`	"#1e40af"	Background color (hex)
`position`	"bottom_right"	Widget position on screen

You can also configure styles via the Dashboard: Settings → Websites → Style button next to each domain. Widget changes take effect immediately for new visitors.

14 SLA Configuration

Monitor service-level agreement compliance across conversations. SLA levels define response-time targets for your support team.

SLA priority levels

Level	Priority	Target Response
P1	Urgent	Immediate response required
P2	High	Within 1 hour
P3	Normal	Within 4 hours
P4	Low	Within 24 hours

Check SLA status

# Get overall SLA compliance overview
curl https://novailink.com/api/v1/sla/status \
  -H "Authorization: Bearer $TOKEN"

# Response includes breaches and warnings
{
  "sla_status": "ok",
  "breaches": [],
  "warnings": 2,
  "pending_count": 15
}

Monitor SLA compliance visually at the SLA Dashboard: /react/app/conversations/sla. Breaches are highlighted in red, warnings in yellow.

15 Agent Management

Invite team members as agents via API. Manage pending invites and track who has accepted.

Invite a new agent

# Send an invitation email to a new agent
curl -X POST https://novailink.com/nc-api/v1/agents/invite \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@company.com","name":"Jane Support"}'

# Response:
{ "success": true, "invite_id": 42, "message": "Invitation sent to agent@company.com" }

List pending invites

# View all unaccepted invitations
curl https://novailink.com/nc-api/v1/agents/pending-invites \
  -H "Authorization: Bearer $TOKEN"

# Response:
[
  { "id": 42, "email": "agent@company.com", "name": "Jane Support", "invited_at": "2024-01-15T10:30:00Z" },
  { "id": 43, "email": "dev@company.com",  "name": "Mike Dev",      "invited_at": "2024-01-14T08:00:00Z" }
]

Cancel an invite

# Revoke a pending invitation by ID
curl -X DELETE https://novailink.com/nc-api/v1/agents/cancel-invite/42 \
  -H "Authorization: Bearer $TOKEN"

# Response:
{ "success": true, "message": "Invitation cancelled" }

Invited agents receive an email with a registration link. Once they accept, they appear in the regular GET /nc-api/v1/agents list. Agent limits depend on your plan — check /nc-api/v1/account/status.

16 Customer Memory

Nova Chat automatically summarizes conversations after 5 minutes of inactivity and stores a memory per contact. This memory is injected into the AI context on future conversations, giving the bot long-term awareness of each customer.

How it works

# After 5 min of inactivity, the system generates a summary:
# "John asked about order #12345. Issue was shipping delay.
#  Resolved by expediting delivery. Customer satisfied."

# This memory is automatically injected into future AI responses
# when John returns — no manual configuration needed.

Retrieve customer memory via API

# Get stored memory for a contact
curl https://novailink.com/nc-api/v1/memory/contact_42 \
  -H "Authorization: Bearer $TOKEN"

# Response:
{
  "contact_id": "contact_42",
  "summary": "Returning customer. Previously discussed order tracking and refund policy.",
  "last_interaction": "2024-01-15T14:30:00Z",
  "total_interactions": 3
}

Webhook event

# Your webhook endpoint receives POST when memory is updated:
# POST https://your-server.com/webhook/memory
{
  "event": "memory_updated",
  "contact_id": "contact_42",
  "summary": "...",
  "timestamp": "2024-01-15T14:35:00Z"
}

No setup required. Memory works automatically once conversations are active. Each contact gets their own memory entry, updated after each conversation ends. This powers personalized, context-aware AI responses. 客户记忆自动生成，无需手动配置。

📋 Endpoint Reference

Endpoint	Description
`POST /nc-api/v1/accounts`	Register new account
`POST /nc-api/v1/auth/login`	Login, get JWT
`GET /nc-api/v1/account/status`	Account status & limits
`POST /nc-api/v1/account/bind-domain`	Add website domain
`GET /nc-api/v1/account/domains`	List domains
`GET/POST /nc-api/v1/agents`	Manage agents
`POST /nc-api/v1/account/domains/:id/ai-config`	Configure AI for domain
`GET/POST/DELETE /nc-api/v1/api-keys`	Manage API keys
`GET/POST/PUT/DELETE /nc-api/v1/knowledge_base/items`	Knowledge base CRUD (single)
`POST /nc-api/v1/knowledge_base/items/import`	Bulk import Q&A pairs (JSON array, max 200)
`POST /nc-api/v1/agentic-rag/analyze`	AI extracts Q&A from conversation
`GET/POST /nc-api/v1/conversations`	Agent conversation management
`POST /api/v1/widget/conversations`	Create customer conversation
`GET/POST /api/v1/widget/messages`	Read/send customer messages
`GET /api/v1/sla/status`	SLA compliance overview
`PUT /nc-api/v1/account/translation`	Toggle widget translation
`PUT /nc-api/v1/widget/style`	Customize widget appearance
`POST /nc-api/v1/agents/invite`	Invite a new agent
`GET /nc-api/v1/agents/pending-invites`	List pending invites
`DELETE /nc-api/v1/agents/cancel-invite/:id`	Cancel agent invite
`GET /nc-api/v1/memory/:contact_id`	Get customer conversation memory

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