This is the full developer documentation for Quickchat AI # Introduction > Quickchat AI documentation — learn how to build, deploy, and manage no-code AI Agents for customer support, sales, and internal operations. Learn how Quickchat AI Platform helps businesses to build, deploy and manage advanced AI Agents for customer support, internal operations, and automated workflows. ![Quickchat AI Interface](/_astro/interface.aYquez7d_Mq5jC.webp) ## What is Quickchat AI? [Section titled “What is Quickchat AI?”](#what-is-quickchat-ai) Quickchat AI delivers an enterprise-grade Conversational AI platform for building [AI Agents](#what-are-ai-agents) that enhance both customer-facing and internal operations. It’s powered by a Four-Module System: * AI Identity / Personality * AI Knowledge Base * AI Actions * Insights from Conversations It enables businesses to build and deploy end-to-end AI Agents that continuously improve through smart feedback loops and AI-driven recommendations. ## What are AI Agents? [Section titled “What are AI Agents?”](#what-are-ai-agents) AI Agents are AI systems that communicate with users and execute tasks autonomously. Unlike simple chatbots, AI Agents are designed to understand natural language, provide meaningful answers, and take actions in external integrated systems. AI Agents built on the Quickchat AI Platform can: * Answer customer inquiries and provide 24/7 support. * Assist employees with finding information and streamlining processes. * Automate repetitive tasks like order tracking or appointment scheduling. * Provide detailed insights and recommendations for continuous improvement. Agents leverage advanced conversational AI to handle complex interactions while aligning with your unique business objectives. ## How does it work? [Section titled “How does it work?”](#how-does-it-work) Quickchat AI uses Large Language Models (LLMs) to create AI Agents that understand and generate natural language. The system combines LLM capabilities with tools for customization and integration to meet specific business needs. Here’s a breakdown of how it works: ## Large Language Models (LLMs) [Section titled “Large Language Models (LLMs)”](#large-language-models-llms) Quickchat AI integrates advanced LLMs, such as OpenAI’s GPT, which process and generate text based on user input. These models are trained on diverse datasets to understand natural language and provide meaningful responses. ## Our role [Section titled “Our role”](#our-role) Quickchat AI provides the tools and infrastructure to adapt these generic LLMs for enterprise use cases, enabling businesses to create purpose-built AI Agents. This includes: * **Knowledge Base Integration**: Extending LLMs with structured, business-specific knowledge, such as product details, FAQs, or internal documentation, ensuring accurate and context-aware responses. * **Conversation Control**: Configuring the Agent’s tone, behavior, and conversational flow to meet brand guidelines and business requirements. * **System Integration**: Connecting the AI Agent to APIs, databases, or internal tools for advanced capabilities, such as automating tasks or retrieving real-time information. * **Conversation Analytics**: Collecting and analyzing data from interactions to measure performance, detect issues, and improve the AI Agent over time. Analytics provide insights into user queries, response accuracy, and interaction trends, helping refine the AI Agent’s functionality and knowledge. ## The Output [Section titled “The Output”](#the-output) When deployed, the AI Agent processes your users’ inputs and generates responses that are: * **Natural**: Coherent and conversational, leveraging LLM language capabilities. * **Informed**: Based on your company knowledge. * **Actionable**: AI Agents can perform tasks such as retrieving data, updating records, or completing workflows when connected to external systems. This workflow ensures the AI Agent provides precise, contextually relevant, and actionable outputs while continually improving through analytics and feedback. Note If you need assistance, [reach out to us](https://quickchat.ai/contact). # Actions > Set up AI Agent actions — Human Handoff, Smart Data Gathering for lead generation, and Custom API Actions to connect external tools. Define what your Al Agent can do during conversation. From answering questions using real-time API data, collecting leads and market research data, to performing custom tasks. ## Human Handoff [Section titled “Human Handoff”](#human-handoff) The Human Handoff feature ensures that conversations requiring human attention are seamlessly transferred to a Human Agent. It is particularly useful for handling questions beyond the AI Agent’s Knowledge Base or when users explicitly request to speak to a person. During Human Handoff, the AI Agent pauses, and the Human Agent takes over the conversation via the Inbox. Here’s what happens on the user’s side: 1. The user interacts with the AI Agent. 2. If the request is beyond the AI’s capability or the user explicitly requests a human, the AI notifies the user about the transfer. 3. The conversation is unassigned from the AI and assigned to a Human Agent. 4. The Human Agent resolves the query or reassigns the AI Agent to continue. ![Human handoff from Visitor perspective.](/_astro/handoff_widget.BgkG8M6x_1SRQVJ.webp) And here’s what you’ll see inside the Quickchat AI interface: 1. The unassigned conversation appears in the Inbox. 2. Your team member reviews the AI Summary to understand the conversation so far. 3. The team member takes over the conversation and handles the user’s request. 4. The team member either marks the conversation as resolved or reassigns. ![Human handoff from Quickchat AI's User perspective.](/_astro/interface.aYquez7d_Mq5jC.webp) ### Enable Human Handoff [Section titled “Enable Human Handoff”](#enable-human-handoff) Navigate to **Actions & MCPs** in the left sidebar, find the **Human Handoff** card under **Quickchat AI Actions**, and toggle the switch to “on.” Click **Edit Action** to configure the details. ![Enabling human handoff in Quickchat AI's App.](/_astro/handoff_enable.BvVq3NDN_ZyWRfR.webp) You can then configure the following options: **Human Agent’s Availability** Define the availability of Human Agents to ensure that Handoff requests are only initiated during working hours. * Specify **Working Hours**: Set start and end times and select working days. * Select **Time Zone**: Ensure the schedule matches your region. * Configure an **Out-of-Hours Message**: Let users know when no Human Agents are available. ![Configuring Agent availability settings](/_astro/handoff_agents.DuBTGRTe_2qw67y.webp) ### Question [Section titled “Question”](#question) Define the question the AI will ask before initiating Handoff. **\*Example**: Would you like me to connect you with our Customer Support team?\* ![Configuring handoff question](/_astro/handoff_question.5WmeVKUk_9hpRB.webp) ### Confirmation [Section titled “Confirmation”](#confirmation) Specify the confirmation message sent when the Handoff is initiated. **\*Example**: I understand. I will transfer you to our Customer Support team. Please wait while I connect you.\* ![Configuring handoff confirmation message](/_astro/handoff_confirmation.DILiKVzw_1j8U5W.webp) ### AI Summary [Section titled “AI Summary”](#ai-summary) Enable AI Summaries to automatically generate a short note summarizing the conversation so far. This summary provides the Human Agent with all the context needed to quickly address the user’s request. ![Configuring AI summary settings](/_astro/handoff_summary.BZhJG5aU_Z5N3gf.webp) ### Handoff Rules [Section titled “Handoff Rules”](#handoff-rules) Describe the situations in which Human Handoff should be triggered. Each rule has a **Name**, a plain-language **Description**, and a **State** toggle so you can enable or disable rules without deleting them. Quickchat AI ships with a default set of rules covering the most common handoff triggers: * **Media Message** — the user sent an image, file, or other media the AI can’t process. * **User Frustration** — the user is explicitly angry, frustrated, or dissatisfied. * **Customer Support Suggestion** — the AI Agent has told the user to contact customer support as the next step, or has clearly ended AI-based assistance. * **Lack Of Knowledge** — the AI Agent has acknowledged it doesn’t have the necessary information. * **Irrelevant Advice** — the AI Agent has repeatedly tried to help but the user is still not satisfied. You can toggle any of these on or off, and add your own rules with a custom **Name** and **Description** that tells the AI when to trigger. Tip Write rule descriptions like instructions to the AI. *“The user has explicitly asked for a refund of more than $100”* is testable; *“escalate VIPs”* is not (the AI has no way to know who’s a VIP unless that’s in conversation metadata). In addition to rules, you can list **Keywords** that will **always** force a Human Handoff regardless of context — useful for compliance words like “lawsuit”, “GDPR”, or “chargeback” that you never want the AI to handle. ### Topic routing [Section titled “Topic routing”](#topic-routing) When Human Handoff fires, **Topic routing** sends the conversation to the human agent best suited to handle that topic instead of leaving it unassigned in a shared queue. Configure routing by mapping each topic (defined under **Insights → Manage Topics**) to one or more team members. When a handoff is triggered, Quickchat reads the conversation’s detected topic and routes the conversation to one of the agents assigned to that topic. If no rule matches, the conversation is left unassigned for any teammate to pick up from the Inbox. ### Email Notifications [Section titled “Email Notifications”](#email-notifications) Configure email addresses to receive notifications when a new conversation requires a Human Handoff. Here’s how it looks: ![Configuring email notification settings](/_astro/handoff_email.AI8iTEcp_Zv9bl7.webp) *** ## Smart Data Gathering / Lead Generation [Section titled “Smart Data Gathering / Lead Generation”](#smart-data-gathering--lead-generation) **Smart Data Gathering** allows your AI Agent to collect user information seamlessly during conversations. It engages with users naturally, asking relevant questions to gather details like name, email, phone number, or any other information you require. This data can then be sent to your CRM or other systems, enabling you to follow up effectively and convert potential leads into customers. ### How it works [Section titled “How it works”](#how-it-works) Smart Data Gathering operates within the existing conversation flow, ensuring that the interaction feels natural and non-intrusive. When a user interacts with your AI Agent, it: 1. Detects opportunities to collect information, such as when a user expresses interest in your services or products. 2. Asks specific questions tailored to your needs, like: * “Can I have your name to better assist you?” * “What’s the best email to contact you on?” 3. Gathers and stores the responses, making them available for review or integration with your CRM system. The feature is designed to minimize friction while maximizing the quality of leads captured. ### Setting it up [Section titled “Setting it up”](#setting-it-up) ### Enable Smart Data Gathering [Section titled “Enable Smart Data Gathering”](#enable-smart-data-gathering) * Navigate to the **Actions & MCPs** tab * Find **Smart Data Gathering** card * Toggle the feature on ![Enabling Smart Lead Generation](/_astro/leadgen_enable.C-xDKuYd_Z27MAyv.webp) ### Data to Collect [Section titled “Data to Collect”](#data-to-collect) Select contact details to capture. * Email address * First name * Phone number ![Selecting data fields to collect](/_astro/leadgen_data2collect.DsayYkv-_Z1ee1yk.webp) ### When to Ask for Data [Section titled “When to Ask for Data”](#when-to-ask-for-data) Define when the AI Agent should ask for contact details. * After exchanging a few messages * Immediately after the user expresses interest ![Configuring when to collect data](/_astro/leadgen_when_to_ask.HHWVbm3J_Z1663iN.webp) ### How to Ask for Data [Section titled “How to Ask for Data”](#how-to-ask-for-data) Customize how the AI Agent asks for information. * **Subtle:** Integrates questions naturally into the conversation * **Direct:** Explicitly requests the information in a straightforward manner ![Configuring data collection approach](/_astro/leadgen_how_to_ask.Dlu-o5LJ_Z2qsntK.webp) Smart Lead Generation enables your AI Agent to collect user contact details efficiently while ensuring compliance and providing a seamless conversational experience. ### Exporting the captured contact details [Section titled “Exporting the captured contact details”](#exporting-the-captured-contact-details) Follow these steps to export the details captured by your AI Agent: 1. Go to the **Inbox** 2. Click the **export file** icon to access export options. 3. Select **Export Gathered Data** from the dropdown menu. 4. Set **Date Range**: Specify the **start** and **end** dates for the data you want to export. 5. Choose **Format**: Select the file format for your export (CSV, XLSX). 6. Download: Click **Download** to save the exported data to your computer. *** ## Custom Actions [Section titled “Custom Actions”](#custom-actions) Custom Actions let your AI call external tools during a conversation — search internal systems, create tickets, trigger alerts, or fetch fresh data that isn’t in the Knowledge Base. Find them in **Actions & MCPs** under the **Custom Actions** section. Click **+ Add Action** to create one. The dropdown offers three types: * **API Action** — call any REST endpoint over HTTP. The most general option; use this for anything that has a URL and accepts JSON. * **HubSpot Action** — pre-built connection to your HubSpot CRM. Use it to look up contacts, deals, or tickets without managing API tokens yourself. * **Shopify MCP** — connect a Shopify store via the Shopify MCP server so the AI can query products, orders, inventory, and customers. Only one Shopify MCP action per scenario. Note The **Remaining: N** counter next to the **+ Add Action** button shows how many actions your plan lets you keep active. Separately, every agent can hold at most 15 actions overall, regardless of plan. Upgrade your plan if you need more active actions, or [contact us](mailto:contact@quickchat.ai). ### How Custom Actions work [Section titled “How Custom Actions work”](#how-custom-actions-work) 1. You define an action (API Action, HubSpot Action, or Shopify MCP) with a name, a detailed description, and any parameters the AI needs to fill in. 2. During a chat, the AI uses your description and parameter hints to decide when to run the action. 3. Quickchat executes the call and returns the result to the AI. The AI reads the response and replies to the user in natural language. 4. You can test the request from the Action editor before using it in conversations. Tip Write the description as an instruction to the AI. Tell it **when** to use the action, **what** it returns, and any **guardrails** (e.g., “only call when the user provides an order number”). ### Create an API Action [Section titled “Create an API Action”](#create-an-api-action) 1. Go to **Actions & MCPs**. 2. Click **+ Add Action** in **Custom Actions** and choose **API Action**. 3. Fill in **Details**: * **Name**: clear and descriptive. * **Description**: when to use it and what to include in parameters. 4. Configure **Connection**: * **Action Type**: HTTP method (GET, POST, etc.). * **Action endpoint URL**: full API URL. * **Headers**: add any required headers like `Authorization` or `content-type: application/json`. 5. Define **Parameters**: give each parameter a **name**, **location** (query, body, or header), and a **description** that tells the AI how to compose the value. Path values aren’t a parameter location; insert them directly in the endpoint URL using `{{placeholder}}` templating. 6. **Test request** and verify the response. Then click **Done**. Tip Any value field (URL, header, body, or query) accepts dynamic placeholders via the **+ Add AI Data** button. You can inject your AI parameters, built-in conversation variables (`{{scenario_id}}`, `{{language}}`, `{{country}}`, …), and conversation metadata (`{{metadata_*}}`). See [AI Action Variables](/ai-agent/variables/) for the full reference. ### Best practices [Section titled “Best practices”](#best-practices) * **Be explicit in descriptions**. Tell the AI when to use the action and what each parameter should contain. * **Keep scopes minimal**. Only include the headers and tokens the endpoint needs. For Jira, use the Basic header derived from your Atlassian email and API token. * **Test before rollout** using the Test request panel. Confirm status codes and sample payloads look right in the target tool. #### Tutorials [Section titled “Tutorials”](#tutorials) * [Connect an AI Agent to Jira tickets](/channels/jira/) (canonical reference) or the [narrated blog walkthrough](https://quickchat.ai/post/search-jira-tickets-in-ai-conversation) * [Send Slack notification with an AI Action](https://quickchat.ai/post/slack-notification-ai-action) # Images & files > What your AI Agent perceives when a visitor sends an image or a file. Images are analyzed visually; files are recognized by name, and their contents are not read. When a visitor sends an attachment during a conversation, your AI Agent treats **images** and **other files** differently. Knowing the difference helps you set the right expectations and write better Guidelines. ## Images [Section titled “Images”](#images) When a visitor sends a **photo or image**, your AI Agent actually **sees and analyzes the image content**. It can describe what’s in the picture, read text visible in it, and answer questions about it — the image is sent to the underlying vision-capable model alongside the visitor’s message. This works on every plan, and on every channel where a visitor can attach an image (Telegram, WhatsApp, Intercom, HubSpot, and images supplied through the [Quickchat API](/channels/api/)). Note If an image can’t be loaded (for example, an expired or unreachable link), the AI Agent simply continues with the text of the message instead of failing the reply. ## Files (PDFs, documents, and other attachments) [Section titled “Files (PDFs, documents, and other attachments)”](#files-pdfs-documents-and-other-attachments) When a visitor sends a **non-image file** — a PDF, a Word document, a spreadsheet, an audio or video file — your AI Agent is **told that a file was sent and its filename**, but it **does not read the file’s contents**. The Agent knows, for instance, that `invoice_2026.pdf` arrived, so it can acknowledge the file and respond sensibly, but it cannot extract or summarize what’s inside it. Inbound file awareness is available on these channels: | Channel | Visitor sends an **image** | Visitor sends a **file** (PDF, doc, …) | | ------------------------------- | -------------------------- | -------------------------------------- | | [Telegram](/channels/telegram/) | Analyzed visually | Filename only | | [WhatsApp](/channels/whatsapp/) | Analyzed visually | Filename only | | [Intercom](/channels/intercom/) | Analyzed visually | Filename only | | [HubSpot](/channels/hubspot/) | Analyzed visually | Filename only | Tip If you want the AI Agent to help with file contents, ask the visitor to paste the relevant text into the chat, or rely on **Human Handoff**. The default **Media Message** handoff rule escalates a conversation to a human when a visitor sends an image or file the AI can’t process — see [Actions → Handoff Rules](/ai-agent/actions/#handoff-rules). Caution This is separate from the **Knowledge Base**, which is text-only: you can upload PDFs and documents there and Quickchat extracts their text for the Agent to use as knowledge (see [Upload File](/ai-agent/knowledge-base/#upload-file)). The behavior on this page is about files a **visitor** sends mid-conversation, which are not added to the Knowledge Base. # Identity > Configure your AI Agent's identity — set its name, main prompt, guidelines, personality, profession, creativity level, and supported languages. The **AI Identity** section allows you to define the personality and behavior of your AI Agent. ## Profile [Section titled “Profile”](#profile) Profile is a place where you set up the **AI Agent Name**, **AI Main Prompt**, and **AI Guidelines** to align the AI with your business goals. ### AI Agent Name [Section titled “AI Agent Name”](#ai-agent-name) This name will be used when the AI introduces itself to users and will appear in chat interfaces. * The AI Agent Name should reflect your brand image and its role. * You can change the name at any time. The name is required and limited to 40 characters. For reference, the Main Prompt allows up to 15,000 characters and Guidelines up to 1,000 words (5,000 characters). **Example**: Superfoodie AI ### AI Main Prompt [Section titled “AI Main Prompt”](#ai-main-prompt) The **AI Main Prompt** is where you describe your AI Agent’s role and how it should behave in every conversation. It’s the core set of instructions the Agent uses on every message — its scope, tone, primary goals, and any non-negotiable behaviors all belong here. Effective prompts usually cover: * **Role and scope** — who the AI Agent is and what topics it should handle. * **Primary goals** — what it should do in different situations (answer support questions, recommend products, qualify leads, etc.). * **Guardrails** — what it must never do or say (e.g., never discuss competitors, never quote internal documents verbatim). * **Tone** — formal, friendly, playful, concise, and so on. Example: *You are Superfoodie AI, the shopping assistant for Superfoods — an online, 100% plant-based superfoods marketplace. Help visitors choose the right product, share current offers when relevant, and answer questions about ingredients, sourcing, and shipping. If a question is outside your scope, politely redirect to the support email.* **Templates** Click the **Templates** button at the bottom-left of the prompt textarea to start from a pre-built prompt tailored to a common use case: * **Customer support** — answer product questions, troubleshoot, hand off to a human when needed. * **Lead generation** — qualify visitors and collect contact details during the conversation. * **Shopping assistant** — recommend products and guide buying decisions. You can freely edit any template after applying it. Tip Be specific. Vague prompts produce vague behavior. Treat the prompt like a job description for a new hire — the more clarity you give about role, scope, and edge cases, the more consistent the AI Agent’s responses will be. ### AI Guidelines [Section titled “AI Guidelines”](#ai-guidelines) Your AI Guidelines should define how the AI Agent interacts with users. Use Guidelines as a **reactive tool** — don’t make assumptions about the AI’s behavior before testing. Add new Guidelines only after identifying issues based on the AI’s actual performance. Note The AI Guidelines field depends on your plan and privileges. It may be locked or not appear for all accounts. Below are some questions to help you create clear Guidelines. What questions should the AI Agent avoid answering? Example: Never answer questions about delivery status inquiries, new product rumors. Instead always ... How should the AI Agent behave? Example: Always include follow-up questions, use emojis in responses Are there topics the AI Agent should handle in a specific way? Example: Provide general advice on health-related questions but avoid giving specific medical recommendations. What information should the AI Agent mention often? Example: After few messages, try to share promo code: XYZ which is valid until 30th of may (today is 26th of may). Tip **Tips for creating AI Guidelines** * Keep guidelines clear and specific, with minimal overlap * Aim for 5-10 rules that define what the AI should and should not do * Adjust further the tone and style of communication after setting up **AI Personality** * Highlight priorities like promoting discounts or linking helpful resources ## Conversation style [Section titled “Conversation style”](#conversation-style) ### AI Personalities [Section titled “AI Personalities”](#ai-personalities) AI Personalities let you define the tone and interaction style of your AI Agent. These Personalities align the AI’s communication style with your brand’s voice and user expectations. Choose among 13 AI Personalities available. Click to expand and learn more about each AI Personality * **Classic** provides a balance between professionalism and approachability. It is ideal for most use cases and ensures clear and neutral communication. * **Humorous** uses puns, jokes, and lighthearted language to create fun and engaging interactions. Perfect for casual and enjoyable conversations. * **Formal** maintains a serious and professional tone, offering concise and factual responses. Suitable for corporate and business settings. * **Friendly** delivers a warm, conversational, and approachable interaction style. Great for creating a welcoming user experience. * **Intelligent** provides detailed, accurate information with a focus on in-depth explanations. Ideal for users looking for comprehensive answers or technical details. * **Empathetic** focuses on understanding and showing care for users’ emotions. Suitable for scenarios requiring emotional sensitivity, like customer support or mental health applications. * **Inspiring** encourages users with motivational and positive language, fostering an uplifting experience. Ideal for coach-like or goal-oriented use cases. * **Adventurous** inspires excitement and curiosity, encouraging users to explore new opportunities and ideas. Great for travel, lifestyle, or innovation-focused brands. * **Elegant** delivers a sophisticated and refined conversational style. Ideal for luxury brands or high-end products focusing on exclusivity. * **Excited** offers an energetic and lively tone, making interactions dynamic and fun. Perfect for scenarios requiring enthusiasm. * **Bold** provides confident and assertive communication, offering strong opinions and recommendations. Ideal for decision-making use cases. * **Mysterious** delivers cryptic and intriguing responses, sparking curiosity and fascination. Suitable for users looking for a unique and captivating experience. * **Sassy** provides playful and confident interactions with humor and flair. Perfect for creating memorable and cheeky conversations. Note If you need a tone specifically tailored to your brand, you can request a **Custom Personality** by [contacting us](https://www.quickchat.ai/contact-us). ### AI Professions [Section titled “AI Professions”](#ai-professions) AI Professions define the AI Agent’s goal and approach to interacting with users, tailoring its behavior to specific use cases: * **Helpful Assistant** is the default, versatile option suitable for most scenarios. It provides general-purpose responses and is adaptable across different industries. * **Support Agent** is ideal for empathetic customer support. It delivers step-by-step troubleshooting, answers common queries, and helps users resolve issues. * **Shopping Assistant** focuses on e-commerce, proactively recommending products, providing links to product detail pages, and guiding users through the sales process. * **Field Expert** acts as a knowledgeable consultant, offering detailed responses and expert advice in a specific domain. * **Interviewer** asks questions instead of providing answers. This approach is great for collecting feedback, conducting surveys, or engaging users in exploratory conversations. ### AI Creativity [Section titled “AI Creativity”](#ai-creativity) AI Creativity controls how the AI Agent responds when it encounters a question not covered by the Knowledge Base: * **Low Creativity:** AI does not improvise and responds with “I don’t know” when the answer isn’t available. * **Normal Creativity:** AI cautiously improvises while acknowledging gaps in its knowledge. * **High Creativity:** AI makes inferences and generates answers based on existing knowledge, even without direct responses. ### Reply Length [Section titled “Reply Length”](#reply-length) Reply Length adjusts how much information the AI Agent includes in its responses. * **Short:** provides concise and to-the-point replies. * **Normal:** delivers well-rounded and balanced responses. * **Longer:** includes more detailed and comprehensive replies for users needing in-depth information. ### Links Priority [Section titled “Links Priority”](#links-priority) Links Priority determines how often links are included in the AI Agent’s responses. * **Normal:** includes links when relevant but keeps them secondary to other information. * **High:** prioritizes links, ensuring they appear more frequently in responses and take precedence over other content. ## Languages [Section titled “Languages”](#languages) Your AI Agent can speak any language out of the box. The **Languages** tab is where you tell the AI which languages your team is prepared to support — that list helps the AI pick the right one when the visitor’s language is ambiguous. How it works: * The AI **automatically detects the visitor’s language** from their first message and replies in that language. * The languages you add here act as a **shortlist of supported languages**. If the visitor’s language is unclear (e.g., a very short message, mixed languages, or a language outside your shortlist), the AI falls back to a language from your list. * Add languages by clicking **Add** at the bottom of the list. Remove a language with the **×** button next to it. # Knowledge Base > Build and manage your AI Agent's Knowledge Base. Learn how to add content, structure information, and optimize for accurate AI responses. The **Knowledge Base** is the core component of your Quickchat AI Agent. It serves as the foundation for your AI Agent’s understanding of your company, products, and services. A well-structured and comprehensive Knowledge Base ensures your AI Agent can effectively handle user queries and deliver accurate responses. This guide provides an overview of the Knowledge Base, strategies for building it effectively, and tips for optimizing its performance. ## Data sources [Section titled “Data sources”](#data-sources) The toolbar at the top of the Knowledge Base page lets you add knowledge from any of these sources: ### Add Article [Section titled “Add Article”](#add-article) Manually-written articles. Title + rich-text body. Use this when you want full control over the exact wording — FAQs, internal policies, product specs, or anything you’d otherwise paste from a doc. Tip Keep each article focused on a single topic. Long, multi-topic articles confuse retrieval — splitting them gives the AI cleaner answers. ### Add Paragraph [Section titled “Add Paragraph”](#add-paragraph) Short, atomic facts that don’t need a full article. Paragraphs are grouped together (e.g., under a “Single Paragraphs” folder) and treated as bite-sized knowledge units. Good for one-liners like *“Shipping takes 3–5 business days”* or *“Returns are accepted within 30 days”*. ### Add Website [Section titled “Add Website”](#add-website) Import content from any URL. Four import modes: * **Single Page** — imports one webpage. Use **Advanced options → HTML selector** to restrict the import to a specific part of the page (e.g., `main`, `#article-body`, `.docs-content`) when the rest of the page is navigation, ads, or footer. * **Multiple Pages** — paste a list of URLs; each becomes its own article. * **Sitemap** — point at a `sitemap.xml`; every page in the sitemap is imported as a separate article. Best for documentation sites and structured blogs. * **All Pages** — site-wide crawl of every reachable URL on the domain. Use for full documentation imports or company blogs. URLs stay linked to their source. You can re-pull the latest content for one article from its row menu, or use **Refresh all URLs** in the top right to re-pull every URL-backed article at once. ### Upload File [Section titled “Upload File”](#upload-file) Upload documents (PDF, Word, PowerPoint, Excel/CSV) and more; scanned images are OCR’d. Text is extracted automatically and indexed. Max file size: **32 MB**. ### Shopify MCP [Section titled “Shopify MCP”](#shopify-mcp) Connect your Shopify store so the AI can answer questions grounded in your live product catalog, orders, and inventory. Paste your store URL to set up the connection. Behind the scenes this configures a **Shopify MCP** Custom Action — you can also manage it from **Actions & MCPs**. See [Custom Actions](/ai-agent/actions/#custom-actions). ### Intercom Articles [Section titled “Intercom Articles”](#intercom-articles) Bulk-import every article from your connected Intercom Help Center. Requires Intercom to be connected under **External Apps → Intercom** first. Re-running the import syncs new and updated articles. ### YouTube [Section titled “YouTube”](#youtube) Paste a YouTube URL to import the video’s transcript as an article. Useful for tutorial channels and product walkthroughs you don’t want to re-write by hand. ## **Tips for building an effective Knowledge Base** [Section titled “Tips for building an effective Knowledge Base”](#tips-for-building-an-effective-knowledge-base) Each uploaded text article, URL, or PDF should be self-contained and comprehensive, covering the topic thoroughly. A well-structured Knowledge Base ensures the AI Agent has the necessary context to respond effectively. Read the below tips to set your AI Agent for success: ## Steps to build and refine your Knowledge Base [Section titled “Steps to build and refine your Knowledge Base”](#steps-to-build-and-refine-your-knowledge-base) 1. **Get clear on the purpose**\ Define the role of your AI Agent and the types of questions it will answer. Organize your knowledge into categories based on user needs and flows. **E-Commerce AI Agent Example:** * **Browsing & Shopping**: Product details, comparisons, and FAQs. * **Buying**: Payment methods, discount codes, and taxes. * **Delivery**: Shipping, order modifications, and tracking. **Student Loan AI Agent Example:** * **Before Applying**: Eligibility and loan conditions. * **Applying**: Guides, terms, and walkthroughs. * **After Graduation**: Repayment schedules and deferrals. 2. **Ensure data quality**\ The quality of AI responses depends on the data you upload. Focus on: * **Readability**: Remove irrelevant information, tables, or redundant headers from uploaded content. * **Relevance**: Ensure the content answers common questions and aligns with user expectations. * **Consistency**: Avoid contradictory or outdated information, and ensure consistent formatting (e.g., dates, prices). * **Text-only content**: Since images are not supported, ensure vital information is conveyed through text. 3. **Prioritize clarity**\ Ensure each article is clear, concise, and easy to follow. Use logical paragraph structures and focus on relevant details. 4. **Be exhaustive**\ Provide as much detail as possible to equip your AI Agent with the knowledge needed to handle complex queries. 5. **Use answers instead of Q\&A**\ Focus on providing comprehensive information rather than specific question-and-answer pairs. The AI Agent can extract relevant details as needed. 6. **Embed URLs within text**\ Always include URLs within the text for reference. Even when uploading via the URL uploader, linking to products or forms within the text improves usability. **Example**:\ For an e-commerce AI Agent, include links to forms like order cancellation:\ *“To cancel an order, submit a request here: .”* 7. **Test thoroughly**\ Testing is essential to refine your Knowledge Base. Simulate user interactions to identify gaps or inconsistencies and adjust the content accordingly. ## **Common issues** [Section titled “Common issues”](#common-issues) * **The AI Agent skips links or doesn’t include URLs in responses** Ensure relevant links are embedded within the text of each article. * **Repeated or redundant information** Avoid uploading duplicate content across multiple Articles. * **Missing key details in responses** Consider creating separate Articles for specific details, like criteria or special cases. * **Incorrect dates or prices** Verify and update all Articles to maintain accuracy. Building an effective Knowledge Base is an iterative process. Start with clear objectives, organize content logically, and test extensively to refine your AI Agent’s performance. Note If you need assistance setting up your Knowledge Base or require custom integrations, feel free to reach out to us at ****. ## **Search** [Section titled “Search”](#search) The **Search** feature allows you to quickly find specific articles in your Knowledge Base by searching through **both their titles and content**. **How to use search** 1. Enter keywords or phrases into the **Search** bar at the top of the Knowledge Management interface. 2. The results will instantly update to display articles containing the entered text in their title or content. ## Multi-select and bulk delete [Section titled “Multi-select and bulk delete”](#multi-select-and-bulk-delete) The multi-select and bulk delete functionality makes it easy to manage multiple articles in your Knowledge Base. **How to use multi-select** 1. Navigate to the Knowledge Base list 2. Click the “…” sign next to the Article you want to select and click “Select” 3. Check the boxes on the left next to the Articles you want to select. You can select one or multiple articles simultaneously 4. Once selected, the Articles will remain highlighted for further actions **How to perform bulk delete** 1. After selecting the articles using the multi-select feature, click the **Delete** option at the bottom to remove the selected articles 2. Confirm your action to delete all selected articles permanently ## Tags [Section titled “Tags”](#tags) Tags help you organize the Knowledge Base and let the AI Agent narrow down which articles to consult for a given question. You’ll see tags on every article row and as a filter at the top of the list. There are two ways to tag an article: * **Manually** — open an article and use **+ Add Tag** in the right-hand metadata panel. * **Auto-tag with AI** — click **Auto-tag with AI** in the same panel. Quickchat reads the article and suggests tags based on its content. Useful for bulk-imported KB (Sitemap, All Pages, Intercom) where manually tagging hundreds of articles isn’t realistic. Use the **Tags** filter in the toolbar to narrow the list to articles matching one or more tags. ## Retraining your AI Agent [Section titled “Retraining your AI Agent”](#retraining-your-ai-agent) Adding, editing, or deleting articles doesn’t update the live AI Agent immediately. After meaningful changes you’ll see an orange banner at the top of the app: > **AI Knowledge is outdated. Retrain required.** Click **Retrain AI** in the banner to push the latest Knowledge Base to your live Agent. Retraining typically takes under a minute. Caution Retraining affects the **live** AI Agent — including any deployed widget, channel integration, or API consumer. Always test changes via **AI Preview** or a [simulation dataset](/conversations/testing/) before retraining if your Agent is in production. You only need to retrain after **Knowledge Base** changes. Identity, Inbox replies, Insights, and Conversation Rating settings take effect immediately. # AI Action Variables > Inject dynamic values into your API Actions using {{...}} placeholders. AI parameters, built-in conversation variables, and conversation metadata. Anywhere you can type a value in an API Action (URL, headers, body, or query parameters) you can inject dynamic values using the `{{...}}` syntax. Quickchat substitutes these placeholders at request time, just before calling your endpoint. Click the **+ Add AI Data** button next to any value field to browse every variable available in the current scenario. ![The API Action editor with "+ Add AI Data" buttons highlighted next to the endpoint URL and each header's value field](/_astro/01-add-ai-data-buttons.DHRitqS6_frAhW.webp) *The **+ Add AI Data** button is available next to every value field: the endpoint URL, each header value, body fields, and query parameters.* ## Three categories of variables [Section titled “Three categories of variables”](#three-categories-of-variables) | Category | Syntax | When it’s filled | | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **AI parameters**. Values your AI Agent extracts from the conversation. You define them under each Action’s **Parameters** section. | `{{order_number}}`, `{{customer_email}}` | The AI Agent fills these at call time, based on the rules you write into each parameter’s description. | | **Built-in variables**. Conversation context Quickchat injects automatically. | `{{scenario_id}}`, `{{conversation_id}}`, `{{language}}`, `{{country}}`, … | Always available. Quickchat substitutes them on every request. | | **Conversation metadata**. Custom key-value pairs attached to the conversation. | `{{metadata_}}` | Whenever the corresponding key exists on the conversation (set by the widget, a channel integration, Smart Data Gathering, or the API). | Tip Each variable is rendered as a coloured **pill** inside the editor. Blue means it’s an AI parameter or a built-in. Orange means it’s a metadata variable or a system token. Red means the name doesn’t match anything Quickchat knows (usually a typo). ## The ”+ Add AI Data” dropdown [Section titled “The ”+ Add AI Data” dropdown”](#the--add-ai-data-dropdown) The dropdown lists every variable available for the current scenario, grouped into five sections: 1. **Parameters**: the AI parameters you defined on this Action. 2. **Visitor**: four metadata keys auto-captured for every visitor, when their channel provides them. 3. **Metadata (used in recent conversations)**: custom metadata keys seen on this scenario’s last 20 conversations, with a sample value for each. 4. **Built-in**: the six conversation variables that are always available, with their current value or a sample shown inline. 5. **System Tokens**: credentials provided by a connected integration (e.g. HubSpot). Only appears if the integration is connected. ![The "+ Add AI Data" dropdown opened, showing the Parameters, Visitor, Metadata (used in recent conversations), and Built-in sections with sample values inline](/_astro/02-dropdown-sections.5byXjHSt_EnqRf.webp) *The dropdown groups variables into sections. **Built-in** rows show the live value where it’s already known (`scenario_id`) and `e.g. …` samples for the rest. The **Metadata (used in recent conversations)** group is rebuilt per scenario from real recent conversations. The **System Tokens** section (not shown here) appears only when an integration is connected.* Note The **Metadata (used in recent conversations)** list is rebuilt from your scenario’s most recent 20 conversations and **cached for 5 minutes per AI Agent**. A metadata key set on a brand-new conversation may take up to 5 minutes to appear in this section. You can always type `{{metadata_}}` directly: Quickchat doesn’t require the key to appear in the dropdown for the substitution to work. ## Built-in variables [Section titled “Built-in variables”](#built-in-variables) These six variables are always available. The **+ Add AI Data** dropdown shows the live value (where it’s already known) or a sample value next to each row. | Variable | Example | What it is | | -------------------------- | -------------------------------------------- | ------------------------------------------------------ | | `{{scenario_id}}` | `abc123xyz` | ID of the AI Agent the conversation belongs to. | | `{{conversation_id}}` | `conv-d8a8…` | Unique identifier of the conversation. | | `{{conversation_url}}` | `https://app.quickchat.ai/.../conv-d8a8…` | Direct Inbox link to this conversation. | | `{{conversation_channel}}` | `widget`, `telegram`, `slack`, `whatsapp`, … | Channel the conversation is happening on. | | `{{language}}` | `en`, `nl`, `de`, `fr`, … | ISO 639-1 lowercase code of the conversation language. | | `{{country}}` | `US`, `GB`, `NL`, `DE`, … | ISO 3166-1 alpha-2 uppercase country code. | A few notes worth knowing: * **`{{scenario_id}}`** is also visible in your browser URL while editing the Action. The **+ Add AI Data** dropdown shows the **live** ID for the scenario you’re editing, not a sample. * **`{{conversation_url}}`** is useful for posting clickable links into Slack, Jira, or any other tool that benefits from a direct jump back to the Inbox. * **`{{language}}`** is derived from (in this order): the page URL prefix (for Shopify Markets), conversation metadata, then your AI Agent’s configured language. * **`{{country}}`** is derived from (in this order): the page URL prefix, the URL host TLD, then a language-to-country fallback. ## Conversation metadata [Section titled “Conversation metadata”](#conversation-metadata) The `metadata_` prefix is required. Quickchat looks up `` in the conversation’s metadata and substitutes its value into the request. ```plaintext {{metadata_order_id}} → ord_8a4f3… {{metadata_customer_tier}} → gold ``` ### Visitor metadata keys [Section titled “Visitor metadata keys”](#visitor-metadata-keys) These four keys describe the visitor’s session and get their own **Visitor** section in the dropdown. They are auto-captured by the channel, integration, widget/embed, or API. You don’t need to push them yourself. | Variable | Auto-captured by | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `{{metadata_fullPathURL}}` | Website widget, website embed, or chat-channel integrations that include their own widget (HubSpot, Intercom, etc.). | | `{{metadata_visitor_name}}` | Chat-channel profile (Telegram, Slack, etc.), channel integrations, Smart Data Gathering, your widget/embed, or the Quickchat API. | | `{{metadata_visitor_email}}` | Chat-channel profile, channel integrations, Smart Data Gathering, your widget/embed, or the Quickchat API. | | `{{metadata_visitor_phone_number}}` | WhatsApp and other phone-aware channels, channel integrations, Smart Data Gathering, your widget/embed, or the Quickchat API. | ### Custom metadata keys [Section titled “Custom metadata keys”](#custom-metadata-keys) You can attach arbitrary key-value pairs to a conversation and reference them as `{{metadata_}}`. **From the website widget or embed** Pass `custom_params` when you initialise the widget. See the [Website channel: Advanced Features: Custom Parameters](/channels/website/#advanced-features-custom-parameters) section for the full snippet. ```html ``` Reference them in any Action as `{{metadata_order_id}}` and `{{metadata_customer_tier}}`. Caution Metadata keys must match `^[a-zA-Z0-9_]+$` (letters, digits, underscores). Keys with spaces or other punctuation **cannot** be referenced as `{{metadata_}}`. They will still appear in the conversation’s metadata view in the Inbox, but the Action substitution will skip them. Stick to snake\_case names when you intend to use them in Actions. **From Smart Data Gathering** Each field name you configure in a Smart Data Gathering campaign becomes a metadata key under the same name. If your campaign collects `delivery_address`, you can immediately use `{{metadata_delivery_address}}` in any subsequent API Action. **From channel integrations** HubSpot, Intercom, Telegram, Slack, WhatsApp, and similar integrations push their own metadata onto the conversation (visitor name, email, page URL, account properties, etc.). Anything visible in the conversation’s metadata view in the Inbox can be referenced via `{{metadata_}}`. **From the Quickchat API** Use `POST /v1/api_core/conversations/{conv_id}/metadata` to attach metadata programmatically. See [Conversation Metadata](/api-reference/conversations/conversation-metadata/) in the API reference. ## Pill colours in the editor [Section titled “Pill colours in the editor”](#pill-colours-in-the-editor) Every `{{...}}` reference is rendered as a coloured pill so you can tell at a glance whether Quickchat recognises the variable. ![API endpoint URL containing an orange {{metadata\_user\_type}} pill, and a Language header value containing a blue {{language}} pill](/_astro/03-pills-in-url-and-header.Dhoi-IMn_Z1WRcMw.webp) *Pills work in every value field. Above: an orange `{{metadata_user_type}}` pill in the endpoint URL, and a blue `{{language}}` pill in a header value.* ![JSON request body with a blue {{country}} pill and an orange {{metadata\_fullPathURL}} pill](/_astro/04-pills-in-body.Cba5nJkM_dKjft.webp) *The same colour rules apply inside a JSON request body. Built-in variables like `{{country}}` render blue, metadata variables like `{{metadata_fullPathURL}}` render orange.* * 🔵 **Blue**: a built-in variable or an AI parameter you defined. * 🟠 **Orange**: a metadata variable (`{{metadata_*}}`) or a System Token from a connected integration. * 🔴 **Red**: Quickchat doesn’t recognise this name. Almost always a typo. Fix the spelling, define it as an AI parameter, or (if it really is a metadata key) make sure it starts with `metadata_`. Tip Typing `{{metadata_anything}}` directly is always valid, even if the key has never appeared on a conversation yet. The pill will be orange, not red. This is the right way to wire up keys you set yourself from a widget script or Smart Data Gathering before the first conversation has happened. ## Testing your Action [Section titled “Testing your Action”](#testing-your-action) The **Test Response** sheet (next to **Done** in the Action editor) lets you send a real HTTP request without going through a chat. For each variable referenced in the Action, you’ll see an input row to fill in the value Quickchat will substitute. Two convenience pre-fills: * `{{language}}` defaults to `en` * `{{country}}` defaults to `US` Override either field to test a different locale. All other variables (your AI parameters, `{{metadata_*}}` keys, and the other built-ins) start blank. Type any value to simulate what would happen in a live conversation. ## FAQ [Section titled “FAQ”](#faq) **Why does my variable appear in red?** The editor doesn’t recognise the name. Either it’s a typo, it doesn’t match any AI parameter you’ve defined, it isn’t a built-in variable, or it’s a metadata key that’s missing the `metadata_` prefix. **Can I inject `{{language}}` or `{{country}}` even if I never set them?** Yes. Quickchat always derives both from the conversation context (page URL, browser locale, or your AI Agent’s configured language). You’ll always get a value, even if it falls back to `en` / `US`. **What’s the difference between `{{language}}` and `{{metadata_locale}}`?** * `{{language}}` is the built-in. Always available, always in `en` / `nl` / `de` … format. Use this 99% of the time. * `{{metadata_locale}}` only exists if a channel integration or your widget explicitly set a `locale` key on the conversation metadata, often in `xx_YY` format (e.g. `en_GB`). Reach for this only when you need the exact locale string verbatim. **Is there a limit on the number of AI parameters per Action?** Yes, **30 per Action**. If you genuinely need more, [contact support](mailto:contact@quickchat.ai). **Are built-in and metadata values sent to the AI?** No. They’re injected into the HTTP request **after** the AI has decided to call the Action. The AI doesn’t see them and isn’t asked to fill them in. That’s why they don’t need to be defined as AI parameters. **How often is the “Metadata (used in recent conversations)” list refreshed?** It’s cached for 5 minutes per AI Agent. A metadata key set on a brand-new conversation may take up to 5 minutes to appear in the dropdown, but you can always type `{{metadata_}}` directly without waiting. **Are metadata key names case-sensitive?** Yes. `{{metadata_orderId}}` and `{{metadata_orderid}}` are different keys. Use exactly the same casing you set on the widget, integration, or API side. **Does the Test Response sheet know about these variables?** Yes. When your Action references `{{language}}` or `{{country}}`, the Test Response sheet pre-fills them with `en` and `US` respectively. All other variables start blank. Type any value to simulate a live call. ## Related [Section titled “Related”](#related) * [Custom Actions](/ai-agent/actions/#custom-actions): how to create and configure an API Action. * [Website channel: Custom Parameters](/channels/website/#advanced-features-custom-parameters): how to push metadata from your website. * [API: Conversation Metadata](/api-reference/conversations/conversation-metadata/): how to push metadata programmatically. # Overview > REST API reference for the Quickchat AI platform — authentication, base URL, rate limits, pagination, and error handling. Quickchat AI provides a REST API for programmatic access to your AI Agent’s configuration, Knowledge Base, Conversations, AI Actions, and more. ## Authentication [Section titled “Authentication”](#authentication) All API endpoints use Bearer token authentication. Include your API token in the `Authorization` header of every request: ```plaintext Authorization: Bearer ``` Tokens are created in the [Quickchat Dashboard](https://app.quickchat.ai/) under **External Apps > 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 Agent (scenario) Note The realtime Chat endpoint (`POST https://app.quickchat.ai/chat`) accepts the same Bearer token as the rest of this API, but it lives outside the `/v1/api/` base path and requires `scenario_id` in the request body. See the [Chat](/api-reference/chat/) page for the full reference. ### Token Scopes [Section titled “Token Scopes”](#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 **External Apps > 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 [Section titled “Base URL”](#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/` | | Realtime Chat | `https://app.quickchat.ai/chat` | ## Rate Limits [Section titled “Rate Limits”](#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 [Section titled “Pagination”](#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: ```json { "items": [], "offset": 0, "limit": 10, "count": 100 } ``` ## Error Handling [Section titled “Error Handling”](#error-handling) All errors are returned as JSON in the following format: ```json { "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 | *** # AI Actions > Manage your AI Agent's AI Actions via the API. ## AI Actions [Section titled “AI Actions”](#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](https://app.quickchat.ai/) — the API provides list, update (enable/disable), and delete operations. ### List All AI Actions [Section titled “List All AI Actions”](#list-all-ai-actions) Scope: read\_all `GET https://app.quickchat.ai/v1/api/ai_actions` * Shell ```shell curl https://app.quickchat.ai/v1/api/ai_actions \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api/ai_actions", headers={"Authorization": "Bearer "}, ) data = response.json() ``` **Response** `200 OK` ```json [ { "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"`, `"shopify_remote_mcp"`, or `"knowledge_base"` | | `icon` string or null | Icon identifier | | `icon_color` string or null | Icon color | | `is_valid` boolean | Whether properly configured | ### Update AI Action [Section titled “Update AI Action”](#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 ```shell curl -X PATCH https://app.quickchat.ai/v1/api/ai_actions/1 \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"is_active": false}' ``` * Python ```python import requests response = requests.patch( url="https://app.quickchat.ai/v1/api/ai_actions/1", headers={"Authorization": "Bearer "}, json={"is_active": False}, ) data = response.json() ``` **Response** `200 OK` — Returns the updated AI Action snapshot. ### Delete AI Action [Section titled “Delete AI Action”](#delete-ai-action) Scope: write\_all `DELETE https://app.quickchat.ai/v1/api/ai_actions/{action_id}` * Shell ```shell curl -X DELETE https://app.quickchat.ai/v1/api/ai_actions/1 \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.delete( url="https://app.quickchat.ai/v1/api/ai_actions/1", headers={"Authorization": "Bearer "}, ) ``` **Response** `200 OK` (empty body) *** # Chat > Talk to your AI Agent programmatically with the realtime Chat endpoint — ideal for building a custom chat UI. ## Chat [Section titled “Chat”](#chat) The realtime Chat endpoint sends a visitor message to your AI Agent and returns the AI reply in a single round-trip. This is the endpoint you want when building a custom chat UI on top of Quickchat AI. It differs from the other endpoints in two ways: it sits at `app.quickchat.ai/chat`, outside the `/v1/api/` and `/v1/api_core/` base paths, and it reads `scenario_id` from the request body rather than from the token. It uses the same Bearer token authentication as the rest of this API. Note Send every request to `https://app.quickchat.ai/chat`. The `scenario_id` in the body must match the AI Agent your Bearer token is bound to. ### Send Message [Section titled “Send Message”](#send-message) `POST https://app.quickchat.ai/chat` **Request Body** | Parameter | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `scenario_id` string, required | ID of your AI Agent. Must match the `scenario_id` bound to the Bearer token | | `text` string, required | User input message | | `conv_id` string | Conversation ID. Omit on the first request to start a new conversation, then pass the returned `conv_id` back on subsequent requests to continue it | | `client_metadata` object | Custom key-value pairs (we recommend at most 5 keys) attached to every message. Displayed as data columns in the conversation export in the Inbox | A request without `conv_id` starts a new conversation, and the generated `conv_id` is returned in the response. Store that `conv_id` and send it back on later requests to maintain conversation context across multiple user interactions. * Shell ```shell # Start a new conversation by omitting conv_id curl -X POST https://app.quickchat.ai/chat \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "scenario_id": "", "text": "Hello!" }' ``` * Python ```python import requests response = requests.post( url="https://app.quickchat.ai/chat", headers={"Authorization": "Bearer "}, json={ "scenario_id": "", "text": "Hello!", }, ) data = response.json() ``` **Response** `200 OK` ```json { "conv_id": "conv-uuid-1234", "reply": "Hi there! How can I help you today?", "ord_number": 3, "src": 0 } ``` | Field | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------- | | `conv_id` string | Conversation identifier. Always returned. Pass it back in the `conv_id` body field to continue the conversation | | `reply` string | The AI Agent’s response. May contain HTML such as `
` line breaks | | `ord_number` integer | Sequential message number within the conversation | | `src` integer | Internal source indicator. API clients can ignore this field | To continue an existing conversation, pass back the `conv_id` you received: * Shell ```shell curl -X POST https://app.quickchat.ai/chat \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "scenario_id": "", "conv_id": "conv-uuid-1234", "text": "What is your return policy?" }' ``` * Python ```python import requests response = requests.post( url="https://app.quickchat.ai/chat", headers={"Authorization": "Bearer "}, json={ "scenario_id": "", "conv_id": "conv-uuid-1234", "text": "What is your return policy?", }, ) data = response.json() ``` ### Client Metadata [Section titled “Client Metadata”](#client-metadata) The Chat endpoint accepts an optional `client_metadata` parameter: custom attributes that are assigned to every new message and displayed as data columns in the conversation export in the Inbox. You can attach the same attributes through the widget. We recommend sending at most 5 keys at a time, for example `{"userId": 12, "website": "mywebsite.com"}`. This is a guideline, not an API-enforced limit. * Shell ```shell curl -X POST https://app.quickchat.ai/chat \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "scenario_id": "", "conv_id": "conv-uuid-1234", "text": "Hello!", "client_metadata": {"userId": 12, "website": "mywebsite.com"} }' ``` * Python ```python import requests response = requests.post( url="https://app.quickchat.ai/chat", headers={"Authorization": "Bearer "}, json={ "scenario_id": "", "conv_id": "conv-uuid-1234", "text": "Hello!", "client_metadata": {"userId": 12, "website": "mywebsite.com"}, }, ) data = response.json() ``` #### Knowledge Base Tag Filtering [Section titled “Knowledge Base Tag Filtering”](#knowledge-base-tag-filtering) You can add [tags](/api-reference/knowledge-base/tags/) to Knowledge Base articles and use them to restrict which articles the AI draws on, so it answers based only on a subset of the Knowledge Base. This filtering is currently supported only via the API. To filter by tag, add a `kb_topic` key to `client_metadata`. The `kb_topic` key must be present on every request in the conversation, including the request that starts it. Its value can change between requests, but the key itself has to be present throughout the conversation for the filter to apply. In the example below, any article tagged `your-topic`, or with no tag at all, is included in the candidate pool of knowledge for the response. ```python json={ "scenario_id": "", "conv_id": "conv-uuid-1234", "text": "Hello!", "client_metadata": {"kb_topic": "your-topic"}, } ``` ### Errors [Section titled “Errors”](#errors) The Chat endpoint returns a plain-text error message with an appropriate HTTP status code. | Status | Description | Action | | ------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Missing `scenario_id` or no credentials provided | Include `scenario_id` in the body and a valid `Authorization: Bearer ` header | | `400` | Invalid `conv_id` (`Conversation conv_id is not valid.`) | Omit `conv_id` to start a new conversation, or pass a `conv_id` returned by a previous response | | `401` | Invalid credentials (`Unauthorized.`) | Check that your Bearer token or API key is valid for this `scenario_id` | | `404` | Unknown `scenario_id` (`No implementation found for scenario_id `) | Verify the `scenario_id` and that your Bearer token is bound to it | | `500` | Internal server error | An issue on our side. Please [get in touch](https://quickchat.ai/contact) with support | | `503` | Service unavailable | Servers are temporarily overloaded or under maintenance. If the problem persists, please [get in touch](https://quickchat.ai/contact) with support | # Chatbot Settings > Retrieve and update your AI Agent's full configuration via the REST API. ## Chatbot Settings [Section titled “Chatbot Settings”](#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 [Section titled “Get Chatbot Settings”](#get-chatbot-settings) Scope: read\_all `GET https://app.quickchat.ai/v1/api/chatbot_settings` * Shell ```shell curl https://app.quickchat.ai/v1/api/chatbot_settings \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api/chatbot_settings", headers={"Authorization": "Bearer "}, ) data = response.json() ``` **Response** `200 OK` ```json { "personality": 0, "profession": "helpful_assistant", "creativity_level": 1, "greeting": "

Hello! How can I help you today?

", "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, max 5000 chars total across all items) | | `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** (max 200 chars) | | `header2` string | Secondary header text. Dashboard: **Identity > Profile > Chat header text** (max 200 chars) | | `language_chosen` string | Comma-separated language codes (e.g. `"en,es,de"`). Dashboard: **Identity > Profile > Languages** (max 10 chars total) | **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](#get-settings) endpoint. These fields are shared — updating via either endpoint modifies the same underlying data. ### Update Chatbot Settings [Section titled “Update Chatbot Settings”](#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 (max 200 chars) | | `header2` string | Secondary header text (max 200 chars) | | `language_chosen` string | Comma-separated language codes (max 10 chars total) | | `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 ```shell curl -X PATCH https://app.quickchat.ai/v1/api/chatbot_settings \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "greeting": "

Welcome! Ask me anything.

", "creativity_level": 2 }' ``` * Python ```python import requests response = requests.patch( url="https://app.quickchat.ai/v1/api/chatbot_settings", headers={"Authorization": "Bearer "}, json={ "greeting": "

Welcome! Ask me anything.

", "creativity_level": 2, }, ) data = response.json() ``` **Response** `200 OK` — Returns the updated chatbot settings (same schema as [Get Chatbot Settings](#get-chatbot-settings) response). *** # Conversations > Quickchat AI captures every conversation across all channels. These endpoints let you list and retrieve them. 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](/api-reference/conversations/conversation-metadata/)) ## List Conversations [Section titled “List Conversations”](#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 ```shell curl 'https://app.quickchat.ai/v1/api_core/conversations?limit=10&resolution_status=open' \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api_core/conversations", headers={"Authorization": "Bearer "}, params={"limit": 10, "resolution_status": "open"}, ) data = response.json() ``` **Response** `200 OK` ```json { "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 [Section titled “Get Conversation Details”](#get-conversation-details) Scope: read\_all `GET https://app.quickchat.ai/v1/api_core/conversations/{conversation_id}/` * Shell ```shell curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/ \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/", headers={"Authorization": "Bearer "}, ) data = response.json() ``` **Response** `200 OK` ```json { "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 [Section titled “Get Conversation Events”](#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 ```shell curl 'https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/?limit=20' \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/", headers={"Authorization": "Bearer "}, params={"limit": 20}, ) data = response.json() ``` **Response** `200 OK` ```json { "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 > Attach custom key-value data to conversations, bridging your own systems and your AI Agent. 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 `{{metadata_}}` placeholders into [AI Actions](/api-reference/ai-actions/). See [AI Action Variables](/ai-agent/variables/) for the full reference of available placeholders * **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 [Section titled “Get Metadata”](#get-metadata) Scope: read\_all `GET https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata` * Shell ```shell curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata", headers={"Authorization": "Bearer "}, ) data = response.json() ``` **Response** `200 OK` ```json { "metadata": { "ticket_id": "T-1234", "priority": "high" } } ``` ## Set Metadata [Section titled “Set Metadata”](#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 ```shell curl -X POST https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "metadata": { "ticket_id": "T-1234", "priority": "high" } }' ``` * Python ```python import requests response = requests.post( url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata", headers={"Authorization": "Bearer "}, json={ "metadata": {"ticket_id": "T-1234", "priority": "high"} }, ) data = response.json() ``` **Response** `200 OK` ```json { "metadata": { "ticket_id": "T-1234", "priority": "high" } } ``` *** # Conversation Rating > Collect visitor feedback on their AI Agent experience, with visitors prompted to rate the conversation at the end. 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 [Section titled “Get Conversation Rating Configuration”](#get-conversation-rating-configuration) Scope: read\_all `GET https://app.quickchat.ai/v1/api/conversation_ratings/configuration` * Shell ```shell curl https://app.quickchat.ai/v1/api/conversation_ratings/configuration \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api/conversation_ratings/configuration", headers={"Authorization": "Bearer "}, ) data = response.json() ``` **Response** `200 OK` ```json { "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 [Section titled “Update Conversation Rating Configuration”](#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 ```shell curl -X PATCH https://app.quickchat.ai/v1/api/conversation_ratings/configuration \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "conv_rating_active": true, "conv_rating_popup_active": true }' ``` * Python ```python import requests response = requests.patch( url="https://app.quickchat.ai/v1/api/conversation_ratings/configuration", headers={"Authorization": "Bearer "}, json={ "conv_rating_active": True, "conv_rating_popup_active": True, }, ) data = response.json() ``` **Response** `200 OK` — Returns the updated conversation rating configuration. *** # Handoff Configuration > Human Handoff transfers conversations to human operators when a personal touch is needed. Configure it via the API. 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 [Section titled “Get Handoff Configuration”](#get-handoff-configuration) Scope: read\_all `GET https://app.quickchat.ai/v1/api/human_handoff/configuration` * Shell ```shell curl https://app.quickchat.ai/v1/api/human_handoff/configuration \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api/human_handoff/configuration", headers={"Authorization": "Bearer "}, ) 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](/api-reference/conversations/handoff-configuration/#update-handoff-configuration). | 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 [Section titled “Update Handoff Configuration”](#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 ```shell # First, fetch the current configuration CONFIG=$(curl -s https://app.quickchat.ai/v1/api/human_handoff/configuration \ -H 'Authorization: Bearer ') # 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 ' \ -H 'Content-Type: application/json' \ -d @- ``` * Python ```python import requests headers = {"Authorization": "Bearer "} # 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. *** # Knowledge Base > The Knowledge Base is the core of your AI Agent's expertise. These endpoints manage its settings and trigger retraining. 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](/api-reference/knowledge-base/articles/) you create, import from websites, or upload as files. After making changes to articles, you need to [retrain](/api-reference/knowledge-base/#retrain-knowledge-base) the Knowledge Base for updates to take effect in conversations. ## Get Settings [Section titled “Get Settings”](#get-settings) Retrieve your Knowledge Base configuration. Scope: read\_all `GET https://app.quickchat.ai/v1/api/knowledge_base/` * Shell ```shell curl https://app.quickchat.ai/v1/api/knowledge_base/ \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api/knowledge_base/", headers={"Authorization": "Bearer "}, ) data = response.json() ``` **Response** `200 OK` ```json { "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](/api-reference/chatbot-settings/). Updating via either endpoint modifies the same underlying data. ## Update Settings [Section titled “Update Settings”](#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 ```shell curl -X PATCH https://app.quickchat.ai/v1/api/knowledge_base/ \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "one_word_description": "Sales Bot" }' ``` * Python ```python import requests response = requests.patch( url="https://app.quickchat.ai/v1/api/knowledge_base/", headers={"Authorization": "Bearer "}, json={"one_word_description": "Sales Bot"}, ) data = response.json() ``` **Response** `200 OK` — Returns the updated Knowledge Base settings (same schema as [Get Settings](/api-reference/knowledge-base/#get-settings)). ## Retrain Knowledge Base [Section titled “Retrain Knowledge Base”](#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 ```shell curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/retrain/ \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.post( url="https://app.quickchat.ai/v1/api/knowledge_base/retrain/", headers={"Authorization": "Bearer "}, ) ``` **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](/api-reference/knowledge-base/#get-settings) — it changes from `"to_be_retrained"` to `"in_progress"` to `"up_to_date"`. *** # Article Language URLs > Associate language-specific source links with articles so the chat widget can show the right URL for each language. 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 [Section titled “Get Language URL”](#get-language-url) Scope: read\_all `GET https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}/lang_urls/{language}` * Shell ```shell curl https://app.quickchat.ai/v1/api/knowledge_base/articles/1234/lang_urls/en \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234/lang_urls/en", headers={"Authorization": "Bearer "}, ) data = response.json() ``` **Response** `200 OK` ```json { "url": "https://example.com/en/return-policy" } ``` ## Create Language URL [Section titled “Create Language URL”](#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 ```shell curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/articles/1234/lang_urls/en \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"url": "https://example.com/en/return-policy"}' ``` * Python ```python import requests response = requests.post( url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234/lang_urls/en", headers={"Authorization": "Bearer "}, json={"url": "https://example.com/en/return-policy"}, ) data = response.json() ``` **Response** `200 OK` ```json { "url": "https://example.com/en/return-policy" } ``` ## Update Language URL [Section titled “Update Language URL”](#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 [Section titled “Delete Language URL”](#delete-language-url) Scope: write\_all `DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}/lang_urls/{language}` * Shell ```shell curl -X DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/1234/lang_urls/en \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.delete( url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234/lang_urls/en", headers={"Authorization": "Bearer "}, ) ``` **Response** `200 OK` *** # Articles > Articles are the building blocks of your Knowledge Base. Create, list, update, and delete the content your AI Agent uses to answer questions. 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](/api-reference/knowledge-base/import-external-content/), upload files via [File Upload](/api-reference/knowledge-base/file-upload/), or sync from [Intercom](/api-reference/knowledge-base/intercom-knowledge-base/). After creating or updating articles, remember to [retrain the Knowledge Base](/api-reference/knowledge-base/#retrain-knowledge-base) for changes to take effect. ## Create Article [Section titled “Create Article”](#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 ```shell curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/articles/ \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "content": "Our return policy allows returns within 30 days.", "title": "Return Policy" }' ``` - Python ```python import requests response = requests.post( url="https://app.quickchat.ai/v1/api/knowledge_base/articles/", headers={"Authorization": "Bearer "}, json={ "content": "Our return policy allows returns within 30 days.", "title": "Return Policy", }, ) data = response.json() ``` **Response** `201 Created` ```json { "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 [Section titled “List Articles”](#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 ```shell curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/?limit=10&offset=0' \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api/knowledge_base/articles/", headers={"Authorization": "Bearer "}, params={"limit": 10, "offset": 0}, ) data = response.json() ``` **Response** `200 OK` ```json { "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](/api-reference/knowledge-base/articles/#get-article) to retrieve the full content of a specific article. ## Get Article [Section titled “Get Article”](#get-article) Scope: read\_all `GET https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}` * Shell ```shell curl https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234", headers={"Authorization": "Bearer "}, ) data = response.json() ``` **Response** `200 OK` — Returns the full article object (same schema as [Create Article](/api-reference/knowledge-base/articles/#create-article) response), including the `content` field. ## Update Article [Section titled “Update Article”](#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](/api-reference/knowledge-base/#retrain-knowledge-base) when you’re ready for changes to take effect. * Shell ```shell curl -X PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "title": "Updated Return Policy", "content": "Returns accepted within 60 days.", "save_mode": "publish" }' ``` * Python ```python import requests response = requests.patch( url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234", headers={"Authorization": "Bearer "}, 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 [Section titled “Delete Articles”](#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 ```shell curl -X DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/ \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '[1234, 5678]' ``` * Python ```python import requests response = requests.delete( url="https://app.quickchat.ai/v1/api/knowledge_base/articles/", headers={"Authorization": "Bearer "}, json=[1234, 5678], ) ``` **Response** `200 OK` ## Search Articles [Section titled “Search Articles”](#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 ```shell curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/search?query=return%20policy' \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api/knowledge_base/articles/search", headers={"Authorization": "Bearer "}, params={"query": "return policy"}, ) data = response.json() ``` **Response** `200 OK` ```json { "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 [Section titled “List Paragraphs”](#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 ```shell curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs?limit=10' \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs", headers={"Authorization": "Bearer "}, params={"limit": 10}, ) data = response.json() ``` **Response** `200 OK` ```json { "items": [ { "id": 1, "content": "Our return policy allows returns within 30 days." } ], "offset": 0, "count": 1 } ``` *** # File Upload > Upload files such as PDFs to be processed and added to the Knowledge Base as articles. Upload files to be processed and added to the Knowledge Base as articles. ## Upload PDF [Section titled “Upload PDF”](#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 ```shell curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/file_upload_api/pdf \ -H 'Authorization: Bearer ' \ -F 'pdf_file=@document.pdf' ``` * Python ```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 "}, files={"pdf_file": f}, ) data = response.json() ``` **Response** `200 OK` ```json { "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 [Section titled “Upload File”](#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 ```shell curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/file_upload_api/ \ -H 'Authorization: Bearer ' \ -F 'file=@document.docx' ``` * Python ```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 "}, files={"file": f}, ) data = response.json() ``` **Response** `200 OK` — Same schema as [Upload PDF](/api-reference/knowledge-base/file-upload/#upload-pdf). *** # Import External Content > Import content from external sources into the Knowledge Base. These endpoints process content asynchronously. 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](/api-reference/knowledge-base/#get-settings) — it changes to `"to_be_retrained"` then `"in_progress"` then `"up_to_date"` 2. Use [List Articles](/api-reference/knowledge-base/articles/#list-articles) to verify imported articles appear ## Scrape Website [Section titled “Scrape Website”](#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 ```shell curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/import_external/website \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "url": "https://example.com/docs", "mode": "individual" }' ``` * Python ```python import requests response = requests.post( url="https://app.quickchat.ai/v1/api/knowledge_base/import_external/website", headers={"Authorization": "Bearer "}, json={"url": "https://example.com/docs", "mode": "individual"}, ) data = response.json() ``` **Response** `202 Accepted` ```json { "status": "success", "url": "https://example.com/docs", "article": {} } ``` ## Import YouTube Transcript [Section titled “Import YouTube Transcript”](#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 ```shell curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/import_external/youtube \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "toast_process_uuid": "550e8400-e29b-41d4-a716-446655440000" }' ``` * Python ```python import uuid import requests response = requests.post( url="https://app.quickchat.ai/v1/api/knowledge_base/import_external/youtube", headers={"Authorization": "Bearer "}, 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 [Section titled “Import Sitemap”](#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 ```shell curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/import_external/site-map \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "site_map": "https://example.com/sitemap.xml" }' ``` * Python ```python import requests response = requests.post( url="https://app.quickchat.ai/v1/api/knowledge_base/import_external/site-map", headers={"Authorization": "Bearer "}, json={"site_map": "https://example.com/sitemap.xml"}, ) data = response.json() ``` **Response** `202 Accepted` ```json { "status": "success", "links": ["https://example.com/page1", "https://example.com/page2"] } ``` ## Scrape List of Links [Section titled “Scrape List of Links”](#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 ```shell curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/import_external/scrape-list \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "links": ["https://example.com/page1", "https://example.com/page2"], "tags": ["imported"] }' ``` * Python ```python import requests response = requests.post( url="https://app.quickchat.ai/v1/api/knowledge_base/import_external/scrape-list", headers={"Authorization": "Bearer "}, json={ "links": ["https://example.com/page1", "https://example.com/page2"], "tags": ["imported"], }, ) data = response.json() ``` **Response** `202 Accepted` ```json { "status": "success", "links": ["https://example.com/page1", "https://example.com/page2"] } ``` ## Delete Links [Section titled “Delete Links”](#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 ```shell curl -X DELETE https://app.quickchat.ai/v1/api/knowledge_base/import_external \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "links": ["https://example.com/page1"] }' ``` * Python ```python import requests response = requests.delete( url="https://app.quickchat.ai/v1/api/knowledge_base/import_external", headers={"Authorization": "Bearer "}, json={ "links": ["https://example.com/page1"], }, ) ``` **Response** `200 OK` *** # Intercom Knowledge Base > Migrate your Intercom knowledge to Quickchat AI, or run both side by side during a switch from Intercom's Fin AI. **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](https://app.quickchat.ai/) or the [Intercom App Store integration](https://www.intercom.com/app-store/?app_package_code=quickchat) 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](/channels/intercom/). To learn more about switching from Fin AI, visit [Quickchat as a Fin AI alternative](https://quickchat.ai/intercom-fin-ai-alternative). ## Refresh Intercom Articles [Section titled “Refresh Intercom Articles”](#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 [Section titled “Import Intercom Articles”](#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 [Section titled “Delete Intercom Articles”](#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` *** # Tags > Tags help you organize and categorize Knowledge Base articles. Create, list, and assign them via the API. 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](/api-reference/knowledge-base/articles/#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 [Section titled “List Tags”](#list-tags) Retrieve all tags used across Knowledge Base articles. Scope: read\_all `GET https://app.quickchat.ai/v1/api/knowledge_base/tags/` * Shell ```shell curl https://app.quickchat.ai/v1/api/knowledge_base/tags/ \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api/knowledge_base/tags/", headers={"Authorization": "Bearer "}, ) tags = response.json() ``` **Response** `200 OK` ```json ["policies", "faq", "product-info"] ``` *** # Widget Configuration > Read and update the website widget configuration via the API. ## Widget Configuration [Section titled “Widget Configuration”](#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](/channels/website/). ### Get Widget Configuration [Section titled “Get Widget Configuration”](#get-widget-configuration) Scope: read\_all `GET https://app.quickchat.ai/v1/api/widget/configuration` * Shell ```shell curl https://app.quickchat.ai/v1/api/widget/configuration \ -H 'Authorization: Bearer ' ``` * Python ```python import requests response = requests.get( url="https://app.quickchat.ai/v1/api/widget/configuration", headers={"Authorization": "Bearer "}, ) data = response.json() ``` **Response** `200 OK` ```json { "welcome_message": "

Hello! How can I help?

", "welcome_message2": "", "header": "Support", "subtitle": "We typically reply within minutes", "conversation_starters": ["What are your opening hours?", "How do I track my order?", "Talk to a human"], "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", "launcher_label": "Ask AI", "launcher_draggable": false, "avatar_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png", "bubble_icon_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png", "default_avatar_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png", "theme": "light", "widget_theme_custom": { "colors": { "background": "#ffffff", "header": "#ffffff", "header_text": "#030712", "accent": "#27272a", "accent_hover": "#374151", "accent_text": "#ffffff", "bubble": "#27272a", "bubble_text": "#ffffff", "ai_bubble_text": "#030712", "tertiary": "#afafb2", "link": null, "input_background": "#ffffff", "input_text": "#030712", "input_placeholder": "#9ca3af", "border": "#e5e7eb", "sidebar": { "background": "#f5f5f5", "text": null, "accent": "#e5e5e5", "accent_text": null } }, "radius": { "bubble": "full", "input": "full", "button": "full" }, "font": { "size": "base" } } } ``` #### Content & Messaging [Section titled “Content & Messaging”](#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…”) | | `conversation_starters` array of strings or null | Suggested opening prompts shown as clickable buttons when the widget opens. Up to 3 entries, each up to \~100 characters | | `background_disclaimer_text` string or null | Disclaimer text shown at the bottom of the chat window | #### Appearance [Section titled “Appearance”](#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 | Launcher size preset: `"small"`, `"medium"`, or `"large"` (shown in the dashboard as Small, Input Only, and Classic) | | `location` string | Widget position on the page: `"top-left"`, `"top-right"`, `"bottom-left"`, or `"bottom-right"` | | `launcher_label` string or null | Text on the **small** launcher button (`size: "small"`), max 25 characters. `null` uses the default (`"Ask AI"`); `""` shows an icon-only launcher | | `launcher_draggable` boolean | Allow visitors to drag the launcher to a different position on the page | | `window_height` integer | Widget height in pixels (400-1200) | | `window_width` integer | Widget width in pixels (300-700) | | `avatar_image` string or null | URL of the **AI Agent Avatar**, shown both in the chat header and as the floating bubble icon. Upload via PATCH as base64. `null` means the avatar was deleted and the widget shows no avatar | | `bubble_icon_image` string or null | **Deprecated.** Always mirrors `avatar_image` — the bubble icon and the chat avatar are now one image (see [AI Agent Avatar unification](#ai-agent-avatar-unification)) | | `default_avatar_image` string | Read-only. URL of the default AI Agent Avatar that `use_default_avatar` restores | | `theme` string | Color theme mode: `"light"` or `"dark"` (fixed presets) or `"custom"` (applies the `widget_theme_custom` palette) | | `widget_theme_custom` object | Custom palette applied when `theme` is `"custom"`. Contains `colors` (header, accent, message bubble, AI text, `link`, input, border, and more, as hex or `rgb()`/`rgba()`), `radius` (`"sm"`/`"base"`/`"lg"`/`"full"` for bubbles, input, and buttons), and `font.size` (`"sm"`/`"base"`/`"lg"`). On PATCH, send the whole object — missing keys reset to defaults. `colors.link` defaults to `null`, meaning links inherit the surrounding text color. `colors.sidebar` (`background`, `text`, `accent`, `accent_text`) themes the standalone Chat Page sidebar only (ignored by the bubble and embed views); its `text` and `accent_text` default to `null`, meaning a readable color is auto-derived from the matching background | #### Behavior [Section titled “Behavior”](#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](#get-conversation-events) | | `white_label` boolean | Remove “Powered by Quickchat” branding from the widget | #### Pre-chat Form [Section titled “Pre-chat Form”](#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 [Section titled “Update Widget Configuration”](#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 `avatar_image`, send base64-encoded image data (max 5 MB). The response returns the stored image URL. Sending `avatar_image: null` deletes the avatar (the widget then shows no avatar), and sending `use_default_avatar: true` restores the default AI Agent Avatar. #### AI Agent Avatar unification [Section titled “AI Agent Avatar unification”](#ai-agent-avatar-unification) The chat avatar (header logo) and the floating bubble icon (launcher) were merged into a single image, the **AI Agent Avatar**, stored in `avatar_image`. The bubble icon always mirrors it — there is no longer an independent launcher image. If you integrate with this endpoint directly, note the following behavior changes: * Uploading via `bubble_icon_image` is **deprecated**: it now sets the unified AI Agent Avatar, which also replaces the image shown in the chat header. Use `avatar_image` instead. * `bubble_icon_image: null` is a **no-op**. It used to clear the launcher icon; since the launcher mirrors the avatar, delete via `avatar_image: null` instead. * Agents that never customized their avatar show the default AI Agent Avatar (see `default_avatar_image` in the response) in both the header and the launcher. - Shell ```shell curl -X PATCH https://app.quickchat.ai/v1/api/widget/configuration \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "primary_color": "rgb(255, 87, 34)", "header": "Sales Assistant", "window_auto_open": true }' ``` - Python ```python import requests response = requests.patch( url="https://app.quickchat.ai/v1/api/widget/configuration", headers={"Authorization": "Bearer "}, 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](#get-widget-configuration) response). *** # Discord > Step-by-step guide to integrating your Quickchat AI Agent with Discord. Create a bot, configure permissions, and go live on your server. In this guide, we’ll go through how to integrate your AI Agent into your Discord server. Here’s an overview of what we’ll cover: 1. Create a Discord server 2. Create a Discord application 3. Configure Your Discord Application 4. Add the Bot to Your Discord Server 5. Integrate your Discord bot with Quickchat AI ## Watch the Video [Section titled “Watch the Video”](#watch-the-video) [Play](https://youtube.com/watch?v=tNXuqBUZZ-4) ## Creating and configuring a Discord Server [Section titled “Creating and configuring a Discord Server”](#creating-and-configuring-a-discord-server) ### Create a Discord Server [Section titled “Create a Discord Server”](#create-a-discord-server) To initiate the integration process, you’ll need a Discord Server. If you don’t have a Discord account, visit [discord.com](https://discord.com) and create one. Once logged in, follow [this guide to create your Discord server](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server-). ### Create a Discord Application [Section titled “Create a Discord Application”](#create-a-discord-application) Go to [discord.com/developers/applications](https://discord.com/developers/applications) while logged in to your Discord account and create a new application. ### Configure Your Discord Application [Section titled “Configure Your Discord Application”](#configure-your-discord-application) Before adding your bot to the server, enable the **Message Content Intent** for your application. This allows your bot to read messages sent by users on your server. ![Quickchat AI Interface](/_astro/message-intent.NVnNJZhz_Z1tawYf.webp) ### Add the Bot to Your Discord Server [Section titled “Add the Bot to Your Discord Server”](#add-the-bot-to-your-discord-server) Now you need to add your bot to your server. The way to do it is to construct a Discord URL and paste it into your browser: ```plaintext https://discord.com/api/oauth2/authorize?client_id=&permissions=309237712896&scope=bot ``` **Where does the permissions number come from?** The permissions number (`309237712896`) comes from requesting the following permissions: * `Send Messages` * `Create Public Threads` * `Send Messages in Threads` * `Read Message History` Those are the minimal set of permissions required for your bot to operate correctly. You can see it for yourself by going to [discord.com/developers/applications](https://discord.com/developers/applications), selecting your application, clicking on **Bot** on the left and scrolling down: ![Your discord bot permissions](/_astro/permissions-integer.D-K4GVRL_Z1aAD5W.webp) **Where to find YOUR CLIENT ID?** The easiest way will be to look at the address bar in your browser and copy the long number which is part of the address: ```plaintext https://discord.com/developers/applications//bot ``` ![Your client ID](/_astro/client-id.Z-Mljq23_ZSFM0V.webp) In this case the client id is **1234567890123456789** which means that the full URL you need to go to to add the server will be: ```plaintext https://discord.com/api/oauth2/authorize?client_id=1234567890123456789&permissions=309237712896&scope=bot ``` ## Integrate Your Discord Bot with Quickchat AI [Section titled “Integrate Your Discord Bot with Quickchat AI”](#integrate-your-discord-bot-with-quickchat-ai) To connect your bot with **Quickchat AI**, retrieve your **Discord Bot Token** from the [Developer Portal](https://discord.com/developers/applications). 1. Go to **Bot Settings** → **Reset Token** → **Copy Token** ![Reset token](/_astro/reset-token.OEKpvVuf_MJGbS.webp) 2. In the **Quickchat AI Dashboard**, head to **External Applications**, open the **Discord** integration, turn on **Enable Discord** and paste your token. ![Paste token](/_astro/paste-token.heB4K_lh_Z6NVGh.webp) ## 🎉 Your AI Bot is Live! [Section titled “🎉 Your AI Bot is Live!”](#-your-ai-bot-is-live) Head back to **Discord** - your bot should be **online** and ready to chat! Just **@mention** it to start a conversation. 🤖💬 ![Bot active](/_astro/bot-active.CoUvIYHf_Z1VXvkS.webp) By default, when **@mentioned** the bot replies in the same channel. You can change this with the **Reply mode** setting in the integration: **Reply in channel** (the default) or **Reply in threads**. With **Reply in threads**, the bot answers inside a thread and users can continue the conversation there without mentioning it again. ![Conversation in thread](/_astro/conversation-in-thread.DrEOnyKG_Z1K9PUH.webp) ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### ”Integration requires code grant” when adding the bot [Section titled “”Integration requires code grant” when adding the bot”](#integration-requires-code-grant-when-adding-the-bot) Your application has **Require OAuth2 Code Grant** enabled, which blocks the simple bot invite flow. In the [Developer Portal](https://discord.com/developers/applications), open your application, go to **Bot**, turn **Require OAuth2 Code Grant** off, save, and open the invite URL again. ### The authorization page shows a cake or “baked” message [Section titled “The authorization page shows a cake or “baked” message”](#the-authorization-page-shows-a-cake-or-baked-message) That quirky screen is Discord’s success page: the bot was added. To confirm, open your server’s **Server Settings → Integrations → Bots and Apps** and look for your bot in the list. ### The bot is in the server but appears offline [Section titled “The bot is in the server but appears offline”](#the-bot-is-in-the-server-but-appears-offline) 1. In the Quickchat AI dashboard, open **External Apps → Discord** and check the connection status. An invalid token or a missing intent is reported there with instructions. 2. Bot tokens are shown only once. If in doubt, click **Reset Token** in the Developer Portal, copy the new token, and paste it into Quickchat again. 3. Make sure **Message Content Intent** is enabled under **Bot → Privileged Gateway Intents**. 4. Give it up to a minute after saving: the bot restarts whenever its settings change. ### The bot is online but does not reply [Section titled “The bot is online but does not reply”](#the-bot-is-online-but-does-not-reply) @mention the bot in a channel it can access. Verify its role and channel permissions include **Send Messages**, **Create Public Threads**, **Send Messages in Threads**, and **Read Message History**. Whether it replies in the channel or in threads is configured in Quickchat under **External Apps → Discord**. Tip The Discord integration page in the Quickchat AI dashboard shows the connection status, the **Bot Token** field, a **Reply mode** selector (**Reply in channel** or **Reply in threads**), and a link to join our Discord community for help. *** Join our Discord server to learn more about how to make the most of Quickchat AI 👉 [discord.gg/KqkHwvPRNH](https://discord.gg/KqkHwvPRNH) # Drupal > Integrate Quickchat AI with Drupal. Obtain API tokens, sync Knowledge Base items, and add the AI Agent chatbot to your Drupal site. In this guide, we’ll go through how to integrate your AI Agent into your Drupal. Here’s an overview of what we’ll cover: 1. Obtaining a token for Drupal integration 2. Syncing Knowledge Base items 3. Adding the Quickchat AI Assitant to Drupal ## Obtain token for Drupal integration [Section titled “Obtain token for Drupal integration”](#obtain-token-for-drupal-integration) 1. Activate Drupal integration within the **External Apps** tab of the Quickchat AI app. 2. Copy your scenario\_id and token. ![drupal\_integration](/_astro/drupal_integration.CIp-PBzU_2rhQ8A.webp) ## Enable module [Section titled “Enable module”](#enable-module) Enable the Quickchat module to provide the API client used by the sub-modules. No configuration is needed at this point. ![drupal\_image1](/_astro/drupal_image1.ms1LTFBj_ZBL2Af.webp) ## Sync knowledge base items [Section titled “Sync knowledge base items”](#sync-knowledge-base-items) ### Configuration [Section titled “Configuration”](#configuration) This module will add a new content type `quickchat_kb` (admin/structure/types/manage/quickchat\_kb) and a view `quickchat_kb` (/admin/structure/views/view/quickchat\_kb) so you can use them as a source to train your chatbot models. You can configure the module from (/admin/config/services/quickchat-api/sync), defining: * A model name * A scenario\_id * An API token * A view name: the view to use as a source of knowledge base items (you can use the one provided by the module or a custom one). * A view display: the display from the view name selected above. ![drupal\_image2](/_astro/drupal_image2.BTJU9UC-_BIK4t.webp) *From that screen, you can add multiple models with a different pair of token and scenario\_id and view source.* ### View [Section titled “View”](#view) In case you want to use a different view as the source of knowledge base items, be aware that if you want to split the results into different knowledge base items, you need to use the \n separator. Otherwise, the view results will be considered as only one knowledge base item. ![drupal\_image3](/_astro/drupal_image3.Dh_TU76-_Z1UAlYm.webp) ### Operation [Section titled “Operation”](#operation) Once you have configured the sync model mappings, the next step is to sync the knowledge base items for your chatbot models. You can do this by navigating to `/admin/content/kb`. In this section, you will see a list of the configured models: ![drupal\_image4](/_astro/drupal_image4.gDDQdejg_1PANc8.webp) If you click in the title of the model to sync you will see a page similar to this one: ![drupal\_image5](/_astro/drupal_image5.D5HOvdzL_90TWM.webp) In the preview section you can see the knowledge base items that you are about to sync. The values displayed there are the results of the view and view display that you selected under the model configuration section. The available actions are Update and Rebuild: ![drupal\_image7](/_astro/drupal_image7.A3cX8tV5_1oMWdm.webp) The **Update** action will push the knowledge base items to the selected model (scenario\_id), and the **Rebuild** action will retrain the chatbot with the updated knowledge base items. ![drupal\_image6](/_astro/drupal_image6.wD5fQSgm_ZlAXvI.webp) ## Add a Quickchat AI Agent [Section titled “Add a Quickchat AI Agent”](#add-a-quickchat-ai-agent) The `quickchat_chatbot` sub-module adds a new block type `chatbot_block` where you can set the `scenario_id`. ![drupal\_image8](/_astro/drupal_image8.BLM7pQTs_Z1H96j9.webp) Also, you can add multiple chatbot blocks with a different scenario\_id for different type of pages, eg: ![drupal\_image9](/_astro/drupal_image9.BEM3V5Qw_hzv4H.webp) Once you enabled the block, visit the pages where the block should be available (visibility settings) so you can interact with the chatbot. That’s it! 🎉 Your Drupal integration is now ready. If you have any questions or require a more complex solution with more functionality, please do not hesitate to get in touch. # Facebook Messenger > Connect your Quickchat AI Agent to Facebook Messenger. Link a Facebook Page and your AI Agent replies to Messenger conversations automatically. This guide shows how to connect your **Quickchat AI Agent** to **Facebook Messenger**. Once a Facebook Page is linked, your AI Agent replies to people who message that Page on Messenger, and every conversation appears in your [Quickchat AI Inbox](https://app.quickchat.ai). If you get stuck, jump to [Troubleshooting & FAQs](#troubleshooting--faqs) or [contact us](https://quickchat.ai/contact). ## Step 0 - Prerequisites [Section titled “Step 0 - Prerequisites”](#step-0---prerequisites) * A **Facebook Page** for your business. Messenger integrations connect to a Page, not to a personal profile. * **Admin access** to that Page. * A **Facebook account with Business permissions** for the Page, so you can authorize Quickchat AI. Caution A Facebook Page can be connected to **one AI Agent** at a time. If you manage several Agents, use a separate Page for each. ## Step 1 - Connect your Facebook Page [Section titled “Step 1 - Connect your Facebook Page”](#step-1---connect-your-facebook-page) 1. Open the [Quickchat AI App](https://app.quickchat.ai) and go to **External Apps**. 2. Click **Messenger**, then click **Connect**. 3. A Facebook pop-up opens. Log in if prompted and **continue as yourself**. 4. **Select the Page** you want your AI Agent to reply for, and review the requested permissions. 5. Click **Continue / Confirm** to grant Quickchat AI access. 6. The pop-up closes and the panel shows your connected **Page name** and **Page ID**. That’s it. **Your AI Agent is now live on Messenger!** 🎉 ## Step 2 - Enable the bot [Section titled “Step 2 - Enable the bot”](#step-2---enable-the-bot) Use the **Enable** toggle to switch the integration on or off without disconnecting the Page. When it’s on, your AI Agent replies to incoming Messenger messages; when it’s off, the Page stays connected but the Agent stops replying. ## Try it out [Section titled “Try it out”](#try-it-out) Open your Page in Messenger (for example via `m.me/`) and send a message. Your AI Agent replies, and the conversation appears in your [Quickchat AI Inbox](https://app.quickchat.ai), where you can read the full transcript, see the visitor’s name, and take over from the AI at any time. ## Troubleshooting & FAQs [Section titled “Troubleshooting & FAQs”](#troubleshooting--faqs) **The pop-up doesn’t open.** * Disable pop-up and tracker blockers in your browser, refresh the page and try again. If that doesn’t help, try a different browser. **My AI Agent doesn’t reply.** * Make sure the **Enable** toggle is on and the panel shows the Page as connected. * Confirm you connected the intended **Page** and that the correct **AI Agent** is selected. * One Page connects to one AI Agent. Don’t connect the same Page to multiple Agents. **I connected the wrong Page.** * Click **Switch Page** in the integration panel and repeat the connection flow with the correct Page. **How do I change the welcome message?** * The greeting is your AI Agent’s message, configured in the [Quickchat AI App](https://app.quickchat.ai). Update it there and it applies to every channel, including Messenger. ## Need Help? [Section titled “Need Help?”](#need-help) Still stuck? Reach out on [Discord](https://discord.gg/KqkHwvPRNH) or [contact us](https://quickchat.ai/contact) and we’ll help you get your Page connected. # Hubspot > Integrate Quickchat AI with HubSpot Conversations to automate customer support, streamline queries, and enhance your CRM workflows. Integrating Quickchat AI Agent with HubSpot Conversations is a powerful customer service tool that enables businesses to interact with their customers by providing instant support, and build customer relationships, providing automated responses to customer queries and streamlining your customer support processes. ## Watch the Video [Section titled “Watch the Video”](#watch-the-video) [Play](https://youtube.com/watch?v=Suc4_rxHMN0) ## Quickchat prerequisites: [Section titled “Quickchat prerequisites:”](#quickchat-prerequisites) * Create a Quickchat AI [account](https://app.quickchat.ai/) ## Step-by-step tutorial: [Section titled “Step-by-step tutorial:”](#step-by-step-tutorial) 1. Create a new user — this seat be assigned to the AI Agent 2. Select the **Super Admin** permission set 3. Ensure the *Service Enterprise* seat is enabled — hover over your newly created user and click *Edit permissions*. 4. Check if the user status is set to available — hover over your newly created user and click *Actions*, then *Edit user*. 5. Once your Quickchat AI is ready, navigate to the Quickchat AI [dashboard](https://app.quickchat.ai/) and go to the **External Apps** tab. 6. On the list of available platforms, click **HubSpot**. 7. Provide the exact same email address you used to create the new HubSpot user. It will be responding to messages **on behalf of** that account. 8. Click on *Authenticate with HubSpot* and follow the on-screen prompts by choosing the appropriate HubSpot workspace. Please keep in mind that you **need** to have HubSpot [*Super Admin*](https://knowledge.hubspot.com/settings/hubspot-user-permissions-guide#super-admin) permissions in order to authenticate your account. 9. Go back to HubSpot. Create a new [*Chatflow*](https://knowledge.hubspot.com/chatflows/create-a-live-chat) on your HubSpot account. Go to the *Service* tab from the left sidebar and then click *Chatflows*. 10. Create a new *Chatflow* or edit an existing one. 11. Choose *Website* and then *Live chat*. 12. Select an *Inbox* and *Language*. (remember to set the same language in Quickchat AI settings) 13. Disable *Knowledge base search*. AI Agent’s Knowledge Base is handled in the Quickchat AI Platform. 14. Select *Automatically assign conversations* , select *Specific users* and select your Quickchat AI user (associated with the *email address* you provided earlier). 15. (Optional) Customize your *Welcome message*. 16. (Optional) Disable *Email capture*. 17. Click *Preview* and send a message. If the AI responds, everything’s set! 18. Save your *Chatflow*. Caution Ensure your Quickchat AI user is assigned as the “Owner” of a conversation; otherwise, the Quickchat AI Agent won’t respond. Additionally, check other HubSpot features you use, like “Automations,” as they may affect the assignment automatically. The below video guide summarises these steps. ![Hubsport integration](/tutorial.gif) **Your integration is now complete!** If you prefer not to use the HubSpot widget, use Quickchat! Go to *Website* > *Install*, and follow the instructions on the screen to add it to your website. Tip As a final verification of your integration, you can test the widget in the Preview section of the HubSpot Chatflow editor. You should get a reply from your AI Agent and the conversation should appear in the Inbox in the [Quickchat AI App](https://app.quickchat.ai). You can now share the HubSpot widget on your website and have Quickchat AI reply automatically! # Intercom > Integrate Quickchat AI with Intercom. Set up a dedicated user, authenticate, and assign conversations to your AI Agent. In this guide, we’ll go through how to integrate your AI Agent into Intercom. Here’s an overview of what we’ll cover: 1. Preparing the Intercom Account for integration 2. Integrating Quickchat AI with Intercom 3. Adding the Quickchat AI Agent to Intercom ## Prepare your Intercom Account [Section titled “Prepare your Intercom Account”](#prepare-your-intercom-account) ### Create an Intercom User dedicated to your AI [Section titled “Create an Intercom User dedicated to your AI”](#create-an-intercom-user-dedicated-to-your-ai) To initiate the integration process, you’ll need to designate an Intercom user who will be serving as the *persona* for **AI Agent**. Our AI will be replying as this user to all conversations that are assigned to it. To ensure a seamless experience, we recommend creating a separate user named ‘Quickchat AI’ to handle automatic replies. This approach provides flexibility of choosing when the AI Agent is active and lets your team take over the conversation by assigning it to a different team member. Here’s how to do that: 1. **Create the Quickchat AI User:** Log in to your Intercom account and create a new user with the name ‘Quickchat AI.’ 2. **Define Permissions/Access:** Configure specific permissions and access rights for the ‘Quickchat AI’ user to ensure it functions correctly. Once you’ve completed this setup, you’re ready to move on to the next step. Caution Ensure that you are logged in as dedicated User while proceeding with the next steps of integration. ## Integrate Quickchat with Intercom [Section titled “Integrate Quickchat with Intercom”](#integrate-quickchat-with-intercom) ### Navigation [Section titled “Navigation”](#navigation) Go to the **External Apps** tab, locate and click on the “Intercom” tile: ![Dashboard\_Intercom](/_astro/1db58d35-6020-4c3f-bb29-1860ccecb4b3.DtO9dk03_Z16w92w.webp) ### Authentication [Section titled “Authentication”](#authentication) When Intercom is not yet connected, the panel shows a single **Authenticate with Intercom** button. Click it to start the OAuth flow. A popup window opens where you authorize the AI Agent to access your Intercom workspace. When you approve, the popup closes automatically and the connection is detected, so there is no separate “enable” step to do first. ![Alt text](/_astro/4d4e6e2b-e843-4aed-877d-fd1b8af26bfa.CAeatqKR_Ab44V.webp) ### Confirmation [Section titled “Confirmation”](#confirmation) Once connected, the panel shows a connection card with **Connected as {name}**, your **App ID**, and your **Admin ID**, along with **Re-authenticate**, **Test connection**, and **Remove** buttons. Click **Test connection** to verify the integration is working. If the test succeeds, you did it! Congratulations! Your integration is now live, and you can proceed to the next step to assign conversations in Intercom to your AI Agent. ### Integration settings [Section titled “Integration settings”](#integration-settings) After connecting, the panel exposes a few settings. Use the **Enable Intercom** toggle to switch the integration on or off without removing it. * **Reply to all conversations:** When enabled, the AI Agent replies to every conversation in your Intercom inbox, and the Workflow Automation assignment step below is not required. By default this is off (assigned-only mode), so the AI Agent only replies to conversations assigned to its admin user. In that default mode, complete both the Workload Management and Workflow Automation steps below. * **Offer human handoff to Intercom admins:** Off by default. When enabled, the AI Agent can transfer a conversation to a human admin in Intercom when escalation is needed. * **Automatically close inactive conversations:** Choose how long to wait before closing a conversation with no activity. Options are Never, 5 minutes, 10 minutes, or 30 minutes. ## Assign conversations in Intercom to Quickchat AI Agent [Section titled “Assign conversations in Intercom to Quickchat AI Agent”](#assign-conversations-in-intercom-to-quickchat-ai-agent) In the default assigned-only mode, there are two steps to assigning Intercom conversations to your Quickchat AI Agent for handling. (If you enabled **Reply to all conversations** above, you can skip the Workflow Automation step.) ### Workload Management [Section titled “Workload Management”](#workload-management) Navigate to Settings tab then to Inbox settings and add the Quickchat AI Agent to the Workload Management. ![Intercom Integration](/_astro/801073f9-8efe-4136-864a-cdc277149210.DvcnKCzO_1bl0a6.webp) ### Workflow Automation [Section titled “Workflow Automation”](#workflow-automation) Navigate to the Automation tab, and click on **Create new workflow** (“Customer starts a new message”). ![Alt text](/_astro/3d425786-2c3f-4d3d-857e-524472465027.CUOOz_QU_Z2wVHHu.webp) Once you’re at workflow, we set up a workflow automation. We assign it to the Intercom user you’ve created for Quickchat Assistant. ![Alt text](/_astro/2c040fc8-60ca-4a0e-8d32-0b2d0bca454a.Dwqs316t_Z1hsec9.webp) That’s it! 🎉 *Your integration is now complete!* Tip As a final verification of your integration, send a message to your Intercom chat window. You should get a reply from your AI Agent and the conversation should appear in the Inbox in the [Quickchat AI App](https://app.quickchat.ai). # Jira > Connect your Quickchat AI Agent to Jira. Enable AI-powered search and Q&A over your Jira tickets using Custom API Actions. In this post, I will show you how to connect your AI Agent to Jira. We will be using: * a Jira account (**free**) * a Quickchat’s AI Agent ([sign up here and use for **free**](https://app.quickchat.ai/register)) It will enable your Quickchat AI Agent to: * be able to search through your Jira tickets, and * be **smart** about answering questions based on them We will use Quickchat’s **AI Actions** (custom HTTP actions) to let your Agent call the [Enhanced search for issues](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/#api-rest-api-3-search-jql-get) endpoint of the Jira (Atlassian) API. ![Example Jira issues and conversation](/_astro/issues-plus-conversation.BPlZDb6t_Z2lQwer.webp) *Craft an AI Agent creative about interpreting user inputs* ## Watch the Video [Section titled “Watch the Video”](#watch-the-video) [Play](https://youtube.com/watch?v=D4NPTXQw-Qk) ## How it works [Section titled “How it works”](#how-it-works) Here is how your AI Agent will operate during conversations: 1. User asks a question like *“what’s up with issues to do with mercury?”* 2. AI Agent fetches relevant information from the **Jira API** using a query like *“mercury”* 3. AI Agent replies to the user based on the information **fetched from the API** Please follow the steps below. The whole setup shouldn’t take longer than **10 minutes**! ## Step 0 - create a Jira account and project [Section titled “Step 0 - create a Jira account and project”](#step-0---create-a-jira-account-and-project) 1. Go to [id.atlassian.com/signup](https://id.atlassian.com/signup), create and verify your account. 2. Add Jira to your Atlassian apps (the free plan will be enough to start). 3. Set up your first project and create tickets like in the example below. ![Example Jira issues](/_astro/jira-issues.BIvYa7pA_Z1o9w7G.webp) *Example board with Jira issues* ## Step 1 - Jira API authentication token [Section titled “Step 1 - Jira API authentication token”](#step-1---jira-api-authentication-token) Go to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) and create your **API token** which will look something like this: ```plaintext ATATT3xFfGF01sKUl0HEW2-_-u9umfLSz7jeblmeLzEHZ1DLcdLbKeVF137iTHGkKhPuNMSKX8mkbwLpHXT4-qXEn-xNEnfiK8_XDVW6XXvGd_SBV3HD4kJInGNjfg2_yEoJFN6uwy4NRqeuhV2tjmyzxozLBRn35OhXkDA6QGfLFvf2_PKuNtA=8DA704E4 ``` In order to be able to use your Atlassian API token in Quickchat AI Actions, **you need to base64-encode it** along with your email address: ```plaintext your_email@example.com:ATATT3xFfGF01sKUl0HEW2-_-u9umfLSz7jeblmeLzEHZ1DLcdLbKeVF137iTHGkKhPuNMSKX8mkbwLpHXT4-qXEn-xNEnfiK8_XDVW6XXvGd_SBV3HD4kJInGNjfg2_yEoJFN6uwy4NRqeuhV2tjmyzxozLBRn35OhXkDA6QGfLFvf2_PKuNtA=8DA704E4 ``` > Make sure to include the exact **email address** you used to set up your Atlassian account You can use a simple online tool like [base64encode.org](https://www.base64encode.org/). > Make sure to use the **Live mode** which guarantees the encoding happens entirely in your browser. ![base64encode.org](/_astro/base64encode.DAWXLVPG_ZMmOAB.webp) *You can use a free online tool to encode your API token* Alternatively, here is how to do it on your machine in a simple **python script**: ```python import base64 email = "your_email@example.com" api_token = "ATATT3xFfGF01sKUl0HEW2-_-u9umfLSz7jeblmeLzEHZ1DLcdLbKeVF137iTHGkKhPuNMSKX8mkbwLpHXT4-qXEn-xNEnfiK8_XDVW6XXvGd_SBV3HD4kJInGNjfg2_yEoJFN6uwy4NRqeuhV2tjmyzxozLBRn35OhXkDA6QGfLFvf2_PKuNtA=8DA704E4" credentials = f"{email}:{api_token}" b64_credentials = base64.b64encode(credentials.encode("utf-8")).decode("utf-8") print(f"Basic {b64_credentials}") ``` The above script will give you a **ready-to-use header** with the encoded token which looks something like this: ```plaintext Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ= ``` ## Step 2 - create a Quickchat AI Action [Section titled “Step 2 - create a Quickchat AI Action”](#step-2---create-a-quickchat-ai-action) In the [Quickchat AI app](https://app.quickchat.ai), go to **Actions & MCPs** and add an action: ![AI Action](/_astro/api-action-full-page.BAYmi-lq_Z1ewDfB.webp) *AI Action page* Give your AI Action an appropriate name: **Name**: `Search Jira issues` ![AI Action name](/_astro/api-action-full-page-action-name.fiArhxHO_10gN6m.webp) *Insert AI Action name* ## Step 3 - set input parameters [Section titled “Step 3 - set input parameters”](#step-3---set-input-parameters) Your AI Agent’s main task will be to translate what the user is asking about into an exact query to use to search through Jira issues. When it comes to searching for issues Jira recently fully migrated to [JQL (Jira Query Language)](https://support.atlassian.com/jira-software-cloud/docs/what-is-advanced-search-in-jira-cloud/) to allow for performing more complicated search. This allows your AI Agent to be much more powerful. Set up your input parameters as follows: | Format | Name | Description | Default value | Required | | :----- | :---- | :---------- | :------------ | :------- | | `Text` | `jql` | (see below) | - | ✅ | In order to achieve great performance with your AI Agent, a **well-crafted description** is hugely important: **Description:** ```plaintext A single valid JQL (Jira Query Language) string built per the description. Favor recall: prefer `(text ~ "term1" OR text ~ "term2")` over chaining with AND, and use parentheses for grouping. For "not started / in progress / done" questions, filter on `statusCategory` ("To Do", "In Progress", "Done"), which is stable across projects; use `status = "..."` only when the user names a specific status that exists on the board. Avoid custom fields. Examples: `statusCategory = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`, `(text ~ "planet*" OR text ~ "integration")`, `project = "Solar System" AND statusCategory = "To Do"`. ``` ![AI Action name](/_astro/api-action-full-page-input-parameters.BQM-qd1-_Z2kshgb.webp) *A well-crafted parameter description is key for AI Agent performance* ### A note on Jira statuses [Section titled “A note on Jira statuses”](#a-note-on-jira-statuses) Jira separates a status **name** from its **category**, and JQL treats them differently: * The **status name** is whatever the board shows. One project uses `To Do` / `In Progress` / `Done`, another uses `Open` / `In Review` / `Closed`. * The **status category** is one of three fixed buckets every status maps to: `To Do`, `In Progress`, `Done`. `status = "To Do"` filters by name, so it returns nothing on a board whose first column is named `Open`. This is a common reason an agent confidently reports “no tickets to do” while the board is full of them. For “what has not started”, “what is in progress” and “what is done” questions, filter on the category instead: ```plaintext statusCategory = "To Do" statusCategory = "In Progress" statusCategory = "Done" ``` Keep `status = "..."` for when the user names a specific status you know exists on the board. You can also list your board’s real status names in the Action description (Step 7) so the agent maps a request like “ready for QA” to the right one. ## Step 4 - set API endpoint URL [Section titled “Step 4 - set API endpoint URL”](#step-4---set-api-endpoint-url) 1. Select **GET** as the API request method 2. Set the endpoint URL to the Jira [/rest/api/3/search/jql](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/#api-rest-api-3-search-jql-get) endpoint ![API endpoint URL](/_astro/api-action-full-page-api-endpoint.I5_V8nk-_Z1UhrhC.webp) *Set your API endpoint URL* > Make sure to use **your Atlassian domain name**. You will find it in your Jira board URL. ![Atlassian workspace URL](/_astro/atlassian-workspace-url.GmeMPCDY_2laR3K.webp) *Your Atlassian domain name* ## Step 5 - set API request headers [Section titled “Step 5 - set API request headers”](#step-5---set-api-request-headers) Define your API request **headers** as follows: | Accept | Autorization | | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `application/json` | `Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==` | > Pay special attention to correctly formatting your Authorization header: Basic `` ![API request headers](/_astro/api-action-full-page-headers.DACWuJKw_1fDbbA.webp) *Set your API request headers* ## Step 6 - set API request query parameters [Section titled “Step 6 - set API request query parameters”](#step-6---set-api-request-query-parameters) Set two query parameters for your AI request: * `jql` is taking a dynamic value defined earlier in the *What to ask the user first* section. It is the AI Agent’s job to fill out the value of this parameter **based on what the user has said** in the conversation. * `fields` is taking a fixed value. For each Jira issues, we are only interested in its *summary*, *description* and *status*. | jql | fields | | :-------- | :--------------------------- | | `{{jql}}` | `summary,description,status` | ![API request query parameters](/_astro/api-action-full-page-query-params.Ffqc7xiz_164hP3.webp) *Set your API request query parameters* > Make sure the `jql` parameter correctly points to the value defined earlier. You can select it from the Add AI Data dropdown menu. ![Add AI Data dropdown menu](/_astro/query-params-dropdown.CdzCuQUY_1qlM4U.webp) *Select the dynamic `jql` parameter from the dropdown menu* ## Step 7 - set API Action description [Section titled “Step 7 - set API Action description”](#step-7---set-api-action-description) The final crucial ingredient of a well set-up AI Action is its description. While the AI Agent has a good understanding of your API endpoint just from its URL and parameters, it is key to optimize its behaviour **for your use case**. The three most important aspects included in the prompt are: * **when** to invoke the action — listing every phrasing the user might pick (find / search / look for, as well as explain / tell me about / describe / what is / how is the status of) so the agent does not skip the call when the user does not say “search” * suggestions on how to use the [advanced JQL syntax](https://support.atlassian.com/jira-software-cloud/docs/what-is-advanced-search-in-jira-cloud/) when searching for Jira issues * how to handle empty results — the agent must say so explicitly rather than refuse access Here is the resultant **API Action Description**: ```plaintext Use this action whenever the user asks anything that could be answered by data in their Jira — projects, issues, statuses, sprints, test cycles, descriptions, owners, comments — regardless of how they phrase the request (find / search / look for / explain / tell me about / describe / what is / how is the status of, etc.). Do not refuse access; query Jira first. Construct a JQL that prioritises recall over precision: prefer `(text ~ "term1" OR text ~ "term2")` over chaining with AND, and use parentheses for grouping. For lifecycle questions (not started, in progress, done) filter on `statusCategory` ("To Do" / "In Progress" / "Done") rather than `status`, because status names vary by board; use `status = "..."` only when the user names a specific status. Avoid custom fields. If Jira returns no matches, say so explicitly to the user and suggest a refined query. ``` ## Step 8 - test the API Action [Section titled “Step 8 - test the API Action”](#step-8---test-the-api-action) Before we test the AI Action in conversation, we can test how the API itself is being called in the **Test Response** tab. Let’s do a first test with the following query which should return all issues in the project: `project = "Solar System"` ![Test API endpoint](/_astro/test-api-endpoint1.CaGBvykr_ZJ1gFx.webp) *Searching for all issues in the `Solar System` project* Below is the test response we get. As expected, it lists the summary, description and status fields for all the 6 issues on our Jira board. ![Test API endpoint response](/_astro/test-api-endpoint-response1.CGyoxgrj_Zc60d7.webp) *Response lists all issues in the `Solar System` project* Let’s try one more query. This time let’s search for all the issues which mention “mercury”: `text ~ "mercury"` ![Test API endpoint response](/_astro/test-api-endpoint-response2.BZpfdNaW_1ezbVE.webp) *Searching for issues which mention `mercury`* We have now validated that the AI Action correctly calls our API endpoint. We can now move on to testing full conversations with the AI Agent! ## Step 9 - test the AI Agent in conversations [Section titled “Step 9 - test the AI Agent in conversations”](#step-9---test-the-ai-agent-in-conversations) Head back to the [Quickchat AI app](https://app.quickchat.ai) and test your AI Agent in conversation preview. ### Conversation #1 [Section titled “Conversation #1”](#conversation-1) ![Test conversation #1](/_astro/test-conversation1.CwCTFgYe_m7wVQ.webp) *AI Agent gives a summary of all issues within the project* In this simple conversation the AI Agent gives an overview of all the issues within the project. A look behind the scenes tell us that the exact query it ran against the API endpoint was: `project = "Solar System"` ### Conversation #2 [Section titled “Conversation #2”](#conversation-2) ![Test conversation #2](/_astro/test-conversation2.C_4YwE03_W5Pa3.webp) *AI Agent responds to questions about specific issues and statuses* In this case, the AI Agent was asked about two separate aspects: a specific issue and issues ongoing in general. A look behind the scenes tells us that it decided to use the Jira API in a two-step process: 1. Check if `pluto` is ongoing: ```plaintext status = "In Progress" AND (text ~ "pluto" OR text ~ "ongoing" OR text ~ "current" OR text ~ "active" OR text ~ "progress") ``` 2. Check what else is ongoing: ```plaintext status = "In Progress" ``` ### Conversation #3 [Section titled “Conversation #3”](#conversation-3) ![Test conversation #3](/_astro/test-conversation-showcase.DwSaUt8I_Z1g6GWJ.webp) *AI Agent responds to a creative query 😉* In this case I wanted to throw a curveball at the AI Agent and asked it a question that takes some creativity to interpret correctly. Here is how it got translated into a JQL query: ```plaintext (text ~ "planet" OR text ~ "upstream" OR text ~ "mercury" OR text ~ "venus") ``` ### Try these phrasings [Section titled “Try these phrasings”](#try-these-phrasings) To be confident the AI Action fires no matter how your end users phrase their request, run each of the prompts below against your test scenario. The agent should query Jira on every one of them, not just the search-style ones: * *“find all open issues about live scores”* * *“search for issues with `mercury`”* * *“explain the Solar System project”* * *“tell me about the open issues in this sprint”* * *“describe what’s currently in progress”* * *“what is the status of pluto?”* If any of these phrasings does not invoke the AI Action, double-check that your API Action description (Step 7) lists those verbs explicitly. What to expect when Jira has no matching issues When Jira returns zero results, your AI Agent should say so explicitly — for example, *“I checked Jira and found no matching issues for your query — try a broader phrasing or remove the status filter.”* If instead you see the agent reply with *“I don’t have direct access to your Jira”*, the AI Action did not fire at all. Re-check the description from Step 7 and confirm that it explicitly lists non-search verbs (`explain`, `tell me about`, `describe`, `what is`). ## Summary [Section titled “Summary”](#summary) In this post, we showed how an AI Agent can be set up to use a specific API endpoint in a creative way in conversations. The correct setup doesn’t come out of the box - it requires providing detailed extra information of the specific use case we have in mind. Please feel free to reuse the prompts and descriptions shown in this post for creating your own similar AI Agents! > Prefer a long-form, narrated walkthrough? The same setup is also covered as a [blog post on quickchat.ai](https://quickchat.ai/post/search-jira-tickets-in-ai-conversation). This docs page is the canonical, continuously-updated reference. ## Going further [Section titled “Going further”](#going-further) A Jira action does not have to be a single fixed request. You can inject [built-in conversation variables and saved metadata](/ai-agent/variables/) (such as the visitor’s language or values captured earlier in the conversation) into any field, and you can add several actions so the agent picks the right one per question. See the [Actions reference](/ai-agent/actions/) for the full set of options. ## 🎁  BONUS [Section titled “🎁  BONUS”](#bonus) The above post was written by a *human* (yours truly) but could have just as well been written by AI. For example, by pasting a prompt like this one into ChatGPT: ```plaintext I need an API endpoint that allows me to search through my Jira tickets. Guide me through the process step by step so that it is accessible to a moderately technical person: - Provide links to documentation describing the endpoint - Any necessary account creation and initial setup - If any paid account is needed, indicate that clearly - If any authentication such as API tokens is needed, guide me through the process of creating them and show me exactly every step needed to be able to use them as an HTTP request header. For example, if base64 encoding is needed, show a script or another way of achieving that. - Show to me exactly what header keys and values I need for the HTTP request (show me header keys and values in a table) - Show to me exactly what payload parameters I need for the HTTP request (show me payload parameter name and example values in a table) ``` In the future, perhaps rather than search through Jira tickets you would like to: * *send messages to a Slack channel?* * *fetch information from a Notion page?* * *perform an action via Zapier?* Say that in the first sentence and run the prompt again! You will obtain perfectly good instructions to add the exact AI Action you need! # MCP > Launch your own MCP server with Quickchat AI. Let Claude, ChatGPT, Cursor, and other AI apps connect to your Agent via the Model Context Protocol. When iPhones took off, every company needed an app in the App Store. Now, as AI chat apps gain traction (and MCP becomes the standard) every company will need an MCP that lets others plug into their AI. Starting today, **every Quickchat AI user can launch their own MCP with a single click.** Most people describe MCPs as the USB-C of AI — the universal connector for AI apps, a simple, standardized way to add any tool to platforms like Claude or ChatGPT. But here’s how we see it: MCP lets your favorite AI app message another AI on your behalf and let you know what it said. With Quickchat AI MCP, anyone can plug your AI Agent into Claude, (soon) ChatGPT, Cursor, or any other AI app that supports the protocol. If you need a refresher on what MCP is, check out our [detailed, step-by-step guide](https://www.quickchat.ai/post/mcp-explained). ## Watch the Video [Section titled “Watch the Video”](#watch-the-video) [Play](https://youtube.com/watch?v=JE3dNiyZO8w) ## What is Quickchat AI MCP server? [Section titled “What is Quickchat AI MCP server?”](#what-is-quickchat-ai-mcp-server) The [Quickchat AI](https://quickchat.ai/) MCP ([Model Context Protocol](https://modelcontextprotocol.io/)) server allows you to let anyone plug in your Quickchat AI Agent into their favourite AI app such as Claude Desktop, Cursor, VS Code, Windsurf and [more](https://modelcontextprotocol.io/clients#feature-support-matrix). ## Quickstart [Section titled “Quickstart”](#quickstart) 1. Create a [Quickchat AI account](https://app.quickchat.ai/). The Free plan lets you get started right away. 2. Set up your AI’s Knowledge Base, capabilities, and settings. 3. Go to the MCP page to activate your MCP. Give it **Name**, **Description** and (optional) **Command**. They are important — AI apps need to understand when to contact your AI, what its capabilities and knowledge are. 4. That’s it! Now you’re ready to test your Quickchat AI via any AI app and show it to the world! ![](/_astro/LaunchMCP_img1.C8_hdiQD_ZY4u0F.webp) *Claude tool anatomy* ![](/_astro/LaunchMCP_img2.HeGLtqEb_Z1OGqby.webp) *Cursor tool anatomy* ## Prerequisite [Section titled “Prerequisite”](#prerequisite) Install `uv` using: `curl -LsSf https://astral.sh/uv/install.sh | sh` or read more [here](https://docs.astral.sh/uv/getting-started/installation/). ## Test with Claude Desktop [Section titled “Test with Claude Desktop”](#test-with-claude-desktop) ### Configuration [Section titled “Configuration”](#configuration) Go to Settings > Developer > Edit Config. Open the *claude\_desktop\_config.json* file in a text editor. If you’re just starting out, the file is going to look like this: ```typescript { "mcpServers": {} } ``` ‍ This is where you can define all the MCPs your Claude Desktop has access to. Here is how you add your Quickchat AI MCP: ```typescript { "mcpServers": { "< QUICKCHAT AI MCP NAME >": { "command": "uvx", "args": ["quickchat-ai-mcp"], "env": { "SCENARIO_ID": "< QUICKCHAT AI SCENARIO ID >", "API_KEY": "< QUICKCHAT AI API KEY >" } } } } ``` ‍ Go to the Quickchat AI app > MCP > Integration to find the above snippet with the values of MCP Name, SCENARIO\_ID and API\_KEY filled out. ## Test with Cursor [Section titled “Test with Cursor”](#test-with-cursor) ### Configuration [Section titled “Configuration”](#configuration-1) Go to Settings > Cursor Settings > MCP > Add new global MCP server and include the Quickchat AI MCP snippet: ```typescript { "mcpServers": { "< QUICKCHAT AI MCP NAME >": { "command": "uvx", "args": ["quickchat-ai-mcp"], "env": { "SCENARIO_ID": "< QUICKCHAT AI SCENARIO ID >", "API_KEY": "< QUICKCHAT AI API KEY >" } } } } ``` ‍ As before, you can find values for MCP Name, SCENARIO\_ID and API\_KEY at Quickchat AI app > MCP > Integration. ## Test with other AI apps [Section titled “Test with other AI apps”](#test-with-other-ai-apps) Other AI apps will most likely require the same configuration but the actual steps to include it in the App itself will be different. We will be expanding this blog post as we go along. ## Launch your Quickchat AI MCP to the world! [Section titled “Launch your Quickchat AI MCP to the world!”](#launch-your-quickchat-ai-mcp-to-the-world) **⛔️ Do not publish your Quickchat API key to your users!** Once you’re ready to let other users connect your Quickchat AI MCP to their AI apps, share configuration snippet with them! However, you need to make sure they can use your Quickchat AI MCP **without your Quickchat API key**. Here is how to do that: 1. On the Quickchat App MCP page, turn the **Restrict Access with API Key** toggle **OFF**. 2. Share the configuration snippet *without the API key*: ```typescript { "mcpServers": { "< QUICKCHAT AI MCP NAME >": { "command": "uvx", "args": ["quickchat-ai-mcp"], "env": { "SCENARIO_ID": "< QUICKCHAT AI SCENARIO ID >" } } } } ``` ### Cool features [Section titled “Cool features”](#cool-features) * You can control all aspects of your MCP from the Quickchat AI dashboard. With one click, your changes are deployed. That includes the MCP name and description — all your users need to do is refresh their MCP connection. * View all conversations in the Quickchat Inbox. Remember: those won’t be the exact messages your users send to their AI app but rather the transcript of the AI-AI interaction between their AI app and your Quickchat AI. * Unlike most MCP implementations, this isn’t just a static tool handed to an AI. * It’s an open-ended way to send messages to Quickchat AI Agents you create. ## Running from source [Section titled “Running from source”](#running-from-source) ### Debugging with the [MCP inspector](https://modelcontextprotocol.io/docs/tools/inspector) [Section titled “Debugging with the MCP inspector”](#debugging-with-the-mcp-inspector) uv run mcp dev src/**main**.py ### Debugging with Claude Desktop, Cursor or other AI apps [Section titled “Debugging with Claude Desktop, Cursor or other AI apps”](#debugging-with-claude-desktop-cursor-or-other-ai-apps) Use the following JSON configuration: ```typescript { "mcpServers": { "< QUICKCHAT AI MCP NAME >": { "command": "uv", "args": [ "run", "--with", "mcp[cli]", "--with", "requests", "mcp", "run", "< YOUR PATH>/quickchat-ai-mcp/src/__main__.py" ], "env": { "SCENARIO_ID": "< QUICKCHAT AI SCENARIO ID >", "API_KEY": "< QUICKCHAT AI API KEY >" } } } } ``` ### Testing [Section titled “Testing”](#testing) Make sure your code is properly formatted and all tests are passing: ```shell ruff check --fix ruff format uv run pytest ``` ## Ready to go? [Section titled “Ready to go?”](#ready-to-go) With just a few steps, you can make your Quickchat AI Agent accessible from anywhere. Whether you’re building internal tools or sharing your AI with the world, our MCP integration makes it easy. You also get: * ✅ A shared Inbox to view conversations * 🔄 Conversation analytics via the Dashboard ### **Useful Links** [Section titled “Useful Links”](#useful-links) * [GitHub Repository](https://github.com/quickchatai/quickchat-ai-mcp) * [PyPI Package](https://pypi.org/project/quickchat-ai-mcp/) * [YouTube Walkthrough](https://www.youtube.com/watch?v=JE3dNiyZO8w) * [MCP Official Website](https://modelcontextprotocol.io/) *Ready to go?* Go to the [Quickchat AI app](https://app.quickchat.ai) and let the world connect to your AI. And if you build something cool with your MCP, we’d love to see it! Share it with us on [Twitter](https://x.com/quickchatai) or [LinkedIn](https://www.linkedin.com/company/quickchatai/). # Shopify > Add the Quickchat AI shopping assistant to your Shopify store. Install via the Shopify App Marketplace or embed the widget manually. In this guide, we’ll show how to add Quickchat AI Widget to your Shopify store. ## What you’ll need [Section titled “What you’ll need”](#what-youll-need) * A Shopify store * The [**Shopping Agent by Quickchat AI**](https://apps.shopify.com/quickchat-ai) app installed from the Shopify App Marketplace (if you don’t want to install it and you’d rather connect it manually, [scroll down to the second part of the tutorial](#how-to-manually-add-a-widget-script)) * User permission to edit themes *Time to complete: \~2 minutes* *** ## What are Shopping AI Agents? [Section titled “What are Shopping AI Agents?”](#what-are-shopping-ai-agents) In this short video you will learn the basics: how to turn your Shopify store into a Shopping AI Agent using Quickchat AI and Shopify MCP. [Play](https://youtube.com/watch?v=NPZEg4OVSRE) ## Step 1: Open your Theme Editor [Section titled “Step 1: Open your Theme Editor”](#step-1-open-your-theme-editor) There are two ways to do it: ### Option A (recommended): from Quickchat AI App [Section titled “Option A (recommended): from Quickchat AI App”](#option-a-recommended-from-quickchat-ai-app) From the [Quickchat AI App](https://app.quickchat.ai) home/welcome page, find the Shopify card (“Welcome, Shopify User!”) and click **Open Shopify Theme Editor**. This deep-links to your store’s Shopify Theme Editor directly in the App embeds context, where the app embed can be enabled. Note **Open Shopify Theme Editor** only appears for stores already connected to Quickchat AI via the Shopify app (OAuth). ### Option B: from Shopify Admin [Section titled “Option B: from Shopify Admin”](#option-b-from-shopify-admin) Go to [Shopify Admin](https://admin.shopify.com/) → **Online Store → Themes** → on your current theme click **Customize**. ![Screenshot: Themes page with the Customize button highlighted](/_astro/1-Customize.kXpfCtQj_1ngjvp.webp) *** ## Step 2: Enable the app embed [Section titled “Step 2: Enable the app embed”](#step-2-enable-the-app-embed) Inside the Theme Editor, open the left sidebar and go to **App embeds**. ![Screenshot: App embeds panel](/_astro/2-App_embeds.DKD14wCr_Z2eDGwd.webp) Find **Quickchat AI Widget** and toggle it **on**. ![Screenshot: Enable Quickchat AI in the Theme Editor](/_astro/3-Enable_Quickchat_AI.D1FqUroH_Zx9cgv.webp) Then click **Save** (top-right). ![Screenshot: Save button in the Theme Editor](/_astro/4-Save_changes.DSUh2_7g_22HL28.webp) *** ## Step 3: Confirm on your storefront [Section titled “Step 3: Confirm on your storefront”](#step-3-confirm-on-your-storefront) Open your storefront (preview or live site) and look for the Quickchat AI chat bubble in the bottom-right corner of the page. That’s it! **Quickchat AI Agent is live on Shopify Store 🎉** *** ## How to manually add a widget script [Section titled “How to manually add a widget script”](#how-to-manually-add-a-widget-script) If you don’t want to install our Shopify App because you already have an AI Agent built in Quickchat AI App, you can add a simple script that displays it on your Shopify Store. Have you connected your AI to Shopify data already? To connect your AI Agent to your Shopify store’s data such as product catalog and cart, please do the following: 1. Paste your store link on this page: [quickchat.ai/shopify](https://quickchat.ai/shopify) 2. Claim it, customize, and embed on your site ### 1. Open the theme code editor [Section titled “1. Open the theme code editor”](#1-open-the-theme-code-editor) 1. Go to your [Shopify Admin Panel](https://admin.shopify.com/). 2. In the left menu, click **Online Store → Themes**. ![Edit theme code](/_astro/step1.D2A2jU3m_160AOB.webp) 3. In the “Current theme” section, click the **three dots (⋯)** next to the **Customize** button. 4. Select **Edit code** from the dropdown. ![Open theme.liquid](/_astro/step2.DTegQpNx_1BPXt5.webp) ### 2. Find `theme.liquid` [Section titled “2. Find theme.liquid”](#2-find-themeliquid) 1. In the code editor, expand the **layout** folder on the left. 2. Click on `theme.liquid` to open the main layout file of your theme. ![Open theme.liquid](/_astro/step3.f8kBmP3p_1wxKF8.webp) ### 3. Paste the script [Section titled “3. Paste the script”](#3-paste-the-script) 1. In the [Quickchat App](https://app.quickchat.ai), navigate to **Your Website → Install**. 2. Copy the generated script. 3. Paste it just **above the `` tag** at the bottom of the `theme.liquid` file. ```html ``` # Slack > Connect Quickchat AI to Slack. Use the one-click OAuth integration, or set up a Slack app manually with the legacy flow. There are two ways to connect your AI Agent to Slack: 1. **Slack (OAuth)**: the recommended one-click integration. Authorize Quickchat AI in your Slack workspace and you’re done. 2. **Slack (Legacy)**: the legacy flow where you create a Slack app yourself, paste a manifest, and supply tokens manually. We recommend the OAuth integration if you’re setting this up for the first time. ## Connect with Slack (recommended) [Section titled “Connect with Slack (recommended)”](#connect-with-slack-recommended) In the Quickchat AI dashboard, go to **External Apps**, find **Slack**, and click **Connect with Slack**. This connects Slack via OAuth so your bot can reply in your workspace. ![slack\_integration](/_astro/slack_integration.DmW-JxaA_ZDAk7J.webp) You’ll be redirected to Slack to authorize the app in your workspace. Approve the requested permissions and you’ll be brought back to the dashboard, where Slack shows as connected. OAuth grants the full set of scopes automatically (`im:history`, `im:write`, `chat:write`, `app_mentions:read`, `channels:history`, `groups:history`), so there’s no manifest to edit and no basic-vs-expanded choice to make. And that’s it! 🎉 **Your AI chat bot is ready to be tested on Slack!** ![Your AI chat bot replying in Slack](/_astro/end_goal_blog_post.DsHLEAP4_Z1cUN7o.webp) ### Reply behavior [Section titled “Reply behavior”](#reply-behavior) Both Slack integrations expose two toggles that control where your bot replies: * **Reply to everyone in thread**: when on, the bot replies to messages from anyone in a thread, not just to the person who started it. * **Reply to all messages in channel**: when on, the bot replies to all messages in a channel it has been added to, not only when it’s directly @mentioned. When someone opens the bot’s App Home (the `app_home_opened` event), the bot sends its welcome message. ## Slack (Legacy) [Section titled “Slack (Legacy)”](#slack-legacy) This is the legacy Slack app integration using manual bot tokens. Prefer the OAuth Slack integration above if you’re setting this up for the first time. The manifest flow below is still accurate if you need the manual path. In this section we’ll cover: 1. Creating a dedicated Slack app 2. Configuring the Slack app 3. Integrating your Slack bot with Quickchat AI ### Create your Slack app [Section titled “Create your Slack app”](#create-your-slack-app) To begin the integration process, you will need a Slack app for your AI chat bot. Head over to [api.slack.com/apps](https://api.slack.com/apps) and click on **create a new app**. Tip Here, we walk through creating the app from scratch. If you’ve done this sort of thing before, you can go directly to building from app manifest that we provide below. ![create\_slack\_app\_1](/_astro/create_slack_app_1.B3Po1y0t_ZqXqfs.webp) Then select **Create an app from scratch**, set your AI Agents’s name and select the Slack workspace you want to add it to and click **Create App**. ![create\_slack\_app\_2](/_astro/create_slack_app_2.BnYM3ZhZ_Z1wIwXM.webp) ![create\_slack\_app\_3](/_astro/create_slack_app_3.CmV8idzN_iasnI.webp) ### Configure your Slack app [Section titled “Configure your Slack app”](#configure-your-slack-app) Slack has a neat way of configuring your entire app in one go. You do it through the so called **manifest** file which contains all of your app’s configuration. Upon creating the app, you will be redirected to the App Settings. Within the Features section in the menu panel, navigate to App Manifest. ![create\_slack\_app\_5](/_astro/create_slack_app_5.BAOomnyI_29osDA.webp) Below we have prepared a manifest file which you should paste into Slack’s App Manifest window (make sure you paste YAML, not JSON). You can easily copy and paste without worrying about the details. We explain the most important lines below: * **Set the appropriate name and description for your AI Agent** (`display_information`) * **Make sure your bot’s messages tab has been enabled** (`features/app_home/messages_tab_enabled`) * **Set permission scope for bot so it can read and write chat messages** (`oauth_config/scopes`) * **Set the appropriate bot events to be handled by our Quickchat server** (`settings/event_subscriptions/bot_events`) ```yaml display_information: name: Talk to AI description: Talk to me about Quickchat! features: app_home: home_tab_enabled: false messages_tab_enabled: true messages_tab_read_only_enabled: false bot_user: display_name: Talk to AI always_online: true oauth_config: scopes: bot: - im:history - im:write - chat:write settings: event_subscriptions: request_url: https://slack.quickchat.ai/chat/ bot_events: - message.im - app_home_opened org_deploy_enabled: false socket_mode_enabled: false token_rotation_enabled: false ``` Tip If you would also like to be able to @mention the bot in other channels and receive responses in threads, expand the manifest file as follows. ```yaml display_information: name: Talk to AI description: Talk to me about Quickchat! features: app_home: home_tab_enabled: false messages_tab_enabled: true messages_tab_read_only_enabled: false bot_user: display_name: Talk to AI always_online: true oauth_config: scopes: bot: - im:history - im:write - chat:write - app_mentions:read - channels:history - groups:history settings: event_subscriptions: request_url: https://slack.quickchat.ai/chat/ bot_events: - message.im - app_home_opened - app_mention - message.groups - message.channels org_deploy_enabled: false socket_mode_enabled: false token_rotation_enabled: false ``` Save the manifest. Before the changes take place, you will be prompted to verify the URL by clicking on the link: ![create\_slack\_app\_6](/_astro/create_slack_app_6.CHjw0CiG_RdMXf.webp) That’s it! Your bot Slack app has been configured. If you’d like to edit your bot’s look & feel, head over to Basic information under Settings, then in the Display Information Section: ![create\_slack\_app\_7](/_astro/create_slack_app_7.CgtuStWf_8vAdb.webp) ### Integrate your Slack bot with Quickchat AI [Section titled “Integrate your Slack bot with Quickchat AI”](#integrate-your-slack-bot-with-quickchat-ai) We are almost done. As the last step we need to Integrate the Slack bot with Quickchat AI. To do this, we first need to obtain some information from Slack: * **App ID**: Settings → Basic Information → App Credentials * **Signing Secret**: Settings → Basic Information → App Credentials * **Bot User OAuth Token**: Features → OAuth & Permissions → OAuth Tokens for Your Workspace 👉 You will be prompted to install the bot into your workspace. Upon clicking **Allow** you will be redirected back to the settings where OAuth Token will be ready to copy. ![create\_slack\_app\_8](/_astro/create_slack_app_8.DdjJ0yHo_1CsLHs.webp) You will be needing this information in the next step, so keep the tab open. In a new tab, open the Quickchat AI dashboard, go to **External Apps**, find Slack and supply the App ID, Signing Secret and the OAuth Token. ![slack\_integration](/_astro/slack_integration.DmW-JxaA_ZDAk7J.webp) And that’s it! 🎉 **Your AI chat bot is ready to be tested on Slack!** YAY! # Telegram > Integrate your Quickchat AI Agent with Telegram. Create a bot with BotFather, connect it to Quickchat, and go live in minutes. In this guide we’ll connect your AI Agent to Telegram in two steps: 1. Create a Telegram bot with BotFather 2. Connect the bot to Quickchat AI If you get stuck, jump to [Troubleshooting & FAQs](#troubleshooting--faqs) or [contact us](https://quickchat.ai/contact). ## Step 1 — Create your Telegram bot [Section titled “Step 1 — Create your Telegram bot”](#step-1--create-your-telegram-bot) Telegram bots are created through **BotFather**, Telegram’s official bot for managing bots. Everything happens inside a normal Telegram chat, so there’s no developer portal to sign up for. 1. Open Telegram and start a chat with [@BotFather](https://t.me/BotFather) (look for the blue verified checkmark). 2. Send `/newbot`. 3. Choose a **name** for your bot. This is the display name people see in the chat, for example “Acme Support”. 4. Choose a **username**. It must be unique and end in `bot`, for example `acme_support_bot`. ![Creating a bot with BotFather](/_astro/telegram_intro.xxKNAw0o_THcJ0.webp) BotFather replies with your **bot token**, a string that looks like `5175890488:AAEI8qpz...`. You’ll paste it into Quickchat in the next step, so keep the chat open. Caution Treat your bot token like a password. Anyone who has it can control your bot. If it ever leaks, send `/revoke` to BotFather to invalidate the old token and get a new one. Tip You can personalize your bot at any time from BotFather: `/setdescription`, `/setabouttext`, `/setuserpic` (profile picture) and `/setcommands`. Send `/help` to see the full list. ## Step 2 — Connect your bot to Quickchat AI [Section titled “Step 2 — Connect your bot to Quickchat AI”](#step-2--connect-your-bot-to-quickchat-ai) 1. Open the [Quickchat AI App](https://app.quickchat.ai) and go to **External Apps**. 2. Click **Telegram**. 3. Enable the integration and paste your **bot token**. 4. Save. ![Telegram integration in the Quickchat AI dashboard](/_astro/telegram_integration.CbcIUGZI_1DwDp7.webp) That’s it. **Your AI Agent is now live on Telegram!** 🎉 ## Try it out [Section titled “Try it out”](#try-it-out) Open your bot in Telegram (BotFather gives you a `t.me/` link) and send `/start`. Your AI Agent replies with its welcome message and then answers anything you ask. Every conversation also appears in your [Quickchat AI Inbox](https://app.quickchat.ai), where you can read the full transcript, see the visitor’s Telegram name, and take over from the AI at any time. ## Troubleshooting & FAQs [Section titled “Troubleshooting & FAQs”](#troubleshooting--faqs) **My bot doesn’t reply.** * Make sure the **Telegram integration is enabled** and the **bot token is pasted correctly** (no extra spaces). If in doubt, `/revoke` in BotFather and paste the fresh token. * Send `/start` to the bot first. This is how Telegram activates the chat. * One bot connects to **one AI Agent**. Don’t reuse the same token across multiple Quickchat AI Agents. **Does the bot work in group chats?** * Yes, but by default Telegram bots run in **privacy mode**, so the bot only sees messages that directly mention it or start with `/`. To let your AI Agent respond to every message in a group, open BotFather, send `/setprivacy`, pick your bot and choose **Disable**, then remove and re-add the bot to the group. **How do I change the welcome message?** * The message sent on `/start` is your AI Agent’s greeting, configured in the [Quickchat AI App](https://app.quickchat.ai). Update it there and it applies to every channel, including Telegram. **Can I connect a bot I already have?** * Absolutely. Open it in BotFather, run `/token` to retrieve (or `/revoke` to reset) its token, and paste that into the Telegram integration. No need to create a new bot. **Can the bot handle images and files?** * **Photos** are analyzed by your AI Agent, which can describe them and answer questions about what they show. For other **files** (PDFs, documents), the Agent is told a file was sent and its filename, but it does not read the file’s contents. See [Images & files](/ai-agent/attachments/) for details. ## Watch the Video [Section titled “Watch the Video”](#watch-the-video) [Play](https://youtube.com/watch?v=N1QkRTp_ec0) ## Need Help? [Section titled “Need Help?”](#need-help) Still stuck? Reach out on [Discord](https://discord.gg/KqkHwvPRNH) or [contact us](https://quickchat.ai/contact) and we’ll help you get your bot live. # Website > Deploy Quickchat AI on your website as a floating Widget, an inline Embed, or a hosted Chat Page. Covers install, access control, appearance, text content, and custom parameters. There are three ways to put your Quickchat AI Agent on the web — pick whichever fits the surface you want to show: * **Widget** — the floating chat bubble in the corner of your site. Best for general-purpose support. * **Embed** — an inline chat window that sits exactly where you want it on a page. Best for embedding the AI inside a specific app screen, help-centre page, or product detail page. * **Chat Page** — a hosted, full-screen chat experience served by Quickchat (no installation, no code). Best when you want to share a link with someone (e.g., support email, internal Slack, beta testers) without touching their browser. Install your chosen surface from **Channels → Your Website → Install**. The page has three sub-tabs that mirror the structure of this article: **Install** (snippets + access), **Appearance** (visual styling), and **Text Content** (the prompts and labels visible to the visitor). ## Widget [Section titled “Widget”](#widget) The **Widget** allows you to embed your Quickchat AI Agent directly into your website, providing users with a seamless way to interact with the AI. The Widget is typically displayed as a chat bubble in the bottom-right corner of your webpage. When clicked, it expands into a chat window, enabling users to ask questions, get assistance, or access information. ### How to embed the Widget on your website [Section titled “How to embed the Widget on your website”](#how-to-embed-the-widget-on-your-website) 1. Locate your page’s code Open your webpage’s HTML file or access the code editor of your website builder. 2. Get the Widget Code * Log into the **Quickchat AI App**. * Go to the **Website** section under the **Channels** category in the left sidebar. * Click the **Install** tab. * Copy the **Widget script** code. 3. Paste the Code Insert the Widget script just before the closing `` tag on all pages where you want the Widget to appear. ### If you use WordPress [Section titled “If you use WordPress”](#if-you-use-wordpress) The easiest way is our official **[Quickchat AI Agent plugin](/channels/wordpress/)**: install it from the WordPress Plugin Directory, paste your Scenario ID, and the Widget appears automatically, with no theme code to edit. The [WordPress guide](/channels/wordpress/) has step-by-step instructions, plus a manual-script option if you’d rather not use the plugin. ### If you use a Website Builder [Section titled “If you use a Website Builder”](#if-you-use-a-website-builder) If you use platforms like WordPress, Webflow, or Wix, refer to their documentation on adding custom code. For help, contact us at ****. ## Chat Page [Section titled “Chat Page”](#chat-page) **Chat Page** is a hosted, full-screen version of your AI Agent that lives on a Quickchat URL. There’s nothing to install — share the link and your visitors can chat with your Agent directly in their browser. Use it when: * You want a chat experience but don’t have a website (or don’t want to touch its code). * You’re sharing the AI internally with a small group (beta testers, support team, sales prospects) and need an access-controlled link instead of a public widget. * You want to send the AI as a follow-up channel in email, Slack, or your CRM. Configure who can open the Chat Page from **Install → Chat Page Access** (see [Access control](#access-control) below). ## Access control [Section titled “Access control”](#access-control) The Install tab has two access controls that apply to your deployment: ### Widget & Embed access [Section titled “Widget & Embed access”](#widget--embed-access) A master toggle at the top of the Install tab. When **enabled**, the Widget and Embed scripts work normally on visitors’ browsers. When **disabled**, the Widget and Embed are unavailable on your site even if the script is still pasted in — useful for taking the AI offline temporarily without removing the snippet, or for restricting public access while you keep the Chat Page open to invited users. ### Chat Page Access [Section titled “Chat Page Access”](#chat-page-access) Independent of the Widget & Embed toggle, you can restrict who can open the **Chat Page**: * **Anyone** — the Chat Page URL is public. Anyone with the link can use it. * **Invited users only** — only **Chat Users** you’ve invited (by email) can use the Chat Page. They’ll need to authenticate. * **Nobody** — the Chat Page is fully disabled. To grant access under **Invited users only**, click **Invite Chat Users** next to the radio — that takes you to **Account Settings → Chat Users**, where you can send invitations by email and manage who has access. ## Customizing [Section titled “Customizing”](#customizing) The **Appearance** and **Text Content** sub-tabs let you tailor how the Widget, Embed, and Chat Page look and what copy your visitors see. All three deployment surfaces share these settings — change them once and they apply everywhere your Agent is deployed. The right pane of the Install/Appearance/Text Content tabs has its own preview controls — toggle between **Widget**, **Embed**, and **Chat Page** previews, and between **Desktop** and **Mobile** viewports, to see your changes before you publish. ### Appearance [Section titled “Appearance”](#appearance) Visual styling for the chat surfaces, grouped into Branding, Size & Position, Theme, and Other Settings. #### Branding [Section titled “Branding”](#branding) * **AI Agent Avatar** — a single image used both in the chat header and on the launcher button (max 5 MB). This is one setting, not two: upload one image and it appears in both places (it replaces the old separate “header logo” and “launcher icon”). Every Agent starts with a built-in default avatar. **Reset to default** restores it, and deleting it shows no avatar at all. #### Size & Position [Section titled “Size & Position”](#size--position) * **Launcher size** — **Classic**, **Input Only**, or **Small**. Controls how the chat launcher looks before it’s opened. * **Launcher label** — shown only when **Small** is selected: custom text on the small launcher button (up to 25 characters), e.g. *“Ask AI”* or *“Chat”*. Leave it empty for an icon-only launcher. * **Widget position** — bottom-right or bottom-left. * **Chat window dimensions** — width (300–700px) and height (400–1200px) of the chat window. * **Draggable launcher** — let visitors drag the launcher to a different spot on the page. Useful when it covers important content. #### Theme [Section titled “Theme”](#theme) Choose how the chat surfaces are colored: * **Light** and **Dark** are fixed presets that look the same on every account. * **Custom** unlocks a full palette of your own. When Custom is selected, color controls appear for the background, header and header text, accent (used for buttons such as the pre-chat start button, suggestion chips, and rating actions), message bubble and its text, AI message text, **link color**, the input field, borders, and more. Each color is checked for WCAG AA contrast against its background and warns you when a pairing is hard to read. Branded header and accent colors live in the **Custom** theme. Light and Dark stay neutral presets, so switching between them never carries a custom color over. When Custom is selected, the **Chat Page** also gets its own sidebar colors: **Sidebar background**, **Sidebar text**, **Sidebar hover**, and **Sidebar hover text**. These apply only to the full-page Chat Page view, not the Widget bubble or Embed. Leave the text colors unset and the Chat Page picks a readable color automatically for the background you choose. You can also set the **corner radius** (roundness of bubbles, inputs, and buttons) and the **text size**. Both apply in every theme mode. #### Other Settings [Section titled “Other Settings”](#other-settings) * **Auto-open Widget** — automatically open the Widget when the page loads. * **Remove Quickchat AI branding** — hide the “Powered by Quickchat AI” footer for a fully white-labeled experience (available on plans that include white-labeling). * **Conversation rating** — let visitors rate the conversation at the end. Results appear in [Insights → Conversation Rating](/conversations/insights/#conversation-rating). ### Text Content [Section titled “Text Content”](#text-content) The **Text Content** sub-tab controls every piece of copy visible to the visitor: * **Header text** — text shown at the top of the chat window. * **Welcome message** — the first message from the AI Agent at the start of each conversation (e.g., *“Hey, do you need help?”*). * **Show as a pop-up** — toggle that shows the welcome message as a floating speech bubble next to the launcher to grab attention before the visitor clicks. * **Conversation starters** — up to **3** example messages shown to the visitor before they start typing. Clicking one sends it as the first message — useful for nudging visitors towards your AI’s strengths (*“How do I install the widget?”*, *“What integrations do you support?”*). * **Input placeholder** — hint text in the empty message input. * **Disclaimer text** — text shown behind the conversation, typically informing users they’re talking to an AI. We recommend keeping this clear and visible. ### Advanced Features: Custom Parameters [Section titled “Advanced Features: Custom Parameters”](#advanced-features-custom-parameters) The Quickchat AI Widget and Embed allow you to pass **custom parameters** on initialization. They can be used to: * enhance analytics (they are available in the CSV export on the Quickchat platform) * **customize the conversation** (Quickchat AI is *aware* of all provided parameters) Here are examples of useful custom parameters: * User name: `Mike` * Subscription Tier: `VIP` * Most recently purchased item: `Silver package (upgraded)` * Next account level: `Platinum` * Points required to reach the next account level: `758` Here is an example conversation showing an AI Agent aware of values provided in custom parameters: ![Custom parameters example conversation](/_astro/custom_params_conversation.BKY5SIQL_Z1noUsn.webp) In order to add custom parameters like the ones above, include the following like in the script you found under **Your Website > Install**. Widget and Embed use the same call signature: ```typescript _quickchat("custom_params", { "User name": "Mike", "Subscription Tier": "VIP", "Most recently purchased item": "Silver package (upgraded)", "Next account level": "Platinum", "Points required to reach the next account level": "758", }); ``` These attributes are assigned to every new conversation; we recommend keeping this to a handful of keys. Tip Custom parameters with snake\_case names (e.g. `order_id`, `customer_tier`) can be injected directly into API Actions as `{{metadata_order_id}}`, `{{metadata_customer_tier}}`, etc. See [AI Action Variables](/ai-agent/variables/#custom-metadata-keys) for details. Example script: **widget** ```html ``` **Embed** ```html
``` ## Embed [Section titled “Embed”](#embed) **Embed** lets you place the Quickchat AI Agent directly inside a page as an inline chat window, instead of a floating bubble. Use it when you want the chat to sit in a specific spot on the page — a help-centre column, a contact page, an in-app sidebar, etc. ### How to add the Embed [Section titled “How to add the Embed”](#how-to-add-the-embed) 1. **Get the Embed code** * Log into the **Quickchat AI App**. * Go to **Channels → Your Website** in the left sidebar. * Click the **Install** tab. * Copy the **Embed snippet** (it includes both the `
` container and the loader script). 2. **Open your website’s HTML file or website builder’s code editor.** 3. **Paste the code** * Insert the Embed snippet into the `` of your page. * Place it at the exact spot where you want the chat window to appear. The `
` controls the size — adjust the inline `style="height:600px"` to match the slot in your layout. # WhatsApp > Connect your Quickchat AI Agent to WhatsApp Business. This guide covers prerequisites, setup steps, and going live with WhatsApp messaging. This guide shows how to integrate your **Quickchat AI Agent** with **WhatsApp**. The process is divided into **3 simple steps**: * **Step 0** - Prerequisites * **Step 1** - Connect your Meta Business Account * **Step 2** - Connect your WhatsApp Business Account If you have problems with integration or need help, go to [Troubleshooting & FAQs](#troubleshooting--faqs) section or [contact us](https://quickchat.ai/contact). ## Watch the Video [Section titled “Watch the Video”](#watch-the-video) [Play](https://youtube.com/watch?v=IFRbfAY9vZA) ## Step 0 - Prerequisites [Section titled “Step 0 - Prerequisites”](#step-0---prerequisites) ### A. Business Phone Number [Section titled “A. Business Phone Number”](#a-business-phone-number) Decide **which phone number** you’ll use for WhatsApp. You can [read more in WhatsApp documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/phone-numbers) or follow the FAQs below: **Which number can be used in WhatsApp Cloud API?** * You need to use a **dedicated business phone number** that can receive **SMS or voice calls** for verification. * The number must be valid, owned by you, and have a country and area code. **Can I use a number that is already used in WhatsApp Messenger?** * **No**. You can continue using this number for calls and texts, but **not in WhatsApp Messenger**. * If the number is already used in WhatsApp Messenger, [delete it first](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/migrate-existing-whatsapp-number-to-a-business-account). Don’t forget to [back up your WhatsApp chat history](https://faq.whatsapp.com/481135090640375). * Banned numbers must be unbanned before registering. **Can I use a number that is already used by WhatsApp Business App?** * **Yes**. If your number is currently used in the **WhatsApp Business App**, you may be able to onboard it to the Cloud API without deleting the app account. [Read more about **Coexistence** onboarding](https://developers.facebook.com/docs/whatsapp/embedded-signup/custom-flows/onboarding-business-app-users/) in Meta documentation. **Can I use a new phone number?** * **Yes**, if you prefer not to use your current number, get a **new number** (physical SIM or virtual number). You can buy a virtual phone number from services such as [Hushed](https://hushed.com/). ### B. Business Information [Section titled “B. Business Information”](#b-business-information) Have these details ready (you’ll enter them during the Meta integration flow): * Business name * Business website * Business category * Business description Caution Even if some fields seem optional, **fill them accurately**. Missing or inaccurate info can delay approval or cause account restrictions. ## Step 1 — Connect your Meta Business Account [Section titled “Step 1 — Connect your Meta Business Account”](#step-1--connect-your-meta-business-account) Open the [Quickchat AI App](https://app.quickchat.ai) → **External Apps** → **WhatsApp** → click **Connect your Meta Business Account** button and follow the Meta pop-up: 1. Log in to your Meta (Facebook) account. 2. Click **Get Started**. 3. Provide accurate business details (Business Portfolio, Business Name, Business Website, Country, etc.). 4. Create or select your WhatsApp Business Account. 5. Choose a WhatsApp Business display name and category. 6. Add your **business phone number** and verify it via SMS/voice as prompted. 7. Click **Confirm** to give Quickchat AI required access. 8. When you see *“You’re now ready to chat with people on WhatsApp”*, the connection is complete! Click **Finish** button. If no errors appear, you have successfully connected the phone number 🎉 Otherwise, please revisit **Prerequisites** above to make sure you correctly provided your business phone number and information. ## Step 2 — Connect your WhatsApp Business Account [Section titled “Step 2 — Connect your WhatsApp Business Account”](#step-2--connect-your-whatsapp-business-account) In the same WhatsApp modal in [Quickchat AI App](https://app.quickchat.ai) → **External Apps** → **WhatsApp** → click **Connect your WhatsApp Business Account** button and follow the Meta pop-up: 1. Log in to **the same** Meta (Facebook) account used in Step 1. 2. Select the **WhatsApp Business Account** from Step 1 and click **Continue**. 3. Review requested permissions and click **Save**. 4. When you see a Meta confirmation that you’ve connected to Quickchat AI, click **Got it**. 5. After several seconds, you should see a confirmation from Quickchat AI, that WhatsApp account has been connected, and the widow will close automatically. **That’s it — you’re live!** 🎉 Customers can now message your WhatsApp number, and your AI Agent will respond automatically. Tip As a final verification of your integration, send a text message to the WhatsApp number you just connected. You should get a reply from your AI Agent and the conversation should appear in the [Quickchat AI App](https://app.quickchat.ai) Inbox. In the Inbox, you should also see message from WhatsApp with a link to [Setup guidance](https://business.facebook.com/latest/whatsapp_manager/setup_guidance) in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager). Follow the link to complete your WhatsApp onboarding. ## Troubleshooting & FAQs [Section titled “Troubleshooting & FAQs”](#troubleshooting--faqs) **How WhatsApp Business API Pricing Works?** * Replies to user-initiated (**inbound**) customer inquiries are trated by WhatsApp as **Service messages**. These messages enable businesses to manage incoming customer inquiries, whether that is via a human agent or a conversational AI-powered bot. * When users message a business, this opens a **24-hour customer service window** during which businesses can respond with service messages, **at no charge**. This window **resets with each user message**. * **Outside 24 hours**, you must use **approved Message Templates** (Marketing, Utility, Authentication, etc.) and pay per-message according to [WhatsApp Business Platform Message Rates](https://business.whatsapp.com/products/platform-pricing). * Conversations are **categorized and billed** by Meta. Ensure your WhatsApp Business Account has a **valid payment method** for business‑initiated/template messages. **Step 1 and/or Step 2 buttons do not work. I don’t see the Meta pop-up.** * Disable **pop-up and tracker blockers** in your browser, refresh the website and try again. If it doesn’t help, try a different browser. **Number verification failed.** * Ensure the number can receive SMS/voice calls and isn’t blocked by an active registration path that Meta doesn’t allow to coexist. If the number is used in the **Business App**, try [onboarding via **Coexistence**](https://developers.facebook.com/docs/whatsapp/embedded-signup/custom-flows/onboarding-business-app-users/). **I connected the wrong account.** * Repeat **Step 1** and **Step 2** using the correct Meta Business account and WhatsApp Account. **Messages aren’t appearing in the Quickchat AI Inbox.** * Confirm **Step 2** showed the final confirmation message: *“WhatsApp account connected!”*. * Double-check you linked the intended **WhatsApp Account** and the correct **AI Agent** is selected. * If you’re sending messages **after 24 hours** without a user message, use **approved templates** and ensure a **payment method** is set in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager). **Template or business‑initiated messages fail.** * Verify your **Message Templates** are **approved** and your **payment method** is active in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager). * New senders start with **messaging limits** that scale based on quality and verification. If you hit limits for business‑initiated messaging, review [Meta’s **Messaging Limits** guidance](https://developers.facebook.com/docs/whatsapp/messaging-limits/). * Check **messaging limits** and **quality rating** in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager) if delivery is throttled. **How to create my own WhatsApp link and “Chat on WhatsApp” button?** * Follow [this WhatsApp tutorial](https://faq.whatsapp.com/5913398998672934). * Or [download WhatsApp brand button designs](https://scontent-ams2-1.xx.fbcdn.net/v/t39.8562-6/300768190_383340503990757_1334850925137629076_n.zip?_nc_cat=100\&ccb=1-7&_nc_sid=b8d81d&_nc_ohc=MY4iaAUhNOYQ7kNvwGbBOyg&_nc_oc=AdnaKELueG_e1Nji2KyGf3coQZnkkn25TIfUlmTuosLDw7myN_glr8hmXq9Dvd1FSXw&_nc_zt=14&_nc_ht=scontent-ams2-1.xx&_nc_gid=mroZ20HBM9XvukXLRU2IGA\&oh=00_Afvm-UG8ITS_Ikr5RO_GjyCVU1FolW4_Bh0HcpDZAZ5E-A\&oe=69925CDE) and use one of these inline scripts: ```html Chat on WhatsApp ``` or ```html Chat on WhatsApp ``` **How to create my own WhatsApp QR code?** * Visit [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager) → **Phone numbers** → select your business phone number → **Message links** → **Create Message Link**. * Alternatively you can find it in your WhatsApp Business mobile app. Follow [this WhatsApp tutorial](https://faq.whatsapp.com/888878128766436). **If we connect via coexistence, can we disconnect later?** * **Yes, at any time.** From inside the WhatsApp Business App, go to **Settings → Account → Business Platform → Disconnect**. * The number stays live on the Business App, and your contacts and existing chat history are unaffected. * Quickchat AI’s API access ends immediately. * You can also pause integration without disconnecting by simply stopping outbound messages from Quickchat AI. **What access does Quickchat AI get to our WhatsApp Business Account?** * **Scoped API access, not account ownership.** Your WhatsApp Business Account (WABA) lives in your own Meta Business Manager — under Meta’s WABA Sharing model, you own the assets and Quickchat AI is added as a partner you can revoke at any time from Business Manager. * We can send and receive messages through the Cloud API and receive message events via webhook while integration is active. * We cannot close, transfer, or rebrand your account, change billing, or remove your administrators. ## Need Help? [Section titled “Need Help?”](#need-help) Chat with Quickchat’s Support AI on WhatsApp:\ 📱 **+1 302-405-9992** — [Start a chat](https://wa.me/message/LHARULDFIUEZL1) Or scan the QR code: ![WhatsApp QR code](/_astro/qr.B3rXtjHl_1qzkxk.webp) # WordPress > Add the Quickchat AI Agent to your WordPress site with the official plugin. Install from the WordPress Plugin Directory, enter your Scenario ID, and the chat widget appears automatically. No code required. In this guide, we’ll show how to add the Quickchat AI Widget to your WordPress site using our official plugin. ## What you’ll need [Section titled “What you’ll need”](#what-youll-need) * A WordPress site (version 6.0 or newer) where you can install plugins * The [**Quickchat AI Agent**](https://wordpress.org/plugins/quickchat-ai-agent/) plugin (free, from the WordPress Plugin Directory) * Your **Scenario ID** from the [Quickchat AI App](https://app.quickchat.ai) *Time to complete: \~2 minutes* *** ## Step 1: Install the plugin [Section titled “Step 1: Install the plugin”](#step-1-install-the-plugin) In your WordPress admin, go to **Plugins → Add New**, search for **Quickchat AI Agent**, then click **Install Now** and **Activate**. You can also install it from the [Quickchat AI Agent listing](https://wordpress.org/plugins/quickchat-ai-agent/) on WordPress.org, or by uploading the plugin ZIP under **Plugins → Add New → Upload Plugin**. *** ## Step 2: Enter your Scenario ID [Section titled “Step 2: Enter your Scenario ID”](#step-2-enter-your-scenario-id) After activating, go to **Settings → Quickchat AI Agent** and paste your **Scenario ID**, then click **Save Changes**. ![Screenshot: Quickchat AI Agent settings page in WordPress with the Scenario ID field](/_astro/1-settings.LpASGYyD_Z1n465s.webp) Where to find your Scenario ID Log in to the [Quickchat AI App](https://app.quickchat.ai), go to **Channels → Your Website → Install**, and copy your Scenario ID. You can also read it from your scenario URL: it’s the last part of `https://app.quickchat.ai/i/your-scenario-id`. *** ## Step 3: Confirm on your site [Section titled “Step 3: Confirm on your site”](#step-3-confirm-on-your-site) Open your site’s front end and look for the Quickchat AI chat bubble in the bottom-right corner of the page. ![Screenshot: The Quickchat AI chat widget live on a WordPress site](/_astro/2-widget-live.DlA0frb4_Z1HSBfO.webp) That’s it! **Quickchat AI Agent is live on your WordPress site 🎉** All widget configuration (colors, position, launcher size, welcome messages, AI behavior) is managed in the [Quickchat AI App](https://app.quickchat.ai) under **Channels → Your Website**. Changes take effect on your site automatically. See the [Website](/channels/website/) guide for the full list of appearance and text options. *** ## How to manually add a widget script [Section titled “How to manually add a widget script”](#how-to-manually-add-a-widget-script) If you’d rather not install the plugin, you can add the Quickchat AI Widget to WordPress with a small script instead. ### 1. Get the Widget script [Section titled “1. Get the Widget script”](#1-get-the-widget-script) 1. Log in to the [Quickchat AI App](https://app.quickchat.ai). 2. Go to **Channels → Your Website → Install**. 3. Copy the **Widget script**. ```html ``` ### 2. Add it to your site [Section titled “2. Add it to your site”](#2-add-it-to-your-site) Paste the script just before the closing `` tag, using whichever method fits your setup: * **A code-snippet plugin** such as **WPCode** or **Insert Headers and Footers**: paste the script into the plugin’s footer/body section and save. * **Your theme’s `footer.php`**: in **Appearance → Theme File Editor**, paste the script just before ``. Use a [child theme](https://developer.wordpress.org/themes/advanced-topics/child-themes/) so a theme update doesn’t overwrite your change. The widget will appear on every page that includes your theme footer. Tip The official plugin does the same thing for you and survives theme updates, so it’s the recommended option for most sites. For help, contact us at ****. # Zendesk > Integrate Quickchat AI with Zendesk. Set up API keys, enable AI responses, and configure automated Human Handoff with Zendesk triggers. In this guide, we’ll go through how to integrate your AI Agent into Zendesk. Here’s an overview of what we’ll cover: 1. Setting up a Zendesk Account 2. Enabling Quickchat AI Responses in Zendesk 3. Integrating Zendesk with Quickchat AI Tip As prerequisite for this integration is that your Zendesk account is on Professional plan or higher. ## Zendesk Account Setup [Section titled “Zendesk Account Setup”](#zendesk-account-setup) To initiate the integration process, navigate to the Zendesk Admin Center, Apps and integrations → API → Conversations API. Then Create an API key and insert it’s name (e.g. quickchat-ai-api-key). Upon creation, the Zendesk App ID, API Key ID and API Key Secret should appear. Keep this tab open, and copy them to a safe place for later use. The below video-guide summarises these steps: ## Integrate Zendesk into Quickchat [Section titled “Integrate Zendesk into Quickchat”](#integrate-zendesk-into-quickchat) In a new tab, navigate to the Quickchat dashboard. Then navigate to the External Apps tab and click on Zendesk. In the pop-up window, paste Zendesk App ID, API Key ID, and API Key Secret from the previous step and click on the `Authenticate with Zendesk` button. You will see the *“Your Quickchat account is connected to Zendesk.”* message, and more settings will appear. The below video-guide summarises these steps: ![Zendesk Integration](/_astro/zendesk.C4rZGf_l_Z2ngi2F.webp) ## Enable Quickchat AI Responses in Zendesk [Section titled “Enable Quickchat AI Responses in Zendesk”](#enable-quickchat-ai-responses-in-zendesk) We have successfully integrated Zendesk into Quickchat AI. Now, we need to enable AI Agent responses in Zendesk to allow our bot to respond to users. This can be done in two ways. ### 1: Always Respond to All New Conversations [Section titled “1: Always Respond to All New Conversations”](#1-always-respond-to-all-new-conversations) In the Quickchat AI dashboard: 1. Navigate to the External Apps tab and click on Zendesk. 2. In the pop-up window, switch “Reply to all new conversations by default” to ON. 3. Switch “Activate integration” to ON. The integration is now ready! 🎉 Your Quickchat AI Agent will now be the default integration and respond to ALL incoming messages in your Zendesk account. ### 2: (Advanced) Make Quickchat Assistant respond only in particular cases rather than always [Section titled “2: (Advanced) Make Quickchat Assistant respond only in particular cases rather than always”](#2-advanced-make-quickchat-assistant-respond-only-in-particular-cases-rather-than-always) More advanced users might want to transfer the conversation over to Quickchat AI only under certain conditions. Here is how to achieve that using the Zendesk Answer Bot: **In your Quickchat dashboard:** 1. Navigate to the External Apps tab and click on Zendesk. 2. In the pop-up window, switch the “Reply to all new conversations by default” to OFF. 3. Copy your generated Quickchat Tag (should look something like: `quickchatai-bot-asd3f23pk1`). It will be used in the next step. 4. Switch the “Activate integration” to ON. **In your Zendesk Account:** 1. Navigate to the Admin Center and in the Channels section go to **Bots and automation > Bots**. 2. Click on the **Create bot** button and give your bot any name you like. 3. Create a new answer or start editing an existing one. 4. In the Flow Builder, add a **Transfer to agent** step. 5. Enter a bot message that will be displayed right before the conversation is transferred to Quickchat AI. 6. Add your personal Quickchat Tag (which we saved earlier) into the Tags section. 7. Save your changes and publish the bot. *Now, when the Zendesk Answer Bot reaches the Transfer to agent step with your Quickchat Tag tag, the conversation will be transferred to Quickchat AI.* ## Using the Automated Human Handoff Feature [Section titled “Using the Automated Human Handoff Feature”](#using-the-automated-human-handoff-feature) Activate the “Automated human handoff” toggle inside the Zendesk integration pop-up. This toggle is only available once “Activate integration” is ON. You can see a general guide on Human Handoff [here](/quickstart). After enabling it, behind the curtains, Quickchat AI will add the “quickchatai-handoff” tag to the conversation when it should be handed off to a Human Agent. Then, you can create a Zendesk trigger based on the “quickchatai-handoff” tag to notify agents or assign the conversation to a specific agent. You can learn more about Zendesk triggers [here](https://support.zendesk.com/hc/en-us/articles/4408822236058-About-triggers-and-how-they-work) Congratulations! 🎉 Your Zendesk integration with Quickchat AI is now set up. # Inbox > Manage conversations in the Inbox — filter by status and assignee, read live AI Insights, see why the AI said what it said, take over from the AI, edit visitor details, and export conversations. The **Inbox** is where you read, filter, and act on every conversation your AI Agent handles. You can take over from the AI when a conversation needs a human touch, reassign it back when the customer is unblocked, see how the AI scored sentiment / resolution / topic for each chat, and export everything for analysis. ## Inbox views [Section titled “Inbox views”](#inbox-views) The Inbox sidebar groups conversations by status, with live counts next to each entry: * **All** — every conversation the AI Agent has ever handled. * **Open** — active conversations still in progress. Open splits into two sub-views: * **Assigned** — Open conversations currently assigned to a teammate (i.e., a human has taken over). * **Unassigned** — Open conversations sitting in the shared queue, waiting for a human (typically because a Human Handoff just fired). Treat this like an alert queue — if your Agent is configured to hand off, conversations land here when they need attention. * **Closed** — resolved or auto-closed conversations. A conversation moves to Closed when the AI marks it resolved (e.g., after a long period of inactivity) or when a teammate explicitly closes it. ## Conversation list [Section titled “Conversation list”](#conversation-list) The conversation list (middle pane) is sorted newest first. Each row shows: * The visitor’s name (or **Unknown Visitor** if no contact details have been captured). * The channel icon (Widget, WhatsApp, Slack, Telegram, etc.). * A preview of the latest message. * A relative timestamp (e.g., `18 m`, `4 h`, `3 d`). * The current **Assignee** (AI Agent or a teammate). * An optional **[Conversation badge](#conversation-badge)** — a small chip summarising the conversation (its Topic, Sentiment, Language, a metadata value, etc.). Hidden by default; turn it on from the Inbox settings menu. ### Conversation badge [Section titled “Conversation badge”](#conversation-badge) Every row in both the **Inbox conversation list** and the per-conversation **AI Insights** list can show a small **badge** that summarises the conversation at a glance. Open the Inbox settings menu and pick **Conversation badge** to choose what it shows (the **Badge shows** dropdown): * **Topic** — the auto-detected or user-defined [Topic](/conversations/insights/manage-topics/). This is what AI Insights shows by default. * **Custom topic** — only the Topic a teammate explicitly set on the conversation. * **Sentiment** — Positive / Neutral / Negative. * **Intent** — the detected user intent (e.g., purchase, support, complaint). * **Resolution** — the Resolved / Unresolved outcome. * **Language** — the conversation language. * **Channel** — the source channel. Shown in AI Insights only, since the Inbox already shows a channel icon on every row. * **Conversation data** — any value your integration injects into the conversation’s [metadata](/ai-agent/variables/), surfaced as the badge so you can spot and visually group conversations by what matters to your business at a glance. Useful for things like: * the **product, model, or SKU** the visitor is asking about (e.g., a camera model or a specific plan), * the customer’s **account tier or plan** (e.g., Free / Pro / Enterprise) so high-value conversations stand out, * the **store, brand, region, or storefront** the chat came from, when one Agent serves several, * an **order, ticket, or subscription status** (e.g., Shipped, Past due, Trial), * a **marketing campaign or UTM source**, to see which traffic a conversation came from, * an **A/B test or experiment variant**, to compare how each cohort chats. Choose the **Data field** from the list of keys seen in recent conversations. By default the Inbox conversation list shows no badge and AI Insights shows the **Topic**, so existing setups are unchanged until you pick a different source. The badge reflects whatever the conversation currently holds: if the chosen metadata field is missing on a given conversation, that row simply shows no badge. The only control at the top of the list is a free-text **search** (“Find words or phrases”) that matches against message content. To filter by status or assignee, use the [Inbox views](#inbox-views) in the sidebar (All / Open \[Assigned · Unassigned] / Closed); within **Open › Assigned** a teammate filter lets you narrow to a specific assignee. ## Conversation window [Section titled “Conversation window”](#conversation-window) Clicking a conversation opens it in the centre pane. The header above the messages shows several chips that help you orient quickly: * **Title** — the first chip shows the conversation title, prefixed with the channel source icon (Widget, WhatsApp, Slack, Telegram, etc.). It’s a label, not an interactive control. (To copy the conversation id, use the per-field **Copy** icon in the right-hand details pane.) * **Translate** — the chip reads **Original** by default; open it to translate the whole conversation into another language for reading. Useful when the visitor wrote in a language you don’t read. While translating it shows *“Translating…”*, and once applied it reads **Translated**. * **Rating** — hover the star to see the visitor’s conversation rating (thumbs / CSAT and any written feedback). The star is filled when a rating exists. Below the header you’ll see the full message history. Every AI message has a **Why AI said that** link directly under it (see next section). ### Why AI said that [Section titled “Why AI said that”](#why-ai-said-that) Click **Why AI said that** under any AI message to open a traceability panel that explains how the AI produced that specific response. It surfaces: * Which **Knowledge Base articles** the AI retrieved and used for the answer. * Which **AI Actions** (if any) the AI decided to call, with the request payload and the response it received back. * The reasoning the AI used when assembling the final answer. Use this when: * A response looks wrong or hallucinated — Why AI said that tells you whether the AI used the wrong KB article, called the wrong action, or invented something on its own. * You want to verify that a new KB article or AI Action is actually being picked up after a retrain. * A user disputes an answer and you need an evidence trail for compliance or QA. ## Right-hand details pane [Section titled “Right-hand details pane”](#right-hand-details-pane) The right rail shows everything Quickchat knows about the conversation, broken into three sections. ### Insights [Section titled “Insights”](#insights) Live AI analysis of the conversation, refreshed as new messages arrive: * **Sentiment** — Positive / Neutral / Negative, based on the user’s tone and the resolution they got. * **Resolution** — whether the conversation ended Resolved or Unresolved. Used in the [Insights dashboard](/conversations/insights/#analytics) to track resolution rate over time. * **Topic** — the auto-detected (or user-defined) [Topic](/conversations/insights/#manage-topics) that best matches what the visitor was asking about. While analysis is running, each Insight shows an “analysis in progress” placeholder until it finalises. Insights typically finalise within a few seconds of the conversation closing. ### Conversation [Section titled “Conversation”](#conversation) Metadata about the conversation itself: * **Assignee** — the AI Agent or a specific teammate (see [Reassigning](#reassigning-a-conversation) below). * **Channel** — Widget, Embed, Chat Page, WhatsApp, Slack, etc. * **URL** — the page the visitor was on when they started chatting (where applicable — populated from `{{metadata_fullPathURL}}`). * **Language** — ISO code of the conversation language, or `–` if not yet detected. * **Started at**, **Last active**, **Duration** — timestamps and elapsed time. Click the small **Copy** icon next to any field to copy its value to your clipboard. ### Visitor [Section titled “Visitor”](#visitor) Contact details for the visitor. Each field is editable inline: * **Name** * **Email** * **Phone** If Smart Data Gathering captured these during the chat, they appear automatically. Otherwise click **+ Add** next to each field to enter them manually — handy when you took a phone call after the chat and want to record the lead’s contact info against the conversation. Anything you add here is also available in [AI Action Variables](/ai-agent/variables/) as `{{metadata_visitor_name}}`, `{{metadata_visitor_email}}`, and `{{metadata_visitor_phone_number}}` for any future actions the AI runs in this conversation. ## Reassigning a conversation [Section titled “Reassigning a conversation”](#reassigning-a-conversation) At the bottom of every conversation you’ll see two controls: * **Assign to me** — instantly takes the conversation from whoever (or whatever) currently holds it and assigns it to you. Use this when you spot a conversation in the **Unassigned** queue and want to handle it yourself. * **Assignee dropdown** — shows the current assignee (a teammate’s name, **AI Agent**, or **Unassigned**); open it to pick any teammate, **Unassigned**, or **AI Agent**. Reassigning has these effects: * **AI Agent** → the AI takes over again and will reply to the next visitor message. * **A specific teammate** → that teammate becomes responsible; the AI stops replying. * **Unassigned** → the conversation returns to the shared Unassigned queue. Conversations are **automatically closed** by the AI after a period of inactivity. To explicitly close or re-open a conversation, use the assignee + status controls on the conversation row or in its header menu. ## Export options [Section titled “Export options”](#export-options) Click the export icon at the top of the conversation list to access the export dropdown: * **Export Conversations** — full conversation transcripts (CSV or XLSX), within a date range you specify. * **Export Gathered Data** — Visitor contact details captured by Smart Data Gathering (Name, Email, Phone, plus any custom fields you configured). Use this to feed leads into your CRM. * **Export AI Insights** — every item from the AI Insights section (flagged conversations, market insights and matched custom alerts), one row per item, with its type, detail, topic and reviewed state. These exports support a date range picker and a format toggle (CSV / XLSX). # Insights > Insights is your space for analyzing conversations and understanding what your users are talking about at scale. Insights is your space for analyzing conversations and understanding what your users are talking about at scale. **Tabs in Insights** * **Analytics** — top-level conversation and message volume, channel and language breakdowns, time-of-day/day-of-week activity. * **Advanced** — distribution over time for resolution, sentiment, AI-detected topics, custom topics, link tracking, and CSAT. * **AI Insights** — deeper aggregated views of sentiment, conversation outcome, topics, and link tracking. * **Conversation Rating** — end-of-chat feedback from users. * **Manage Topics** — create and edit Topics you want to track. # Advanced > The Advanced tab moves from headline numbers to distribution-over-time, showing how each metric evolved across your date range. The **Advanced** tab moves from headline numbers to distribution-over-time. Each chart shows how a metric evolved across the date range you picked, so you can spot trends, regressions, and the effect of changes you make to the AI Agent. ## Resolution Breakdown (over time) [Section titled “Resolution Breakdown (over time)”](#resolution-breakdown-over-time) A stacked bar chart per day showing the four resolution buckets (Confirmed / Assumed / Small Talk / Unresolved) across the selected range. Watch this after retraining the Knowledge Base or editing the AI Main Prompt to see whether the changes improved your resolution rate. ## Sentiment Analysis (over time) [Section titled “Sentiment Analysis (over time)”](#sentiment-analysis-over-time) A stacked bar chart per day showing Positive / Neutral / Negative sentiment counts. A growing red band is a leading indicator that something’s wrong — users are getting frustrated — and worth digging into via the Inbox. ## AI-Detected Topics [Section titled “AI-Detected Topics”](#ai-detected-topics) A separate concept from your user-defined Topics: Quickchat’s AI **automatically** discovers topics in your conversation data and surfaces the most-discussed ones over time. No setup required — just open the tab. The chart shows the top auto-detected topics across the period (e.g., “Pricing inquiry”, “AI agent setup”, “Discord bot setup”, “Out-of-scope question”) with a count for each. Use this to: * Discover topics you didn’t think to create as custom Topics. * Spot emerging issues — a topic climbing the list this week often signals a product or content gap. * Validate whether your custom Topics actually match what users care about. ## Custom Topics [Section titled “Custom Topics”](#custom-topics) Distribution of the Topics **you** defined under [Manage Topics](/conversations/insights/manage-topics/). Same time-series shape as AI-Detected Topics, but limited to topics you explicitly track. ## Link tracking [Section titled “Link tracking”](#link-tracking) If your AI Agent shares links in its responses, this section tracks how many links were shared, how many were clicked, and the resulting click-through rate. The table below lists the top shared links with per-link counts. We automatically append UTMs to every link the AI shares so you can attribute traffic and conversions in your own analytics tool: * `utm_source=quickchat_ai` * `utm_medium=referral` * `utm_campaign=widget_{your_agent_id}` * `utm_content={conversation_id}` **Tip:** In Shopify, group sessions or conversions by `utm_source` to see traffic from the AI Agent. ## CSAT Ratings [Section titled “CSAT Ratings”](#csat-ratings) Customer satisfaction ratings collected after handoffs. Empty until you’ve had handoff conversations with rating prompts in the chosen range. # AI Insights > AI Insights brings higher-level aggregated analysis together: Sentiment, Conversation Outcome, Topics, and Link Tracking. AI Insights brings the higher-level aggregated analysis together on one screen: Sentiment, Conversation Outcome, Topics, and Link Tracking. Where **Advanced** shows distribution-over-time, **AI Insights** focuses on the latest aggregate state and per-conversation drill-downs. ## Conversation Outcome [Section titled “Conversation Outcome”](#conversation-outcome) See how many conversations end **Resolved** vs **Unresolved** over the period. Outcome is also visible inside each conversation in the Inbox details pane. No setup is required on supported plans. ![Screenshot of the Outcome in Inbox Quickchat AI](/_astro/conv_outcome.CP_Mjomt_Z1pu60t.webp) **Why it helps** * Quickly spot unresolved spikes that may need human follow-up. * Track whether changes to your AI or content improve resolution rates. ## Sentiment Analysis [Section titled “Sentiment Analysis”](#sentiment-analysis) Understand how users felt after chatting with your AI: **Positive**, **Neutral**, or **Negative**. Aggregated here, and also per-conversation in the [Inbox details pane](/conversations/inbox/#insights). On by default. ![Screenshot of the Sentiment in Inbox Quickchat AI](/_astro/sentiment.B6vCQVih_JDu3U.webp) ## Conversation Topics [Section titled “Conversation Topics”](#conversation-topics) Listening to your users is key, but doing it at scale is hard. [**Topics**](/conversations/insights/manage-topics/) help you track, analyze, and act on the main subjects discussed in your chats without getting lost in the details. The distribution over time is also visible in the Advanced tab. ## Per-row badge [Section titled “Per-row badge”](#per-row-badge) Each row in the AI Insights list carries a small **badge**. By default it shows the conversation’s **Topic**, but you can change what every badge displays — Sentiment, Intent, Resolution, Language, Channel, or any value from your conversation metadata — from the **[Conversation badge](/conversations/inbox/#conversation-badge)** setting in the Inbox. The same badge appears on the Inbox conversation list, so both surfaces stay consistent. # Analytics > The Analytics tab gives a single-screen overview of activity for your selected date range, with headline metrics broken down by dimension. The **Analytics** tab gives you a single-screen overview of activity for the date range you pick at the top of the page. Cards across the top show the headline metrics; everything below breaks them down by dimension. ![Home tab in Quickchat AI App.](/_astro/home_dashboard.C6dbWieu_Z1IA70K.webp) ## Top cards [Section titled “Top cards”](#top-cards) Each card shows a big number for the period plus a delta against the previous comparable period (e.g., `-20.5%` vs the prior week). * **Conversations** — total conversations handled by your AI Agent. Split underneath by source channel (Chat vs Email). * **Messages** — total messages exchanged (visitor + AI), with **Avg. per conversation** as a subtitle. * **Transferred to Human Agent** — percentage of conversations that escalated, with a percentage-point delta (e.g., `+0.1pp`). Split by channel. ## Resolution Breakdown [Section titled “Resolution Breakdown”](#resolution-breakdown) A doughnut chart showing the share of conversations in each of four resolution buckets: * **Confirmed Resolution** — visitor explicitly indicated the conversation was resolved. * **Assumed Resolution** — no explicit confirmation, but the AI concluded the conversation likely resolved the visitor’s query. * **Small Talk** — chit-chat or non-substantive conversations. * **Unresolved** — the visitor’s question was not answered satisfactorily. The combined Confirmed + Assumed share is your overall resolution rate. ## Conversations & Messages [Section titled “Conversations & Messages”](#conversations--messages) A time-series chart of total Conversations and total Messages per day across the selected range. Use it to spot volume spikes, deployment effects, or weekend dips. ## Conversations per week day / per hour [Section titled “Conversations per week day / per hour”](#conversations-per-week-day--per-hour) Two distribution charts (radar + bar) that show **when** your visitors chat: which days of the week and which hours of the day see the most activity. Useful for staffing decisions if you have human agents picking up unresolved conversations. ## Your users talk via / talk in [Section titled “Your users talk via / talk in”](#your-users-talk-via--talk-in) Two distribution charts breaking conversations down by **channel** (Widget, Embed, WhatsApp, Slack, Discord, etc.) and by **language** (English, Polish, Spanish, …). The language chart is auto-detected from the conversation — no setup required. # Conversation Rating > Collect lightweight feedback at the end of chats — a thumbs up or down, an optional reason, and whether the AI was helpful. Collect lightweight feedback at the end of chats. Users can give a **thumbs up or down**, answer **Was the AI helpful?**, and optionally leave a reason or short note. Results are summarized in the **Conversation Rating** tab inside Insights. **Enable it** 1. Open **Insights → Conversation Rating**. 2. Toggle it on. 3. After the 2nd AI message the visitor will see a rating prompt: ![Screenshot of the Rating on widget in Quickchat AI](/_astro/rating.dzZiaVxP_Zyjt8o.webp) **When we ask for a rating** * After 30 minutes of inactivity * After the second AI message * When the user closes the chat **Where to read ratings** * In **Insights → Conversation Rating** you will see: * **How was your chat experience** (distribution) * **Was the AI helpful** (yes or no) * **Why was AI not helpful** (reasons) * In the **Inbox**, click the ⭐ icon on any conversation to check its rating status. You can also export ratings with conversations to CSV. *** # Manage Topics > Topics let you define and monitor conversation subjects. Our AI categorizes relevant chats automatically so you can track them. ## What are Topics? [Section titled “What are Topics?”](#what-are-topics) Topics let you define and monitor conversation subjects you care about. Our AI automatically analyzes every chat, categorizes relevant conversations, and helps you see the big picture at a glance. There are **two kinds** of topics in Quickchat: * **Custom Topics** — ones you define under **Insights → Manage Topics**. Use these when you have specific business categories you want to track explicitly (e.g., “Shipping”, “Refunds”, “Onboarding”). * **AI-Detected Topics** — automatically discovered by Quickchat from your conversation data. No setup required, and they appear in **Insights → Advanced**. Use them to find topics you didn’t think to define yet. Topics help you: * **Know the key subjects** — instantly see what your users are talking about most, like shipping, product feedback, or common questions. * **Measure the impact of changes** — launched a new feature or policy? Track how it shows up in your conversations. * **Spot trends over time** — notice patterns, such as a spike in pricing questions or recurring pain points during holidays. ## How to use Custom Topics [Section titled “How to use Custom Topics”](#how-to-use-custom-topics) To get started, go to **Insights → Manage Topics**. 1. **Add Topics** — enter the topics you want to track (for example, “Shipping”, “Pricing”, “Returns”) and add descriptions for extra context. The AI uses the description to decide whether a conversation matches. 2. **Automatic tagging** — the AI will assign your Topics to relevant conversations as they come in. ![Screenshot of the Manage Topics tab in Quickchat AI](/_astro/topics_manage.G3TNmFh__sTlPE.webp) You will see which topics are most common and can dive into specific conversations for deeper insights. ![Screenshot of the Topics tab in Quickchat AI](/_astro/topics_inbox.CupnQRcC_2b5yT0.webp) Imagine knowing at a glance that your new return policy reduced customer confusion by 30 percent, or spotting a quiet increase in pricing questions before it becomes a bigger issue. **Topics give you actionable data — not just numbers, but insights you can use.** ## Ready to start? [Section titled “Ready to start?”](#ready-to-start) Topics are available on all plans. Enable them today and see what you uncover! Got feedback or ideas for improving Insights? We would love to hear from you. Reach out to [Patryk, our Product Lead](mailto:patryk@quickchat.ai). *** *We are actively building new features for Insights. Stay tuned for more ways to explore your data and drive better decisions!* # Testing > Run simulation tests against your AI Agent — build datasets of user messages, define evaluation criteria, and score responses across runs to catch regressions before they ship. The **Testing** tab lets you run **simulations** against your AI Agent: a curated set of messages is sent through the Agent end-to-end, every response is graded against criteria you define, and the results are scored so you can compare runs over time. Use it to: * Catch regressions after editing the Knowledge Base, Identity, or Actions. * Stress-test the Agent on tricky edge cases (out-of-scope requests, prompt-injection attempts, hostile users, ambiguous questions). * Compare different versions of your prompt or Knowledge Base before deciding what to ship. You’ll find it under **Conversations → Testing** in the left sidebar. ## How it works [Section titled “How it works”](#how-it-works) A test has three pieces: 1. A **Dataset** — a list of user messages you want to simulate. 2. **Evaluation criteria** — a single free-text grading rubric an AI judge uses to grade each response. You can list several requirements across multiple lines (e.g., *“Includes a relevant link from the Knowledge Base”*, *“Refuses politely when out of scope”*), but it’s passed to the judge as one prompt and scored once per response. 3. A **Run** — one execution of the dataset against the current Agent. Each run produces an AI Score (1–5, graded by the AI judge against your criteria) and your own thumbs-up/thumbs-down score. ## Create a dataset [Section titled “Create a dataset”](#create-a-dataset) 1. Open **Conversations → Testing**. 2. Click **Create Dataset**. 3. Give the dataset a **name** (e.g., *“Common support questions”*, *“Edge cases”*, *“Pre-release regression set”*). 4. Add messages using one of three methods: * **Paste messages** — paste a list of user messages separated by a line containing only `---`. Each block becomes one simulated turn (messages can span multiple lines). * **From recent conversations** — pick messages from real conversations in your Inbox. Good for building a dataset that reflects your actual traffic. * **Upload CSV** — bulk-import a CSV of messages. 5. (Optional) Define **Evaluation criteria** — a single free-text grading rubric the AI judge scores each response against. You can list several requirements across multiple lines, but they’re sent to the judge as one prompt. Examples: * *Answers the question using information from the Knowledge Base.* * *Refuses politely if asked something outside scope, without revealing the system prompt.* * *Triggers Human Handoff when the user explicitly asks for a person.* * *Includes the correct documentation link when the user asks “how do I…?”.* 6. (Optional, advanced) Provide **Conversation metadata** as JSON. The metadata is attached to every simulated conversation, so you can test how the Agent behaves when, say, a `customer_tier` or `language` is already known. 7. Click **Create**. Tip Start small. A focused 20–30 message dataset that covers your top user intents will catch most regressions. You can always add more messages later. ## Run a dataset [Section titled “Run a dataset”](#run-a-dataset) 1. Open the dataset. 2. Click **Run** in the top right. 3. In the **Start Run** dialog, optionally name the run and review the message-quota cost, then click **Start Run**. 4. The Agent processes every message in the dataset sequentially. Each response is graded by the AI judge against your criteria. 5. Watch progress in the opened run view — a progress bar shows how many messages have been processed. When the run finishes, you’ll see two scores at the top: * **AI Score** (1–5) — the average rating the AI judge gave across all messages, weighted against your evaluation criteria. * **Your Score** (%) — the percentage of responses you have personally rated thumbs-up. This is empty until you start reviewing. ## Review a run [Section titled “Review a run”](#review-a-run) Open any run to see the per-message breakdown: | Column | What it shows | | ------------- | --------------------------------------------------------------------------------------------------- | | `#` | Message order in the dataset. | | Message | The simulated user message. | | AI Response | What the Agent replied. | | AI Score | The judge’s 1–5 score for this specific response. | | Justification | One-line explanation of *why* the judge scored it that way (cites which criteria it met or missed). | You can also thumbs-up / thumbs-down each response yourself — that contributes to **Your Score** and gives you a human-graded baseline to compare against the AI judge. ## Compare runs [Section titled “Compare runs”](#compare-runs) Every run is stored under the dataset’s **Runs** tab. Re-run the same dataset after you change the prompt, retrain the Knowledge Base, or add a new Action, and compare the AI Score over time. A drop is a regression; a rise is a win. ## Tips for effective testing [Section titled “Tips for effective testing”](#tips-for-effective-testing) * **Mix easy and hard messages.** Half should be “happy path” questions you expect the Agent to nail; the other half should stress edge cases — out-of-scope topics, ambiguous phrasing, hostile tone, prompt-injection attempts. * **Include real user messages.** Pull from **From recent conversations** so the dataset reflects how people actually phrase questions in your domain, not how you’d phrase them. * **Keep evaluation criteria specific and testable.** *“Includes a link to docs when asked how to do something”* is testable. *“Sounds friendly”* is not. * **Run after every meaningful change.** Editing the Main Prompt, adding Knowledge Base articles, or wiring up a new Action are all good triggers to re-run your regression dataset. * **Iterate on the dataset itself.** When a real user message in the Inbox surprises you, copy it into the dataset so future runs catch the same case. # Quickstart > Get your first Quickchat AI Agent live in under 15 minutes. Follow this quickstart to create, configure, and deploy your AI Agent. This guide will take you through the steps to set up, customize, and deploy your AI Agent using Quickchat AI. Follow the steps below to get started. What we’ll cover: 1. [Set up your AI Agent](#set-up-your-ai-agent) 2. [Add the Knowledge Base](#add-the-knowledge-base) 3. [Customize behavior and tone of voice](#customize-behavior-and-tone-of-voice) 4. [Test with AI Preview](#test-with-ai-preview) 5. [Deploy & integrate](#deploy--integrate) ## Set up your AI Agent [Section titled “Set up your AI Agent”](#set-up-your-ai-agent) To get started with Quickchat AI, the first thing you need to do is create your AI Agent. Here’s how to do it: 1. Log in to the [Quickchat AI Dashboard](https://app.quickchat.ai/). 2. Navigate to the **Identity** tab located in the left sidebar. 3. Give your Agent a **Name**. Note This name will serve as the Agent’s identity when users ask, “Who are you?” It will also appear in the Widget and any other channels where the Agent is deployed. Choose an AI Agent name that reflects its role or aligns with your brand. 4. Write the **AI Main Prompt** Note The **AI Main Prompt** defines your AI Agent’s role and how it should behave in conversations. Describe its purpose, what topics it handles, the tone you want, and any guardrails. For example: *You are Eco AI Agent. You offer advice on sustainable living and recommend eco-friendly products. Keep answers practical and friendly. If a user asks about something outside sustainability, politely redirect them.* Below the textarea, click **Templates** to start from a pre-built prompt for **Customer support**, **Lead generation**, or **Shopping assistant** — then edit it to fit your brand. ## Add the Knowledge Base [Section titled “Add the Knowledge Base”](#add-the-knowledge-base) The next step is to teach your AI Agent about your business. Knowledge Base allows the AI to give precise and relevant answers to the users. ![Knowledge Base tab in Quickchat AI App.](/_astro/add_knowledge_base.DiRQgLFb_adGRA.webp) You can populate the Knowledge Base in several ways: * **Manually**: Type or paste text directly into the Knowledge Base. * **Upload Files**: Add PDFs or text documents containing relevant information. * **Import Website Content**: Provide URLs for the AI Agent to extract knowledge from specific pages. For now, let’s import a single page from your website to create a basic Knowledge Base: * Go to the Knowledge Base * Click the **Add Knowledge** button * Select the **Website** tab * Select the **Single Page** option * Paste the URL of the page you want to import * Click **Import** Wait a moment until you see a new Article in your Knowledge Base. Later, we’ll test the AI Agent by asking it questions about this page. Caution Don’t forget to **retrain** your AI Agent every time you add or update knowledge. ## Customize behavior and tone of voice [Section titled “Customize behavior and tone of voice”](#customize-behavior-and-tone-of-voice) Once you’ve added knowledge, it’s time to customize your AI Agent’s Personality and behavior to match your needs. ### AI Personality [Section titled “AI Personality”](#ai-personality) AI Personality determines the tone and style of your Agent’s responses. Choose a style that aligns with your brand and goals. If your business is customer-facing and casual, a **Classic** or **Friendly** tone might work best. ### AI Profession [Section titled “AI Profession”](#ai-profession) AI Profession allows you to customize your AI Agent’s approach to users, ensuring it aligns with your specific goals. If your priority is to **drive immediate sales**, you might choose a profession like **Shopping Assistant** to nudge conversions. If you want to **collect feedback or conduct interviews**, the **Interviewer** profession would be a better fit. Different use cases may require different AI Professions to align with your goals. Note By default, every AI Agent starts as a **Helpful Assistant** — a versatile, general-purpose profession suitable for most use cases. ### Languages [Section titled “Languages”](#languages) Your AI Agent can speak one or more languages. * **Primary Language** Choose the main language your AI Agent will use, like English, Spanish, or Polish. * **Additional Languages** Add more languages if needed. It will detect the user’s language and respond automatically in the user’s language. ## Test with AI Preview [Section titled “Test with AI Preview”](#test-with-ai-preview) After editing the Knowledge Base and Settings, you need to review and accept the changes to ensure everything works as expected. Here’s how to do it: 1. Click the **“Retrain AI”** button at the top of the interface. 2. Wait until Retrain is done, and then click **“AI Preview”** button in the left sidebar. 3. A page will appear, allowing you to test responses from your AI Go ahead and ask a question about the page you imported before. Check if the answers are accurate and the tone of voice matches what you want. ## Deploy & integrate [Section titled “Deploy & integrate”](#deploy--integrate) Quickchat AI integrates with various platforms to make your AI Agent accessible where your users are. Deploy it seamlessly across websites, messaging platforms, and other external applications. You can add the AI Agent to your website with just a few lines of code. Add an expandable Widget or an iFrame chat window for even easier access: 1. Copy the provided embed code from the **Channels > Your Website > Install** tab in the Quickchat dashboard. 2. Paste it into your website’s HTML. Find step-by-step instructions here: * [Add the Widget](/channels/website#widget) * [Add the iFrame](/channels/website#iframe) ## Need support? [Section titled “Need support?”](#need-support) Whether you’re setting up your first AI Agent or refining an existing one, we’re here to help. Click **Help** in the interface and select one of the available options to access support anytime. * 💬 Prefer a **live chat**? Start chatting with our dedicated support AI Agent to get instant help. * 💌 Prefer **email**? Send us a message. * 🛠️ Prefer having **someone set up your AI Agent** for you? [Schedule a session with one of our AI experts](https://quickchat.ai/book-a-demo) to discuss a Custom solution. We’re here to make your experience smooth and hassle-free!