AI assistant

The AI assistant answers customers on every channel of your business, using only the knowledge you give it. It can reply on its own, suggest replies for your agents to approve, collect contact details, show products and hand the conversation to a person when it cannot help. This page explains how to set it up, how it decides what to do and how to keep its costs under control.

Before you start

You need permission to manage Support (owner, admin, or an employee with Manage access to Support).
The assistant needs an AI provider key. Ha Tang uses the platform key by default; you can add your own key instead (see Budget and API key). When no key is available, the AI assistant page shows a warning.
Add knowledge before you turn it on. With an empty knowledge base, the assistant hands every conversation to a human.

Everything lives under Support → AI assistant, in five tabs: Assistant, Knowledge, Situations, Tests and AI runs. There is one assistant per business: the same persona, instructions and knowledge serve the website widget, mobile apps, email and every connected social channel.

Step 1: Add knowledge

Open Support → AI assistant → Knowledge (also in the sidebar as Knowledge) and add sources. The assistant answers only from what is indexed here.

Source type	What to enter
FAQ (Q/A pairs)	Blocks of `Q: …` and `A: …` (or `Hỏi:` / `Đáp:`) separated by a blank line
Text / markdown	Policies, price lists, product details
Website, Google Doc / Sheet, or Notion link	A website start URL or `sitemap.xml`; a Google Doc or Sheet shared "anyone with the link"; a Notion page or database shared with your Notion integration
PDF / Word file	A PDF or DOCX up to 20 MB

How sources are processed:

Websites are crawled on the same host, following links two levels deep and up to 50 pages. The crawler honors robots.txt and your sitemaps, and skips pages marked noindex. Set Re-crawl every (days) to refresh it automatically (default 7, 0 = never).
Notion needs an integration token. Create one at notion.so/profile/integrations, paste it in Support → AI assistant → Assistant (Team budget and key), then share each page or database with the integration.
Files: text is extracted on upload. A scanned PDF is read by the AI in the background, and that cost counts toward your AI budget.
Each source shows its status (pending, indexing, indexed, error), the number of chunks and when it was last indexed. Click Re-index after changing a source outside Ha Tang.

The page header shows how many chunks are indexed and whether semantic search is on. The assistant combines keyword and semantic matches when it looks up an answer.

Unanswered questions

When the assistant hands a conversation off because the answer was not in the knowledge base, the question lands under Unanswered questions on the Knowledge tab. Similar questions are grouped and counted. Click Answer, write the right answer and Save to FAQ: it becomes a Q/A pair in an FAQ source named "Câu hỏi từ khách", and the assistant uses it from then on. Click Ignore for questions you do not want to answer.

Try it

The Chat with the AI panel on the Knowledge tab lets you write as a customer and see how the assistant answers with your current knowledge, situations and products. You can pick the channel and pretend to be inside or outside office hours. Nothing is sent to anyone, but each answer counts toward the AI budget.

Step 2: Choose a mode

Open the Assistant tab and pick a Mode:

Mode	Behavior
Off	The assistant never answers.
When nobody is online	Answers only while no agent is online; agents take over the moment they reply.
First responder	Answers every new customer first and hands off when it cannot help. The widget shows as online.
Draft only	Never talks to customers. Suggests a reply to the agent for every customer message.

Then adjust the rest of the form:

Setting	Default	Notes
Assistant name (shown to visitors)	`Trợ lý`	Up to 60 characters
Model	Platform default	Leave blank to use the default model
Max assistant replies before hand-off	6	1 to 20 per conversation
Instructions for the assistant	empty	Tone, what to push, what to avoid; up to 4,000 characters. It still answers only from the knowledge base.
Hand-off phrase (vi / en)	"Mình sẽ chuyển bạn tới nhân viên hỗ trợ ngay nhé." / "Let me connect you with a human agent."	Sent when it hands off without writing its own message
After a hand-off, keep suggesting replies to the agent	On	Drafts continue after a hand-off
Let the assistant ask for the visitor's email when a follow-up is needed	On	Shows an email form in the website widget
Save the name and phone number visitors mention	On	Also asks for a phone number when a follow-up would help

How the assistant handles a message

Flows get the first word. When no flow replies, the assistant takes its turn:

It stays silent when the conversation is closed, a human agent owns it, or an agent clicked Stop AI.
It checks your situations and applies any that match.
After the maximum number of replies, it hands off.
It looks up the most relevant knowledge and writes a reply. It can also use these actions:

Action	When
Hand off to a human	The customer asks for a person, complains, wants a refund or cancellation, has a problem with a payment, wants to change personal data, or the answer is not in the knowledge base
Save customer details	The customer mentions their name, phone number or email. It also fills custom fields marked AI fills it in (Customers → Custom fields) while they are empty.
Ask for an email	Website conversations only, when a follow-up is needed and the visitor has no email
Show products	Your catalog has products; it sends product cards
Create a draft order	Your catalog has products; it creates a draft order and leaves a private note asking an agent to confirm it and send a payment link

When the assistant hands off, it:

sends the hand-off phrase (or its own message) to the customer;
leaves a private note for agents with the reason and a short summary;
passes the conversation to the distribution rules;
sends a chat.conversation.handoff webhook event with the reason (not_in_knowledge, complaint, refund, payment, personal_data, requested, other, or a limit such as max_turns);
falls back to the offline flow when nobody on the team is online.

If the customer comes back after the conversation was resolved, the assistant starts answering again.

Suggested replies (drafts)

In Draft only mode, and after a hand-off when keep suggesting replies is on, the assistant writes a suggestion for each customer message instead of replying. The suggestion appears above the composer as AI suggestion with two buttons:

Insert puts the text in the composer so you can edit and send it.
Discard dismisses it.

Drafts are only written while at least one agent is online. When the knowledge base does not cover the question, the draft says honestly that the team will check and follow up.

In the inbox

Stop AI silences the assistant (and flows) in one conversation; Resume AI gives the conversation back to it.
Under each AI reply, Knowledge used shows the chunks it relied on. Improve this reply lets you correct the question and answer; the pair is saved to the "Câu hỏi từ khách" FAQ and used next time.

Situations

Situations teach the assistant how to handle specific cases. Open the Situations tab, click Add situation or start from a template. You can have up to 10; situations higher in the list win.

Field	Options
Starts when	The visitor talks about a topic (the AI recognizes it from your description), The message contains keywords (accents ignored), or Every message
Conditions	Office hours (any, within, outside), channels, websites
Instructions for the AI	How to reply in this situation (up to 1,000 characters)
Extra context	Facts the AI needs only here, such as wholesale prices (up to 2,000 characters)
Then	Just reply as instructed, Bring in an agent to follow along (the AI keeps replying), Hand off to an agent, Stop the AI in this conversation, Mark as spam and stop the AI
Apply at most once per conversation	On by default

tip

Keep the list short. Too many rules make the assistant rigid and harder to predict. Put general guidance in the instructions on the Assistant tab and use situations for real exceptions.

Tests

The Tests tab checks the assistant against questions your customers really ask. For each test you write the customer's message, optional earlier chat, and what a good reply does. Each test is answered 3 times and graded 0 to 100. A large spread between the three answers means the assistant is not consistent yet. Each grading counts toward the AI budget.

AI runs

The AI runs tab lists every model call the assistant made in the last 30 days: when, what kind (reply, draft, follow-up, workflow, comment, tagging, test…), the outcome, the conversation, tokens, cost and latency. The Assistant tab sums up the last 30 days: runs, hand-offs and cost.

Budget and API key

The Team budget and key card on the Assistant tab sets:

Daily cap and Monthly cap in USD. Leave them blank to use the platform defaults. When a cap is hit, the assistant stops answering, admins get one email per day, and customers fall back to the offline flow.
Your own AI provider API key, for the provider of the configured model. Without it, the platform key is used. Remove the team key switches back.
The Notion integration token for Notion knowledge sources.

Everything the AI does for your business counts toward the same caps: replies, drafts, AI follow-ups, workflow AI writes a message steps, AI comment replies, automatic tagging, OCR of scanned PDFs, tests and the try-it panel.

Other places the AI helps

Follow-ups: a website's Automation tab can let the AI write follow-ups to customers who went quiet. See Automation.
Workflows: the AI writes a message step. See Automation.
Comment auto-replies: on Facebook, Instagram, TikTok and X accounts, public replies and private messages can be written by the AI. See the channel guides, for example Messenger and Instagram.
Tags: tags marked AI applies it in Support → Conversation tags are added automatically when a conversation matches their description, a few minutes after the first message and when it is resolved. The AI only adds tags; agents remove the ones they disagree with.

Manage knowledge with the API

To push your own documents (a help center, a CMS, product docs) under your own ids and keep them in sync on every deploy, use the Knowledge API. The source endpoints below add FAQs, text, files and websites to crawl.

Knowledge belongs to the business. The endpoints include a website id (site_…) in the path; any of your websites works.

Endpoint	Purpose
`GET /chat/sites/{id}/kb/sources`	List knowledge sources
`POST /chat/sites/{id}/kb/sources`	Add an FAQ, text or URL source; indexing runs in the background
`POST /chat/sites/{id}/kb/files`	Upload a PDF or DOCX (multipart field `file`, optional `title`), up to 20 MB
`GET, PATCH, DELETE /chat/sites/{id}/kb/sources/{sourceId}`	Read, update (re-indexes) or delete a source
`POST /chat/sites/{id}/kb/sources/{sourceId}/reindex`	Re-index a source
`GET /chat/sites/{id}/kb/search?q=…&limit=6`	Search the knowledge the assistant answers from (`limit` 1 to 20)

Reads need chat:read; changes need chat:write. Request fields for a source: kind (faq, text or url), title, content (for FAQ and text, up to 200,000 characters), url (for url) and refresh_days (0 to 90, default 7).

cURL
Node.js
Python
PHP

curl -X POST https://api.hatang.dev/chat/sites/site_123/kb/sources \
  -H "Authorization: Bearer ht_123..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "faq",
    "title": "Shipping",
    "content": "Q: How long does delivery take?\nA: 1-3 days in the city, 3-5 days elsewhere.\n\nQ: Is shipping free?\nA: Free for orders from 500,000 VND."
  }'

// The Node SDK does not wrap knowledge sources yet; call the endpoint directly.
const res = await fetch("https://api.hatang.dev/chat/sites/site_123/kb/sources", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.HATANG_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    kind: "faq",
    title: "Shipping",
    content: "Q: How long does delivery take?\nA: 1-3 days in the city, 3-5 days elsewhere.\n\nQ: Is shipping free?\nA: Free for orders from 500,000 VND.",
  }),
});
const source = await res.json();

import os, requests

res = requests.post(
    "https://api.hatang.dev/chat/sites/site_123/kb/sources",
    headers={"Authorization": f"Bearer {os.environ['HATANG_API_KEY']}"},
    json={
        "kind": "faq",
        "title": "Shipping",
        "content": "Q: How long does delivery take?\nA: 1-3 days in the city, 3-5 days elsewhere.\n\n"
                   "Q: Is shipping free?\nA: Free for orders from 500,000 VND.",
    },
)
source = res.json()

<?php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.hatang.dev']);
$res = $client->post('/chat/sites/site_123/kb/sources', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('HATANG_API_KEY')],
    'json' => [
        'kind' => 'faq',
        'title' => 'Shipping',
        'content' => "Q: How long does delivery take?\nA: 1-3 days in the city, 3-5 days elsewhere.\n\nQ: Is shipping free?\nA: Free for orders from 500,000 VND.",
    ],
]);
$source = json_decode($res->getBody(), true);

Response (201 Created):

{
  "object": "chat_kb_source",
  "id": "kbs_...",
  "site_id": "site_123",
  "kind": "faq",
  "title": "Shipping",
  "url": null,
  "status": "pending",
  "error": null,
  "pages": 0,
  "chunk_count": 0,
  "refresh_days": 7,
  "last_indexed_at": null,
  "created_at": "2026-10-23T03:00:00.000Z"
}

Poll GET /chat/sites/{id}/kb/sources/{sourceId} until status is indexed (or error, with the reason in error). A url source without url, or an FAQ or text source without content, returns 422 validation_error.

Agents' apps can also stop or resume the assistant in a conversation and settle drafts through the agent API of the chat gateway. See Chat gateway.

Troubleshooting

Symptom	Cause	Fix
The assistant hands every conversation off	The knowledge base is empty, or nothing is indexed yet	Add sources and wait for `indexed`
It never answers	Mode is Off, an agent stopped it in that conversation, a human owns the conversation, or the mode is When nobody is online and an agent is online	Check the mode and the conversation's assignee; click Resume AI
No drafts appear	No agent is online, the knowledge base is empty, or the mode is not Draft only and there was no hand-off	Drafts need an online agent and some indexed knowledge
It stopped answering everywhere	The daily or monthly cap was hit	Raise the caps or wait for the next day or month; see AI runs for what used the budget
A website source shows `error`	The site blocks the crawler in `robots.txt`, or the URL is unreachable	Allow the crawler, or add the content as text or a file

Next steps

Automation: flows, workflows and distribution rules that work with the assistant.
Webhooks reference: react to chat.conversation.handoff in your own systems.
REST API for Support: read conversations and messages from your backend.

View this page as Markdown

Before you start​

Step 1: Add knowledge​

Unanswered questions​

Try it​

Step 2: Choose a mode​

How the assistant handles a message​

Suggested replies (drafts)​

In the inbox​

Situations​

Tests​

AI runs​

Budget and API key​

Other places the AI helps​

Manage knowledge with the API​

Troubleshooting​

Next steps​