AI Not Working
View as Markdown
OmnyBot includes two AI assistants: **AI Bots** for customer conversations across connected channels (`DRAFT` or `AUTO_SEND` mode) and **Mina**, the in-app assistant for Q&A and quick actions. Use this checklist to isolate and fix common issues.
## AI Bot Is Not Replying or Generating Drafts
Check these conditions in the exact order the system evaluates them:
1. **No active AI Bot assigned to the channel:**
- In the Multi-Bot architecture, each channel (Zalo, Facebook Fanpage, WhatsApp, Webchat) **must have an active AI Bot (`isActive`) assigned** and AI enabled on that channel.
- *Fix:* Open **AI Bots** (requires `ai:manage`), verify the Bot is active, and confirm the target channel is connected to it.
2. **Auto-draft or conversation AI toggle is off:**
- Workspace **Auto-draft on inbound** (`autoDraftOnInbound`) or the **per-conversation AI toggle** is turned off.
- *Fix:* Re-enable the toggle in AI settings or in the conversation toolbar. (The manual **AI Suggest** button in the inbox still works even on muted conversations.)
3. **AI Wallet is out of tokens (`AI_WALLET_INSUFFICIENT_TOKENS`):**
- Each AI turn reserves at least **2,500 tokens** upfront before calling the model (low-balance alerts trigger below **15,000 tokens**).
- *Fix:* Check your balance under **Settings → Billing → Usage** and purchase an **AI Bot Token** pack in [Plans & Trials](/workspace-management/billing/).
4. **AI auto-paused by Human Handoff:**
- **Keyword handoff (`KEYWORD_HANDOFF`):** When a customer sends handoff keywords (default: *"gặp nhân viên"*, *"gặp người thật"*, *"tư vấn viên"*, *"alo shop"*, *"hotline"*, or custom Bot keywords), AI pauses on that thread (default **4 hours**).
- **Max consecutive bot replies:** After reaching consecutive reply limit (default **3** replies) without human intervention, AI pauses (default **4 hours**) so an agent can take over.
- *Fix:* Re-enable AI manually in the conversation toolbar, or wait for the pause duration to expire (AI auto-resumes on the next customer message).
5. **Inbound message triage:**
- **Noise (`NOISE`):** Stickers, emoji-only messages, or laughs (*"haha"*, *"hihi"*) are intentionally skipped to save tokens.
- **Acknowledgments (`ACK`):** *"ok"*, *"thanks"*, *"cảm ơn"*, *"dạ"* receive a **❤️** reaction (capped at **120/day**) instead of a text reply.
6. **Group chat or already replied:**
- Automated AI replies only run on 1-on-1 (**`DIRECT`**) threads, never on **`GROUP`** chats.
- If the latest message is outbound (**`OUT`**) from an agent, AI skips generating a draft.
7. **Outside active schedule:**
- Check the Bot's active schedule or workspace AI working hours.
## Bot Is in Auto-Send (`AUTO_SEND`) Mode but Only Shows a Draft (`DRAFT`)
This is a built-in **safety fallback** to prevent inaccurate replies:
- **Low confidence:** No sufficiently close Knowledge Base chunk was found (vector cosine distance above the `0.5` auto-send threshold) or the reply contained a deferral phrase (*"kiểm tra lại"*, *"nhờ bộ phận"*, *"check lại"*). OmnyBot keeps it as a draft for human review and logs an **AI Knowledge Gap (`OPEN`)**.
- **Daily auto-send cap reached (`autoSendDailyCap`):** Once the channel hits its daily auto-send ceiling, subsequent turns fall back to drafts.
**Fix:**
1. In the inbox, click **Use** to send the draft, edit it, or dismiss it.
2. Open **Knowledge Gaps** and add the missing product/policy info to your **Knowledge Base** — better grounding increases auto-send confidence.
3. Adjust the Bot's daily auto-send cap or confidence threshold if appropriate.
## Mina Assistant Won't Reply or Refuses Actions
| Symptom / Error Code | Cause | Fix |
| --- | --- | --- |
| `AI_AGENT_QUOTA_EXCEEDED` (429) | Daily per-user message limit, workspace message limit, or daily token budget was reached. | Wait until the next day when daily quotas reset. |
| `AI_AGENT_BUSY` (409) | The Mina thread is still processing an earlier turn (up to 60s lock). | Wait for the active response to complete before sending again. |
| Mina refuses KB writes, gap updates, or tags | Account lacks the required permission: KB/Gap actions require `workspace:manage`; QR login requires `nick:connect`; tags/templates require `inbox:reply`. | Ask an administrator for the required permission or run as Owner. |
| `DEEPSEEK_GENERATION_FAILED` / `OPENROUTER_GENERATION_FAILED` / `EMBEDDINGS_FAILED` (502) | Upstream AI model or embeddings service experienced a temporary failure. | Retry after a few minutes. Reserved AI Wallet tokens are automatically refunded on provider errors. |
:::tip[Stay ahead of gaps & token balance]
Enable **Knowledge Gap (`KNOWLEDGE_GAP`)** and **AI Wallet (`WALLET_LOW_TOKENS` / `WALLET_OUT_OF_TOKENS`)** notifications under [Notifications](/workspace-management/account-notifications/) so you can act before Bot replies pause.
:::
OmnyBot includes two AI assistants: AI Bots for customer conversations across connected channels (DRAFT or AUTO_SEND mode) and Mina, the in-app assistant for Q&A and quick actions. Use this checklist to isolate and fix common issues.
AI Bot Is Not Replying or Generating Drafts
Section titled “AI Bot Is Not Replying or Generating Drafts”Check these conditions in the exact order the system evaluates them:
- No active AI Bot assigned to the channel:
- In the Multi-Bot architecture, each channel (Zalo, Facebook Fanpage, WhatsApp, Webchat) must have an active AI Bot (
isActive) assigned and AI enabled on that channel. - Fix: Open AI Bots (requires
ai:manage), verify the Bot is active, and confirm the target channel is connected to it.
- In the Multi-Bot architecture, each channel (Zalo, Facebook Fanpage, WhatsApp, Webchat) must have an active AI Bot (
- Auto-draft or conversation AI toggle is off:
- Workspace Auto-draft on inbound (
autoDraftOnInbound) or the per-conversation AI toggle is turned off. - Fix: Re-enable the toggle in AI settings or in the conversation toolbar. (The manual AI Suggest button in the inbox still works even on muted conversations.)
- Workspace Auto-draft on inbound (
- AI Wallet is out of tokens (
AI_WALLET_INSUFFICIENT_TOKENS):- Each AI turn reserves at least 2,500 tokens upfront before calling the model (low-balance alerts trigger below 15,000 tokens).
- Fix: Check your balance under Settings → Billing → Usage and purchase an AI Bot Token pack in Plans & Trials.
- AI auto-paused by Human Handoff:
- Keyword handoff (
KEYWORD_HANDOFF): When a customer sends handoff keywords (default: “gặp nhân viên”, “gặp người thật”, “tư vấn viên”, “alo shop”, “hotline”, or custom Bot keywords), AI pauses on that thread (default 4 hours). - Max consecutive bot replies: After reaching consecutive reply limit (default 3 replies) without human intervention, AI pauses (default 4 hours) so an agent can take over.
- Fix: Re-enable AI manually in the conversation toolbar, or wait for the pause duration to expire (AI auto-resumes on the next customer message).
- Keyword handoff (
- Inbound message triage:
- Noise (
NOISE): Stickers, emoji-only messages, or laughs (“haha”, “hihi”) are intentionally skipped to save tokens. - Acknowledgments (
ACK): “ok”, “thanks”, “cảm ơn”, “dạ” receive a ❤️ reaction (capped at 120/day) instead of a text reply.
- Noise (
- Group chat or already replied:
- Automated AI replies only run on 1-on-1 (
DIRECT) threads, never onGROUPchats. - If the latest message is outbound (
OUT) from an agent, AI skips generating a draft.
- Automated AI replies only run on 1-on-1 (
- Outside active schedule:
- Check the Bot’s active schedule or workspace AI working hours.
Bot Is in Auto-Send (AUTO_SEND) Mode but Only Shows a Draft (DRAFT)
Section titled “Bot Is in Auto-Send (AUTO_SEND) Mode but Only Shows a Draft (DRAFT)”This is a built-in safety fallback to prevent inaccurate replies:
- Low confidence: No sufficiently close Knowledge Base chunk was found (vector cosine distance above the
0.5auto-send threshold) or the reply contained a deferral phrase (“kiểm tra lại”, “nhờ bộ phận”, “check lại”). OmnyBot keeps it as a draft for human review and logs an AI Knowledge Gap (OPEN). - Daily auto-send cap reached (
autoSendDailyCap): Once the channel hits its daily auto-send ceiling, subsequent turns fall back to drafts.
Fix:
- In the inbox, click Use to send the draft, edit it, or dismiss it.
- Open Knowledge Gaps and add the missing product/policy info to your Knowledge Base — better grounding increases auto-send confidence.
- Adjust the Bot’s daily auto-send cap or confidence threshold if appropriate.
Mina Assistant Won’t Reply or Refuses Actions
Section titled “Mina Assistant Won’t Reply or Refuses Actions”| Symptom / Error Code | Cause | Fix |
|---|---|---|
AI_AGENT_QUOTA_EXCEEDED (429) | Daily per-user message limit, workspace message limit, or daily token budget was reached. | Wait until the next day when daily quotas reset. |
AI_AGENT_BUSY (409) | The Mina thread is still processing an earlier turn (up to 60s lock). | Wait for the active response to complete before sending again. |
| Mina refuses KB writes, gap updates, or tags | Account lacks the required permission: KB/Gap actions require workspace:manage; QR login requires nick:connect; tags/templates require inbox:reply. | Ask an administrator for the required permission or run as Owner. |
DEEPSEEK_GENERATION_FAILED / OPENROUTER_GENERATION_FAILED / EMBEDDINGS_FAILED (502) | Upstream AI model or embeddings service experienced a temporary failure. | Retry after a few minutes. Reserved AI Wallet tokens are automatically refunded on provider errors. |