API

Quickchat AI provides a REST API for programmatic access to your AI Assistant’s configuration, Knowledge Base, Conversations, AI Actions, and more.

Authentication

All API endpoints use Bearer token authentication. Include your API token in the Authorization header of every request:

Authorization: Bearer <API_TOKEN>

Tokens are created in the Quickchat Dashboard under Integrations > API. Each token is a JWT that contains your scenario_id, so no additional identifier header is needed.

• Token validity: 52 weeks from creation
• Tokens can be revoked at any time from the Dashboard
• Each token is scoped to a single AI Assistant (scenario)

Note

The Chat endpoint uses a different, legacy authentication method (api_key + scenario_id in the request body). See Chat (Legacy Auth) below, or the full legacy documentation.

Token Scopes

API tokens are created with one of two scopes:

Scope	Access Level	Description
read_all	Read-only	Can read all resources but cannot create, update, or delete
write_all	Read + Write	Full access to all endpoints, including write operations

• Tokens are assigned a scope when created in the Dashboard under Integrations > API
• write_all scope includes all read_all permissions automatically
• Using a read_all token on a write endpoint returns 403 with "Insufficient token scope. Required: write_all"

Tip

Use read_all tokens for monitoring, analytics, and read-only integrations. Only use write_all tokens when your integration needs to create or modify resources.

Scope requirements by endpoint group:

Endpoint Group	Read Operations	Write Operations
Chatbot Settings	read_all	write_all
Knowledge Base Settings	read_all	write_all
Articles	read_all	write_all
Article Language URLs	read_all	write_all
Tags	read_all	—
File Upload	—	write_all
Import External Content	—	write_all
Intercom Knowledge Base	read_all	write_all
Widget Configuration	read_all	write_all
Conversations	read_all	—
Conversation Metadata	read_all	write_all
Handoff Configuration	read_all	write_all
Conversation Rating	read_all	write_all
AI Actions	read_all	write_all

Base URL

Endpoint Group	Base URL
Knowledge Base, AI Actions, File Upload, Import, Chatbot Settings, Widget, Handoff, Conversation Rating	https://app.quickchat.ai/v1/api/
Conversations	https://app.quickchat.ai/v1/api_core/

Rate Limits

Rate limits are applied per token, per endpoint.

Tier	Limit	Applies To
READ	120 requests/min	GET and list operations
WRITE	60 requests/min	POST, PATCH, PUT, DELETE
HEAVY	20 requests/min	File uploads, imports, scraping

When a rate limit is exceeded, the API returns HTTP 429 Too Many Requests.

Pagination

List endpoints support pagination via query parameters:

Parameter	Description
limit integer	Number of items per page
offset integer	Number of items to skip

Paginated responses follow this structure:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Error Handling

All errors are returned as JSON in the following format:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Status	Code	Description
400	BAD_REQUEST	Invalid input or missing required fields
401	PERMISSION_DENIED	Invalid, expired, or revoked token
402	PAYMENT_REQUIRED	Active subscription required
403	PERMISSION_DENIED	Token lacks the required scope for this operation
404	NOT_FOUND	Resource not found
409	CONFLICT	Conflicting operation (e.g., concurrent modification)
422	VALIDATION_ERROR	Request body failed schema validation
429	TOO_MANY_REQUESTS	Rate limit exceeded
500	UNKNOWN	Internal server error
503	SERVICE_UNAVAILABLE	Temporary unavailability

---

Chatbot Settings

Retrieve and update your AI Agent’s full configuration, including personality, conversation style, and system prompt.

Corresponds to Identity > Profile and Identity > Conversation Style in the Dashboard.

Get Chatbot Settings

Scope: read_all

GET https://app.quickchat.ai/v1/api/chatbot_settings

Shell

curl https://app.quickchat.ai/v1/api/chatbot_settings \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/chatbot_settings",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "personality": 0,
  "profession": "helpful_assistant",
  "creativity_level": 1,
  "greeting": "<p>Hello! How can I help you today?</p>",
  "greeting2": "",
  "header": "Support Assistant",
  "header2": "",
  "language_chosen": "en",
  "reply_length": 1,
  "one_word_description": "Support Agent",
  "short_description": "A helpful customer support assistant.",
  "ai_commands": ["Be polite", "Stay on topic"]
}

Field	Description
one_word_description string	AI Agent name. Dashboard: Identity > Profile > AI Agent Name (max 200 chars)
short_description string	System prompt / AI Agent description. Dashboard: Identity > Profile > AI Agent Description (max 2000 chars)
ai_commands array of strings	Behavioral guidelines for the AI. Dashboard: Identity > Conversation Style > AI Guidelines (max 500 chars per item)
personality integer (0–13)	AI personality preset. Dashboard: Identity > Conversation Style > Personality. See table below
profession string	AI profession/role. Dashboard: Identity > Conversation Style > Profession (max 200 chars). See table below
creativity_level integer (0–2)	Dashboard: Identity > Conversation Style > Creativity. 0 = Deterministic, 1 = Balanced, 2 = Creative
reply_length integer (0–2)	Dashboard: Identity > Conversation Style > Reply Length. 0 = Short, 1 = Medium, 2 = Long
greeting string	Primary greeting message (HTML). Dashboard: Identity > Profile > Greeting messages (max 1000 chars)
greeting2 string	Secondary greeting message (HTML). Dashboard: Identity > Profile > Greeting messages
header string	Chat header text. Dashboard: Identity > Profile > Chat header text
header2 string	Secondary header text. Dashboard: Identity > Profile > Chat header text
language_chosen string	Comma-separated language codes (e.g. "en,es,de"). Dashboard: Identity > Profile > Languages

Personality values:

Value	Label	Description
0	Classic	Well-rounded, balanced between professionalism and approachability (default)
1	Humorous	Witty tone with puns and jokes for entertaining interactions
2	Formal	Formal and serious, concise factual information for business settings
3	Friendly	Casual conversations with a personal, approachable touch
4	Sassy	Confident and playful with humor
5	Intelligent	Detailed, accurate information for comprehensive understanding
6	Empathetic	Caring, compassionate interactions showing concern for feelings
7	Bold	Strong opinions and recommendations delivered with confidence
9	Excited	Lively and energetic engagement
10	Mysterious	Cryptic, intriguing responses for a unique experience
11	Inspiring	Promotes positive thinking and goal-reaching in a coach-like fashion
12	Adventurous	Encourages leaving comfort zones and exploring new opportunities
13	Elegant	Sophisticated experience for unique and exquisite brands

Profession values:

Value	Dashboard Label	Description
helpful_assistant	Helpful Assistant	Versatile, multi-purpose. Recommended for most use cases
customer_support_representative	Support Agent	Empathetic, provides step-by-step solutions and troubleshooting
shopping_assistant	Shopping Assistant	Proactively offers product recommendations with links
field_expert	Field Expert	Professional consultant, asks clarifying questions, provides expert guidance
interviewer	Interviewer	Asks questions instead of providing answers. For surveys, interviews, feedback

Note

The one_word_description, short_description, and ai_commands fields are also available through the Knowledge Base Settings endpoint. These fields are shared — updating via either endpoint modifies the same underlying data.

Update Chatbot Settings

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/chatbot_settings

Request Body — All fields are optional. Only include the fields you want to update.

Parameter	Description
personality integer (0–13)	AI personality preset
profession string	AI profession/role (max 200 chars)
creativity_level integer (0–2)	0 = Deterministic, 1 = Balanced, 2 = Creative
greeting string	Primary welcome message (HTML, max 1000 chars)
greeting2 string	Secondary welcome message
header string	Chat header text
header2 string	Secondary header text
language_chosen string	Comma-separated language codes
reply_length integer (0–2)	0 = Short, 1 = Medium, 2 = Long
one_word_description string	AI Agent name (max 200 chars)
short_description string	AI Agent system prompt / description (max 2000 chars)
ai_commands array of strings	AI Guidelines (max 500 chars per item)

Shell

curl -X PATCH https://app.quickchat.ai/v1/api/chatbot_settings \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "greeting": "<p>Welcome! Ask me anything.</p>",
  "creativity_level": 2
}'

Python

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/chatbot_settings",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "greeting": "<p>Welcome! Ask me anything.</p>",
        "creativity_level": 2,
    },
)
data = response.json()

Response 200 OK — Returns the updated chatbot settings (same schema as Get Chatbot Settings response).

---

Knowledge Base

The Knowledge Base is the core of your AI Agent’s expertise — it contains all the information your AI uses to answer questions. These endpoints let you manage the Knowledge Base configuration and trigger retraining after content changes.

The Knowledge Base draws from Articles you create, import from websites, or upload as files. After making changes to articles, you need to retrain the Knowledge Base for updates to take effect in conversations.

Get Settings

Retrieve your Knowledge Base configuration.

Scope: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/

Shell

curl https://app.quickchat.ai/v1/api/knowledge_base/ \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "one_word_description": "Support Agent",
  "short_description": "A helpful customer support assistant.",
  "ai_commands": ["Be polite", "Stay on topic"],
  "retrain_state": null
}

Field	Description
one_word_description string	AI Agent name. Dashboard: Identity > Profile > AI Agent Name
short_description string	System prompt / AI Agent description. Dashboard: Identity > Profile > AI Agent Description
ai_commands array of strings	Behavioral guidelines. Dashboard: Identity > Conversation Style > AI Guidelines
retrain_state string or null	Current training status: null (up to date or never trained), "to_be_retrained", "in_progress", "up_to_date", or "failed"

Note

These three fields (one_word_description, short_description, ai_commands) are shared with Chatbot Settings. Updating via either endpoint modifies the same underlying data.

Update Settings

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/knowledge_base/

Request Body

Parameter	Description
one_word_description string	AI Agent name
short_description string	System prompt / AI Agent description
ai_commands array of strings	AI Guidelines

Shell

curl -X PATCH https://app.quickchat.ai/v1/api/knowledge_base/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "one_word_description": "Sales Bot"
}'

Python

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/knowledge_base/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={"one_word_description": "Sales Bot"},
)
data = response.json()

Response 200 OK — Returns the updated Knowledge Base settings (same schema as Get Settings).

Retrain Knowledge Base

Trigger an asynchronous retraining of the Knowledge Base.

Scope: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/retrain/

Shell

curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/retrain/ \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/knowledge_base/retrain/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)

Response 202 Accepted

Note

Retraining is needed after publishing article changes to ensure the AI Agent uses the latest content. You can monitor progress via the retrain_state field in Get Settings — it changes from "to_be_retrained" to "in_progress" to "up_to_date".

---

Articles

Articles are the building blocks of your AI Agent’s Knowledge Base. Each article represents a piece of knowledge — a help page, FAQ entry, product description, or any content your AI should know about.

There are three article types: Articles (full documents with title and body), Paragraphs (short standalone text entries), and URL articles (automatically created when importing web content). You can create articles manually via the API, import them from websites using Import External Content, upload files via File Upload, or sync from Intercom.

After creating or updating articles, remember to retrain the Knowledge Base for changes to take effect.

Create Article

Scope: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/articles/

Request Body

Parameter	Description
content string, required	Article content
type string	"Article" (default) or "Paragraph"
title string	Article title

Article Types

• "Article" — A full knowledge base document with title and content. Use for FAQ entries, help articles, product descriptions.
• "Paragraph" — A short standalone text entry without a title. Use for brief facts, one-liner answers, quick reference data.
• "URL" (read-only) — Created automatically when content is imported from a website. Contains the scraped page content with the source URL. Cannot be set on creation.

Shell

curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/articles/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "content": "Our return policy allows returns within 30 days.",
  "title": "Return Policy"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "content": "Our return policy allows returns within 30 days.",
        "title": "Return Policy",
    },
)
data = response.json()

Response 201 Created

{
  "id": 1234,
  "article_id": "abc-123",
  "type": "Article",
  "title": "Return Policy",
  "description": "",
  "content": "Our return policy allows returns within 30 days.",
  "state": "draft",
  "deploy_state": "draft",
  "version": null,
  "max_available_version": null,
  "url": null,
  "tags": [],
  "created_timestamp": "2026-01-15",
  "last_modified_timestamp": "2026-01-15",
  "downloaded_timestamp": "2026-01-15",
  "last_updated_timestamp": "2026-01-15",
  "last_updated_from_external_source_timestamp": null
}

Field	Description
id integer	Article numeric ID. This is the canonical identifier used in all URL paths
article_id string	Legacy string identifier. May be empty — use id instead
type string	"Article", "Paragraph", or "URL"
title string	Article title
description string	Article description
content string	Article content
deploy_state string	"draft" or "published" — controls article visibility
state string	Internal processing status (see note below)
version integer or null	Current version number
max_available_version integer or null	Highest available version
url string or null	Source URL (for URL-type articles)
tags array of strings	Associated tags
created_timestamp string	Creation date
last_modified_timestamp string	Last modification date
downloaded_timestamp string	Download date
last_updated_timestamp string	Last update date
last_updated_from_external_source_timestamp string or null	Last external source update

Understanding Article States

Articles have two state fields:

• deploy_state: Controls whether the article is a "draft" or "published". This is the primary field you should use to manage article visibility.
• state: Reflects the internal processing status. For most API users, this field can be ignored — it tracks backend processing steps and may show values like "done" or "published".

List Articles

Scope: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/

Query Parameters

Parameter	Description
limit integer	Items per page
offset integer	Items to skip
types string	Filter by type: Article, Paragraph, URL
tags string	Filter by tag
url string	Filter by URL
title string	Filter by title
query string	Search by content

Shell

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/?limit=10&offset=0' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10, "offset": 0},
)
data = response.json()

Response 200 OK

{
  "items": [
    {
      "id": 1234,
      "article_id": "abc-123",
      "type": "Article",
      "title": "Return Policy",
      "description": "",
      "state": "published",
      "deploy_state": "published",
      "version": 1,
      "max_available_version": 1,
      "url": null,
      "tags": ["policies"],
      "created_timestamp": "2026-01-15",
      "last_modified_timestamp": "2026-01-15",
      "downloaded_timestamp": "2026-01-15",
      "last_updated_timestamp": "2026-01-15",
      "last_updated_from_external_source_timestamp": null
    }
  ],
  "offset": 0,
  "limit": 10,
  "count": 1
}

Note

The list response does not include the content field. Use Get Article to retrieve the full content of a specific article.

Get Article

Scope: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}

Shell

curl https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK — Returns the full article object (same schema as Create Article response), including the content field.

Update Article

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}

Request Body

Parameter	Description
content string	Updated article content
title string	Updated title
tags array of strings	Updated tags
save_mode string	"draft" (default) or "publish"

Caution

The save_mode: "draft" option only sets the deploy_state flag — it does not prevent the article content from being used by the AI once the Knowledge Base is retrained. For programmatic workflows, use save_mode: "publish" and trigger a retrain when you’re ready for changes to take effect.

Shell

curl -X PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Updated Return Policy",
  "content": "Returns accepted within 60 days.",
  "save_mode": "publish"
}'

Python

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "title": "Updated Return Policy",
        "content": "Returns accepted within 60 days.",
        "save_mode": "publish",
    },
)
data = response.json()

Response 200 OK — Returns the updated article object.

Delete Articles

Delete one or more articles by ID.

Scope: write_all

DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/

Request Body — JSON array of article IDs.

Shell

curl -X DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '[1234, 5678]'

Python

import requests

response = requests.delete(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json=[1234, 5678],
)

Response 200 OK

Search Articles

Search through article content with text matching.

Scope: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/search

Query Parameters

Parameter	Description
query string, required	Search query
is_case_insensitive boolean	Case-insensitive search (default: true)
with_title_url_and_tags boolean	Include title/URL/tags in search (default: true)
strict_search boolean	Require exact match (default: false)
num_of_display_articles integer	Number of articles to display (default: 5)
num_of_data_articles integer	Number of articles to search (default: 15)

Shell

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/search?query=return%20policy' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/search",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"query": "return policy"},
)
data = response.json()

Response 200 OK

{
  "article_snippets": [
    {
      "article_id": 1234,
      "expository_sentence": "Our return policy allows returns within 30 days.",
      "query_words_ids": [
        {"start_char": 4, "end_char": 10, "text": "return"}
      ]
    }
  ],
  "article_snapshots": {
    "items": [],
    "offset": 0,
    "count": 1
  }
}

List Paragraphs

List all Paragraph-type articles. Paragraphs are short standalone text entries without a title — as opposed to full Articles which have both a title and content body.

Scope: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs

Query Parameters

Parameter	Description
limit integer	Items per page
offset integer	Items to skip
query string	Filter by content

Shell

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs?limit=10' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10},
)
data = response.json()

Response 200 OK

{
  "items": [
    {
      "id": 1,
      "content": "Our return policy allows returns within 30 days."
    }
  ],
  "offset": 0,
  "count": 1
}

---

Article Language URLs

Language URLs let you associate language-specific source links with articles. When the AI references an article during a conversation, the chat widget displays the URL matching the conversation’s detected language (most_frequent_language). This is useful for multilingual deployments where the same content has different URLs per locale (e.g., example.com/en/returns vs example.com/es/devoluciones).

Get Language URL

Scope: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}/lang_urls/{language}

Shell

curl https://app.quickchat.ai/v1/api/knowledge_base/articles/1234/lang_urls/en \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234/lang_urls/en",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "url": "https://example.com/en/return-policy"
}

Create Language URL

Scope: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}/lang_urls/{language}

Request Body

Parameter	Description
url string, required	URL for the language-specific version

Shell

curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/articles/1234/lang_urls/en \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/en/return-policy"}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234/lang_urls/en",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={"url": "https://example.com/en/return-policy"},
)
data = response.json()

Response 200 OK

{
  "url": "https://example.com/en/return-policy"
}

Update Language URL

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}/lang_urls/{language}

Request Body

Parameter	Description
url string, required	Updated URL

Response 200 OK — Returns the updated URL object.

Delete Language URL

Scope: write_all

DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}/lang_urls/{language}

Shell

curl -X DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/1234/lang_urls/en \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.delete(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234/lang_urls/en",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)

Response 200 OK

---

Tags

Tags help you organize and categorize your Knowledge Base articles. They serve three key purposes:

1. Visual organization in the Inbox — Tags appear as labels on articles in the Dashboard, making it easy to visually identify and filter content by topic, department, or category.
2. AI Action targeting — When you configure AI Actions in the Dashboard, you use tags to tell the AI which subset of articles to search. For example, a “Search Returns” action can target only articles tagged returns, giving the AI focused, relevant results instead of searching the entire Knowledge Base.
3. Programmatic filtering — Use the tags parameter in List Articles to retrieve only articles matching a specific tag, enabling targeted content management workflows.
4. AI search relevance — The AI Agent is tag-aware when searching the Knowledge Base for answers. Descriptive tags help the AI narrow down the most relevant articles, improving answer accuracy and response quality.

List Tags

Retrieve all tags used across Knowledge Base articles.

Scope: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/tags/

Shell

curl https://app.quickchat.ai/v1/api/knowledge_base/tags/ \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/tags/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
tags = response.json()

Response 200 OK

["policies", "faq", "product-info"]

---

File Upload

Upload files to be processed and added to the Knowledge Base as articles.

Upload PDF

Scope: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/file_upload_api/pdf

Upload a PDF file. The content is extracted and added as an article.

Shell

curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/file_upload_api/pdf \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -F 'pdf_file=@document.pdf'

Python

import requests

with open("document.pdf", "rb") as f:
    response = requests.post(
        url="https://app.quickchat.ai/v1/api/knowledge_base/file_upload_api/pdf",
        headers={"Authorization": "Bearer <API_TOKEN>"},
        files={"pdf_file": f},
    )
data = response.json()

Response 200 OK

{
  "status": "success",
  "message": "File processed successfully.",
  "article": {
    "id": 1234,
    "title": "document.pdf"
  }
}

Field	Description
status string	Processing status
message string	Human-readable result message
article object	The created article

Upload File

Scope: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/file_upload_api/

Upload a supported file (PDF, DOCX). The content is extracted and added as an article.

Shell

curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/file_upload_api/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -F 'file=@document.docx'

Python

import requests

with open("document.docx", "rb") as f:
    response = requests.post(
        url="https://app.quickchat.ai/v1/api/knowledge_base/file_upload_api/",
        headers={"Authorization": "Bearer <API_TOKEN>"},
        files={"file": f},
    )
data = response.json()

Response 200 OK — Same schema as Upload PDF.

---

Import External Content

Import content from external sources into the Knowledge Base. These endpoints process content asynchronously.

Async Processing

All import endpoints process content asynchronously. After submitting an import request, the content is scraped and added to the Knowledge Base in the background. The Knowledge Base is automatically marked for retraining once the import completes.

To monitor progress:

1. Check retrain_state via Get Knowledge Base Settings — it changes to "to_be_retrained" then "in_progress" then "up_to_date"
2. Use List Articles to verify imported articles appear

Scrape Website

Scrape a single webpage or an entire website and import the content.

Scope: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/import_external/website

Request Body

Parameter	Description
url string, required	URL to scrape
mode string	"individual" (default), "site_wide", or "individual_with_summary"
phrases array of strings	Key phrases to extract
html_selector string	CSS selector to target specific content

Shell

curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/import_external/website \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/docs",
  "mode": "individual"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/knowledge_base/import_external/website",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={"url": "https://example.com/docs", "mode": "individual"},
)
data = response.json()

Response 202 Accepted

{
  "status": "success",
  "url": "https://example.com/docs",
  "article": {}
}

Import YouTube Transcript

Import the transcript from a YouTube video.

Scope: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/import_external/youtube

Request Body

Parameter	Description
url string, required	YouTube video URL
toast_process_uuid string, required	UUID v4 for tracking the import process

Shell

curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/import_external/youtube \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "toast_process_uuid": "550e8400-e29b-41d4-a716-446655440000"
}'

Python

import uuid
import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/knowledge_base/import_external/youtube",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "toast_process_uuid": str(uuid.uuid4()),
    },
)

Response 202 Accepted — The transcript is processed asynchronously.

Import Sitemap

Import content from all links in an XML sitemap.

Scope: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/import_external/site-map

Request Body

Parameter	Description
site_map string, required	URL to an XML sitemap
link_filter_regex string	Regex to filter which links to import (default: ".*")
html_selector string	CSS selector to target specific content
summarize boolean	Whether to summarize imported content (default: false)

Shell

curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/import_external/site-map \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "site_map": "https://example.com/sitemap.xml"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/knowledge_base/import_external/site-map",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={"site_map": "https://example.com/sitemap.xml"},
)
data = response.json()

Response 202 Accepted

{
  "status": "success",
  "links": ["https://example.com/page1", "https://example.com/page2"]
}

Scrape List of Links

Import content from a specific list of URLs.

Scope: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/import_external/scrape-list

Request Body

Parameter	Description
links array of strings, required	List of URLs to scrape (non-empty)
tags array of strings	Tags to apply to imported articles
html_selector string	CSS selector to target specific content
summarize boolean	Whether to summarize imported content (default: false)

Shell

curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/import_external/scrape-list \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "links": ["https://example.com/page1", "https://example.com/page2"],
  "tags": ["imported"]
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/knowledge_base/import_external/scrape-list",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "links": ["https://example.com/page1", "https://example.com/page2"],
        "tags": ["imported"],
    },
)
data = response.json()

Response 202 Accepted

{
  "status": "success",
  "links": ["https://example.com/page1", "https://example.com/page2"]
}

Delete Links

Remove previously imported URL-type articles from the Knowledge Base.

Scope: write_all

DELETE https://app.quickchat.ai/v1/api/knowledge_base/import_external

Request Body

Parameter	Description
links array of strings, required	List of URLs to remove (min 1)

Note

All provided URLs must exist in the Knowledge Base as URL-type articles. If any URL doesn’t match an existing article, the request returns 404.

Shell

curl -X DELETE https://app.quickchat.ai/v1/api/knowledge_base/import_external \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "links": ["https://example.com/page1"]
}'

Python

import requests

response = requests.delete(
    url="https://app.quickchat.ai/v1/api/knowledge_base/import_external",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "links": ["https://example.com/page1"],
    },
)

Response 200 OK

---

Intercom Knowledge Base

Migrate your Intercom knowledge to Quickchat AI in minutes. If you’re using Intercom’s Fin AI and want to switch to Quickchat AI — or run both side by side — these endpoints make it seamless. Your entire Intercom Help Center (the articles that power Fin AI’s responses) can be synced to Quickchat’s Knowledge Base with a single API call.

How it works:

1. Connect your Intercom account via the Quickchat Dashboard or the Intercom App Store integration
2. Use Import Intercom Articles to pull all your Help Center articles into Quickchat’s Knowledge Base
3. Use Refresh Intercom Articles to keep content in sync as you update articles in Intercom
4. If you decide to disconnect, Delete Intercom Articles cleanly removes all synced content

This means your AI Agent immediately has access to the same knowledge that Fin AI uses, with zero manual content migration. For a full walkthrough of the Intercom integration, see the Intercom channel guide. To learn more about switching from Fin AI, visit Quickchat as a Fin AI alternative.

Refresh Intercom Articles

Re-fetch content from Intercom for existing articles.

Scope: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/intercom/refresh_articles

Request Body

Parameter	Description
article_ids array of integers	Specific article IDs to refresh (default: all)
fetch_new_articles boolean	Whether to fetch new articles (default: true)

Response 204 No Content

Import Intercom Articles

Import all articles from Intercom.

Scope: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/intercom/import

Response 200 OK — Returns a list of imported article snapshots.

Delete Intercom Articles

Remove all Intercom-sourced articles from the Knowledge Base.

Scope: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/intercom/delete

Response 204 No Content

---

Widget Configuration

The widget is a chat interface that you embed on your website — it appears as a floating bubble in the corner of the page that visitors can click to open a conversation with your AI Agent. The widget is fully customizable: you control its colors, size, position, greeting messages, and behavior.

These settings also affect the embed, which is a full-page or inline version of the same chat interface that you can place directly into your webpage layout (as opposed to the floating bubble). Both the widget and embed share the same configuration for appearance, messaging, and behavior.

With these endpoints, you can programmatically customize how Quickchat AI appears on your website — match your brand colors, set up pre-chat forms to collect visitor information, configure typing indicators, enable voice input, and more. For setup instructions, see the Website channel guide.

Get Widget Configuration

Scope: read_all

GET https://app.quickchat.ai/v1/api/widget/configuration

Shell

curl https://app.quickchat.ai/v1/api/widget/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/widget/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "welcome_message": "<p>Hello! How can I help?</p>",
  "welcome_message2": "",
  "header": "Support",
  "subtitle": "We typically reply within minutes",
  "popup_active": true,
  "input_placeholder": "Type your message...",
  "primary_color": "rgb(0, 122, 255)",
  "voice_active": false,
  "header_color": "rgb(0, 122, 255)",
  "header_collapse": false,
  "header_text_color": true,
  "typing": true,
  "window_auto_open": false,
  "white_label": false,
  "prechat_active": false,
  "prechat_header_text": null,
  "prechat_button_text": null,
  "prechat_message_text": null,
  "background_disclaimer_text": null,
  "streaming_active": true,
  "link_tracking_active": false,
  "window_height": 600,
  "window_width": 400,
  "size": "medium",
  "location": "bottom-right",
  "avatar_image": "",
  "bubble_icon_image": ""
}

Content & Messaging

Field	Description
welcome_message string	Primary welcome message displayed when widget opens (HTML). Dashboard: Website > Greeting
welcome_message2 string	Secondary welcome message shown below the primary greeting
header string	Text displayed in the widget header bar. Dashboard: Website > Header
subtitle string	Subtitle text shown below the header. Dashboard: Website > Subtitle
input_placeholder string	Placeholder text in the message input field (e.g., “Type your message…”)
background_disclaimer_text string or null	Disclaimer text shown at the bottom of the chat window

Appearance

Field	Description
primary_color string	Widget accent color as CSS rgb value (e.g., "rgb(0, 122, 255)"). Used for buttons, links, and user message bubbles
header_color string	Header background color as CSS rgb value
header_text_color boolean	Header text brightness. true = white/light text (for dark headers), false = dark text (for light headers). Note: despite the name, this is a boolean, not a color string
size string	Widget size preset: "small", "medium", or "large"
location string	Widget position on the page: "bottom-right", "bottom-left", "top-right", or "top-left"
window_height integer	Widget height in pixels (400-1000)
window_width integer	Widget width in pixels (250-1920)
avatar_image string	URL of the avatar image shown in the chat. Upload via PATCH as base64
bubble_icon_image string	URL of the floating bubble icon. Upload via PATCH as base64

Behavior

Field	Description
popup_active boolean	Show a popup prompt near the widget bubble to encourage visitors to start a conversation
window_auto_open boolean	Automatically open the widget when the page loads (instead of showing just the bubble)
header_collapse boolean	Allow visitors to collapse the header area for more chat space
typing boolean	Show a typing indicator animation while the AI is generating a response
streaming_active boolean	Stream AI responses word-by-word instead of showing the complete message at once
voice_active boolean	Enable voice input — visitors can send messages using their microphone
link_tracking_active boolean	Track when visitors click links in AI responses. Tracked clicks appear as tracked_link events in Conversation Events
white_label boolean	Remove “Powered by Quickchat” branding from the widget

Pre-chat Form

Field	Description
prechat_active boolean	Enable the pre-chat form. When active, visitors must fill in the form before chatting
prechat_header_text string or null	Header text for the pre-chat form
prechat_button_text string or null	Label for the submit button on the pre-chat form
prechat_message_text string or null	Body text/instructions shown in the pre-chat form (HTML)

Update Widget Configuration

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/widget/configuration

Request Body — All fields are optional. Only include the fields you want to update.

Note

For image fields (avatar_image, bubble_icon_image), send base64-encoded image data (max 5 MB). The response returns the stored image URL.

Shell

curl -X PATCH https://app.quickchat.ai/v1/api/widget/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "primary_color": "rgb(255, 87, 34)",
  "header": "Sales Assistant",
  "window_auto_open": true
}'

Python

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/widget/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "primary_color": "rgb(255, 87, 34)",
        "header": "Sales Assistant",
        "window_auto_open": True,
    },
)
data = response.json()

Response 200 OK — Returns the updated widget configuration (same schema as Get Widget Configuration response).

---

Conversations

Quickchat AI automatically captures and analyzes every conversation your AI Agent has across all channels — widget, Slack, WhatsApp, Telegram, and more. The Conversations API gives you programmatic access to this rich dataset for building custom dashboards, feeding downstream analytics pipelines, triggering CRM workflows, or integrating with your existing business intelligence tools.

Every conversation includes AI-powered analysis: sentiment detection, topic classification, resolution tracking, and automatic flagging of conversations that may need human attention. Combined with full message history, tracked link clicks, and custom metadata, you have everything you need to understand how visitors interact with your AI Agent.

Conversation data is spread across several endpoints:

• List Conversations — Basic info, visitor details, status. Use for dashboards, overviews, and filtered queries
• Get Conversation Details — Full info including unified_analysis (AI-generated insights) and client_metadata
• Get Conversation Events — Complete message history, tracked link clicks, and log entries
• Get/Set Metadata — Custom key-value data you attach to conversations (see Conversation Metadata)

List Conversations

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations

Query Parameters

Parameter	Description
limit integer	Items per page
offset integer	Items to skip
query string	Search by order number, UUID, or message text
assignee_type string	"ai_assistant", "human_operator", or "unassigned"
source string	"widget", "slack", "telegram", "whatsapp", etc.
resolution_status string	"open" or "resolved"
created_timestamp_start_date datetime	Filter by creation date (start)
created_timestamp_end_date datetime	Filter by creation date (end)
last_message_at_start_date datetime	Filter by last message date (start)
last_message_at_end_date datetime	Filter by last message date (end)
most_frequent_language string	Filter by detected language

Shell

curl 'https://app.quickchat.ai/v1/api_core/conversations?limit=10&resolution_status=open' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10, "resolution_status": "open"},
)
data = response.json()

Response 200 OK

{
  "items": [
    {
      "id": "conv-uuid-1234",
      "ord": 42,
      "created_at": "2026-01-15T10:30:00Z",
      "last_message_at": "2026-01-15T10:35:00Z",
      "title": "Return policy question",
      "source": "widget",
      "terminated": false,
      "resolution_status": "open",
      "has_unread_messages": true,
      "supports_inbox_control": true,
      "last_message_content": "What is your return policy?",
      "most_frequent_language": "en",
      "assignee": {
        "type": "ai_assistant"
      },
      "visitor_name": "John",
      "visitor_email": "john@example.com",
      "visitor_phone_number": null,
      "visitor_label": null
    }
  ],
  "offset": 0,
  "limit": 10,
  "count": 42
}

Field	Description
id string	Conversation UUID
ord integer	Sequential conversation number
created_at string	Conversation creation timestamp
last_message_at string	Timestamp of the most recent message
title string	AI-generated conversation title
source string	Channel the conversation originated from (e.g., "widget", "slack", "whatsapp")
terminated boolean	Whether the conversation has ended
resolution_status string	"open" or "resolved"
has_unread_messages boolean	Whether there are unread messages
supports_inbox_control boolean	Whether the conversation source supports inbox control (assign, handoff)
last_message_content string	Content of the last message in the conversation
most_frequent_language string	Most frequently detected language in the conversation
assignee object	Current assignee (type: "ai_assistant", "human_operator", or "unassigned")
visitor_name string or null	Visitor’s name (from pre-chat form or channel profile)
visitor_email string or null	Visitor’s email address
visitor_phone_number string or null	Visitor’s phone number
visitor_label string or null	Custom label assigned to the visitor

Get Conversation Details

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conversation_id}/

Shell

curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/ \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "id": "conv-uuid-1234",
  "ord": 42,
  "created_at": "2026-01-15T10:30:00Z",
  "last_message_at": "2026-01-15T10:35:00Z",
  "title": "Return policy question",
  "source": "widget",
  "terminated": false,
  "resolution_status": "open",
  "has_unread_messages": true,
  "supports_inbox_control": true,
  "last_message_content": "What is your return policy?",
  "most_frequent_language": "en",
  "assignee": {
    "type": "ai_assistant"
  },
  "url": null,
  "client_metadata": {"userId": 12},
  "last_visitor_message_at": "2026-01-15T10:34:00Z",
  "unified_analysis": {
    "sentiment": "neutral",
    "resolution_status": "open",
    "topic": "Return policy",
    "is_flagged": false,
    "flag_reason": null
  },
  "visitor_name": "John",
  "visitor_email": "john@example.com",
  "visitor_phone_number": null,
  "visitor_label": null
}

The detail response includes all fields from the list response, plus:

Field	Description
url string or null	URL of the page where the conversation started (widget only)
client_metadata object or null	Custom key-value pairs attached to the conversation
last_visitor_message_at string	Timestamp of the last visitor message
unified_analysis object or null	AI-generated analysis of the conversation (see below)

unified_analysis fields:

Field	Description
sentiment string	AI-detected conversation sentiment (e.g., "positive", "neutral", "negative")
resolution_status string	AI-assessed resolution status (may differ from top-level resolution_status)
topic string	AI-detected conversation topic
is_flagged boolean	Whether the AI flagged this conversation for human review
flag_reason string or null	Reason the conversation was flagged

resolution_status vs unified_analysis.resolution_status

The top-level resolution_status field ("open" or "resolved") is the canonical status set manually or by automation rules.

The unified_analysis.resolution_status is computed by AI analysis and may differ — for example, the AI might classify a conversation as resolved based on content analysis even though the top-level status is still "open". Use the top-level field for filtering and workflow; use unified_analysis for analytics and insights.

Get Conversation Events

Retrieve all events (messages, tracked links, logs) for a conversation.

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conversation_id}/events/

Query Parameters

Parameter	Description
limit integer	Items per page
offset integer	Items to skip

Shell

curl 'https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/?limit=20' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 20},
)
data = response.json()

Response 200 OK

{
  "items": [
    {
      "type": "message",
      "data": {
        "id": "msg-uuid-001",
        "ord": 1,
        "created_at": "2026-01-15T10:30:00Z",
        "content": "Hello! How can I help you today?",
        "author": "ai_assistant",
        "handoff_state": null,
        "message_insights": null,
        "feedback": null,
        "client_metadata": null,
        "sources_generated": [],
        "is_welcome": true,
        "attachments": []
      }
    },
    {
      "type": "message",
      "data": {
        "id": "msg-uuid-002",
        "ord": 2,
        "created_at": "2026-01-15T10:31:00Z",
        "content": "What is your return policy?",
        "author": "visitor",
        "handoff_state": null,
        "message_insights": null,
        "feedback": null,
        "client_metadata": null,
        "sources_generated": [],
        "is_welcome": false,
        "attachments": []
      }
    }
  ],
  "offset": 0,
  "limit": 20,
  "count": 2
}

Event types: message, tracked_link, log

Author types: ai_assistant, visitor, human_operator

Field	Description
type string	Event type: "message", "tracked_link", or "log"
data.id string	Message unique identifier
data.ord integer	Sequential message number
data.created_at string	Timestamp of the event
data.content string	Message content
data.author string	"ai_assistant", "visitor", or "human_operator"
data.handoff_state string or null	Handoff state if applicable
data.message_insights object or null	AI-generated message insights
data.feedback object or null	User feedback on the message
data.client_metadata object or null	Custom metadata attached to the message
data.sources_generated array	Knowledge Base articles the AI used when generating its response
data.is_welcome boolean	Whether this is a welcome message
data.attachments array	File attachments

---

Conversation Metadata

Conversation Metadata lets you attach custom key-value data to conversations, creating a powerful bridge between your systems and your AI Agent. Metadata flows through your entire Quickchat workflow:

• Feed via API — Use these endpoints to programmatically attach metadata to any conversation (e.g., from your CRM, helpdesk, or backend)
• Feed via widget/embed — Pass metadata as initialization parameters when loading the widget, or inject it dynamically during an active conversation using the JavaScript SDK
• Visible in the Dashboard — Metadata appears in the conversation detail view in the Inbox, so your team always has context
• Included in exports — Metadata is included when you export conversations from the Dashboard, making it available for offline analysis
• Used in AI Actions — Metadata values can be injected directly as hard-coded arguments into AI Actions, enabling dynamic behavior without code changes
• Available to the AI Agent — Your AI Agent is aware of metadata values and can reference them during conversations. For example, pass a customer’s name or plan tier, and the AI will personalize its responses accordingly

Metadata is the way to dynamically steer and personalize each conversation. Pass customer IDs, account tiers, referral sources, A/B test variants, or any context your AI Agent needs. This capability will be significantly expanded in future releases.

Metadata is validated against a JSON schema if one is configured in the Dashboard.

Get Metadata

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Shell

curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

Set Metadata

Create or update metadata for a conversation.

Scope: write_all

POST https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Request Body

Parameter	Description
metadata object, required	Key-value metadata to store

Shell

curl -X POST https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "metadata": {"ticket_id": "T-1234", "priority": "high"}
    },
)
data = response.json()

Response 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

---

Handoff Configuration

Human Handoff enables your AI Agent to automatically transfer conversations to human operators when it detects situations that need a personal touch. Handoff is AI-driven — the AI continuously evaluates the conversation against configurable guidelines and triggers a handoff when appropriate, without any manual intervention.

How automatic handoff works:

1. During a conversation, the AI evaluates each message against your generic guidelines (e.g., user frustration, lack of knowledge) and custom guidelines you define
2. When a guideline triggers, the AI shows the visitor a confirmation message asking if they’d like to speak with a human
3. If the visitor confirms, the conversation is transferred to a human operator, with an optional AI-generated summary of the conversation so far
4. If working hours are configured and the request falls outside them, a custom message is shown instead

Additional handoff methods:

• Keyword triggers — Visitors can type specific phrases (e.g., “speak to human”, “agent”) to request handoff directly
• Manual handoff from Dashboard — Operators can take over any conversation from the Inbox by changing the conversation assignee

Topic-based Routing is an advanced feature that routes handoffs to specific operators based on the conversation topic. Each routing profile defines a topic, a description of when it applies, and a list of operators who handle that topic. When a handoff triggers, the AI matches the conversation to the most relevant routing profile and notifies the assigned operators. Configure routing profiles via the routing_profiles array in the PUT request.

Get Handoff Configuration

Scope: read_all

GET https://app.quickchat.ai/v1/api/human_handoff/configuration

Shell

curl https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

The response contains several nested objects:

settings — Core handoff configuration:

Field	Description
is_active boolean	Whether human handoff is enabled
keywords array of strings	Trigger keywords that prompt a handoff (e.g., ["speak to human", "agent"])
ai_summary_active boolean	Send an AI-generated conversation summary to the human operator when handoff occurs
topic_based_routing_active boolean	Whether topic-based routing to specific operators is enabled (read-only, configured via routing profiles)
question_message string	Message shown to the visitor asking if they want to be connected to a human
confirmation_message string	Message shown after the visitor confirms handoff (max 500 chars)
confirmation_outside_working_hours_message string	Message shown when handoff is requested outside working hours (max 500 chars)
working_hours_active boolean	Restrict handoff to working hours only
timezone string	Timezone for working hours (e.g., "Europe/London")
send_email_notification boolean	Send email notifications to operators on handoff
emails array of strings	Email addresses to notify

availability — Working hours schedule (array of slots):

Field	Description
id integer	Availability slot ID
day_span string	Day or day range (e.g., "monday", "monday-friday")
start_time string	Start time in "HH:MM" format
end_time string	End time in "HH:MM" format

generic_guidelines — Predefined handoff trigger rules (array):

Field	Description
name string	Guideline type: "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message"
description string	Description of when this guideline triggers
is_active boolean	Whether this guideline is enabled

custom_guidelines — User-defined handoff trigger rules (array):

Field	Description
id integer	Guideline ID
name string	Custom guideline name (max 100 chars)
description string	When this guideline should trigger handoff (max 2000 chars)
is_active boolean	Whether this guideline is enabled

routing_profiles — Topic-based routing directs handoffs to the right operators based on what the conversation is about.

When a handoff triggers, the AI evaluates the conversation against all active routing profiles and matches it to the most relevant topic. The operators listed in that profile are then notified. If no routing profile matches, the default notification behavior (email list in settings.emails) is used.

Example: You have a “Billing” routing profile assigned to your finance team and a “Technical Support” profile assigned to engineers. When a customer asks about an invoice and triggers a handoff, the AI matches the conversation to “Billing” and notifies only the finance team — not the engineers.

Configure routing profiles in the Dashboard under Handoff > Topic-based Routing, or via the routing_profiles array in the PUT request.

Field	Description
id integer	Routing profile ID
name string	Topic name (e.g., “Billing”, “Technical Support”) (max 100 chars)
description string	When this profile should match — describe the types of conversations that should route to these operators (max 2000 chars)
is_active boolean	Whether this routing profile is enabled
user_ids array of integers	IDs of operators who should be notified when this profile matches

Update Handoff Configuration

Scope: write_all

PUT https://app.quickchat.ai/v1/api/human_handoff/configuration

Caution

PUT replaces the entire handoff configuration atomically. You must include all sections (settings, availability, generic_guidelines, custom_guidelines, routing_profiles) in the request body. Omitting a section or providing partial data will result in validation errors. To make incremental changes, first GET the current configuration, modify the fields you need, and PUT the full object back.

Shell

# First, fetch the current configuration
CONFIG=$(curl -s https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>')

# Modify and PUT back (example: enable handoff)
echo "$CONFIG" | jq '.settings.is_active = true' | \
curl -X PUT https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d @-

Python

import requests

headers = {"Authorization": "Bearer <API_TOKEN>"}

# Fetch current configuration
config = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
).json()

# Modify and PUT back
config["settings"]["is_active"] = True

response = requests.put(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
    json=config,
)
data = response.json()

Response 200 OK — Returns the updated handoff configuration.

---

Conversation Rating

Conversation Rating lets you collect visitor feedback on their AI Agent experience. When enabled, visitors are prompted at the end of their conversation to rate their experience — providing direct, actionable signal on how well your AI Agent is performing.

Ratings appear in the Dashboard under Conversations > Inbox alongside each conversation, and are included in conversation exports. Use this data to identify knowledge gaps, refine your AI Agent’s configuration, and track satisfaction trends over time.

Corresponds to Conversations > Inbox > Feedback settings in the Dashboard.

Get Conversation Rating Configuration

Scope: read_all

GET https://app.quickchat.ai/v1/api/conversation_ratings/configuration

Shell

curl https://app.quickchat.ai/v1/api/conversation_ratings/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/conversation_ratings/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "conv_rating_active": true,
  "conv_rating_popup_active": true,
  "conv_rating_question_codes": ["HELPFUL_THUMBS", "EXPERIENCE_THUMBS"]
}

Field	Description
conv_rating_active boolean	Enable visitor feedback collection at the end of conversations
conv_rating_popup_active boolean	Show a popup prompt asking for feedback (must match conv_rating_active)
conv_rating_question_codes array of strings	Types of feedback questions shown. Default: ["HELPFUL_THUMBS", "EXPERIENCE_THUMBS"]

Update Conversation Rating Configuration

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/conversation_ratings/configuration

Note

conv_rating_active and conv_rating_popup_active must be set to the same value.

Shell

curl -X PATCH https://app.quickchat.ai/v1/api/conversation_ratings/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "conv_rating_active": true,
  "conv_rating_popup_active": true
}'

Python

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/conversation_ratings/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "conv_rating_active": True,
        "conv_rating_popup_active": True,
    },
)
data = response.json()

Response 200 OK — Returns the updated conversation rating configuration.

---

AI Actions

AI Actions extend your AI Agent’s capabilities beyond answering questions from the Knowledge Base. They let you define triggered behaviors — things the AI should do when it detects specific situations in a conversation.

What AI Actions do:

• HTTP Request Actions — Call external APIs when triggered. For example, check order status in your backend, create a support ticket, or look up account information — all during the conversation.
• Remote MCP Actions — Connect to Model Context Protocol servers for advanced tool integrations (e.g., Shopify product lookups, custom database queries).

Typical use cases:

• Look up real-time information (order status, account details, inventory) from your backend systems during conversations
• Create tickets, update CRM records, or trigger workflows in external systems based on conversation context
• Provide personalized recommendations by querying your product catalog

Each action has a name, description (which tells the AI when to trigger it), and a type-specific configuration. Actions can be enabled/disabled individually via the API. Actions are created and fully configured in the Quickchat Dashboard — the API provides list, update (enable/disable), and delete operations.

List All AI Actions

Scope: read_all

GET https://app.quickchat.ai/v1/api/ai_actions

Shell

curl https://app.quickchat.ai/v1/api/ai_actions \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/ai_actions",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

[
  {
    "id": 1,
    "name": "Check Order Status",
    "description": "Look up order status when customer asks about their order.",
    "is_active": true,
    "type": "http_request",
    "icon": null,
    "icon_color": null,
    "is_valid": true
  }
]

Field	Description
id integer	AI Action identifier
name string	Display name
description string	When the action triggers
is_active boolean	Whether enabled
type string	"http_request", "remote_mcp", or "shopify_remote_mcp"
icon string or null	Icon identifier
icon_color string or null	Icon color
is_valid boolean	Whether properly configured

Update AI Action

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/ai_actions/{action_id}

Request Body

Parameter	Description
is_active boolean	Enable/disable the action
icon string	Icon identifier (max 200 chars)
icon_color string	Icon color (max 50 chars)

Shell

curl -X PATCH https://app.quickchat.ai/v1/api/ai_actions/1 \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"is_active": false}'

Python

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/ai_actions/1",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={"is_active": False},
)
data = response.json()

Response 200 OK — Returns the updated AI Action snapshot.

Delete AI Action

Scope: write_all

DELETE https://app.quickchat.ai/v1/api/ai_actions/{action_id}

Shell

curl -X DELETE https://app.quickchat.ai/v1/api/ai_actions/1 \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.delete(
    url="https://app.quickchat.ai/v1/api/ai_actions/1",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)

Response 204 No Content

---

Chat (Legacy Auth)

Caution

The Chat endpoint uses legacy authentication and is not part of the modern API token system. For new integrations, consider using the API token-based endpoints above together with a webhook or polling approach for conversations.

The Chat endpoint uses legacy authentication with api_key and scenario_id in the request body. It does not use Bearer tokens.

Send Message

POST https://chat.quickchat.ai/chat

Request Body

Parameter	Description
api_key string, required	Your API key from the Dashboard
scenario_id string, required	ID of your AI Assistant
text string, required	User input message
conv_id string	Conversation ID. Omit to start a new conversation
message_context string	Additional per-message context passed to the AI
client_metadata object	Custom key-value pairs (max 5 keys) attached to messages

Shell

curl -X POST https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!",
  "conv_id": "abcd1234"
}'

Python

import requests

response = requests.post(
    url="https://chat.quickchat.ai/chat",
    json={
        "api_key": "<API_KEY>",
        "scenario_id": "<SCENARIO_ID>",
        "text": "Hello!",
        "conv_id": "abcd1234",
    },
)
data = response.json()

Response 200 OK

{
  "ord_number": 236,
  "conv_id": "abcd1234",
  "reply": "Hey there!"
}

Field	Description
ord_number integer	Sequential message number in the conversation
conv_id string	Conversation identifier (use to continue the conversation)
reply string	AI Assistant’s response