Workforce Bots FAQ
Answers to common setup and operating questions about Workforce Bots.
For what the app is and how to set it up from scratch, see the
Workforce Bots Overview.
Setup
Do I need to upload documents before my bot can answer anything?
Yes. A bot answers only from the material in its knowledge base. Until at least one document shows a processing status of Ready, the bot returns the fallback message you configured (or the template default) for every question.
Which file types and sizes does the knowledge base accept?
PDF, Word (.doc and .docx), and plain text. Each file can be up to 10 MB. Spreadsheets, CSV, and image files are not accepted as knowledge documents.
What happens after I upload a document?
The system extracts the text, generates a summary and key topics, and splits the content into chunks of roughly 1,500 characters each. The document status moves from Pending to Processing to Ready. If extraction fails, the status shows Failed and you can retry from the Documents page.
Permissions and access
Who can create and manage bots?
Admins and app admins can create, edit, delete, and sync bots, manage documents, review approvals, read conversations, and change settings. All other employees can view active bots and chat with them through the Ask tab or the portal, but cannot change anything.
What do the access modes mean?
Each bot has one of four modes:
- Portal Only (Public) — anyone with the portal link can chat; no MangoApps login required.
- Portal with Login — the portal link works but the visitor must log in first.
- Internal Only (Intranet) — available only inside the app through the Ask tab and the Bots list; no portal page at all.
- Both Portal and Internal — available everywhere.
The default is Portal Only (Public).
I set a bot to Internal Only but employees still can’t see it — what’s wrong?
Check three things: the bot’s status must be Active, the Draft toggle must be off, and the Workforce Bots app must be enabled for your organization. A draft bot or a bot with an expired or upgraded status is hidden from everyone except admins.
Day-to-day
How does the Ask tab decide which bot to use?
When your organization has more than one active internal bot, a lightweight classifier picks the most relevant one for each question. The answer shows which bot responded. With a single active internal bot, questions go to it directly.
Can employees ask questions in their own language?
Yes. On the bot’s edit page, pick a Primary language from the dropdown (16 languages are available: English, Spanish, French, German, Portuguese, Italian, Japanese, Chinese, Korean, Hindi, Arabic, Dutch, Polish, Russian, Turkish, and Vietnamese). Enable Auto-detect user language and reply in kind to have the bot detect the language and respond in it automatically. Auto-detect is off by default.
How do I embed a bot on our company website?
The bot must have a portal access mode (Portal Only, Portal with Login, or Both). The portal page supports three embedding paths: a full-page link at /portal/<slug>, a chrome-stripped iframe at /portal/<slug>?embed=1, and a JavaScript widget snippet that renders a floating chat bubble. Restrict which external domains may embed the bot by entering allowed origins on the bot’s edit page under Allowed embed origins.
Can I pass our own SSO identity into an embedded bot?
Yes. Set a SSO shared secret on the bot’s edit page. Your site signs a JWT with that secret using HS256 (the token must include an expiry claim). The portal uses the asserted name and email for attribution without creating a platform account.
How does the “Route to a human” escalation work?
When deflection is enabled and an answer falls below the configured confidence threshold, the employee sees a Route to a human button. Clicking it tries to reach a person in this order: first it creates a Service Desk ticket (if Service Desk is enabled for your organization), then it sends an in-app notification to the bot’s admin. The configured deflection webhook fires alongside either path. The reply the employee sees says whether a human was actually reached — it does not promise hand-off unconditionally.
What triggers each webhook event?
Webhooks fire on four events: Conversation completed (the session ends), Low rating (the employee rates an answer 1 or 2 stars), Question unanswered (the bot could not find a relevant answer), and Routed to a human (the employee clicked the deflection button). Each payload is signed with HMAC-SHA256 using the webhook’s secret.
When something looks wrong
“The bot just gave the wrong answer — can I fix it?”
The answer has already been shown; approving or rejecting stamps a compliance record but does not change what the employee saw. To improve future answers, go to the bot’s Knowledge Gaps page, find the question, and click Teach the bot — the answer you write is saved as an FAQ document in the bot’s corpus. You can also upload a better document or edit the system prompt.
“My document has been stuck on Processing for a long time”
Open the bot’s Documents page, find the document, and click Retry. If it fails again, the status shows Failed with an error message. Common causes are password-protected PDFs, scanned images without text layers, and corrupted files. Re-upload with a clean copy.
“Employees say the portal page won’t load”
Verify the bot’s access mode includes portal access (Portal Only, Portal with Login, or Both). A bot set to Internal Only has no portal page — the URL returns a not-found error. Also confirm the bot is Active, not in draft, and that its portal slug is set.
“I got a notification that a webhook was auto-disabled”
A webhook is automatically disabled after 15 consecutive delivery failures. Fix the receiving endpoint, then re-enable the webhook from the bot’s Webhooks tab. The failure count resets on the next successful delivery.
“The bot isn’t answering questions from our Knowledge Base”
Make sure a Knowledge Base source is selected on the bot’s edit page and that you have clicked Sync Now or enabled Knowledge Base Sync for nightly updates. The available sources (Service Desk, Safety Hub, Recruiting, HR, Help, Learning, Inspections, Custom) appear in the dropdown only when your organization has entries in that domain.
Governance and compliance
What does PII redaction cover?
When PII redaction is enabled on a bot, user messages are scanned before storage for five patterns: Social Security numbers, credit-card numbers, email addresses, phone numbers, and dates of birth. Each match is replaced with [REDACTED]. Redaction runs on user messages only, not on the bot’s answers.
How does the conversation retention policy work?
In Settings → Erase conversation text after, set a number of days (minimum 7). A nightly job erases the message text of conversations older than that window. The conversation row, its timestamps, ratings, and audit trail are preserved — only the free-text content is removed. Leaving the field blank keeps conversations forever, which is the default.
What does “Require identity verification to read conversations” do?
When enabled, admins must re-enter their password or PIN before opening the conversation transcript viewer. The verification lasts 15 minutes. Each read is logged to the audit trail. This protects sensitive employee questions (HR, medical, benefits) from casual browsing by admins who stay logged in.
Licensing and limits
Does Workforce Bots require a license?
Yes. An admin enables it from the Apps Marketplace and a license is required. Workforce Bots is off by default for every organization.
Are there limits I should know about?
| What | Limit |
|---|---|
| Upload size | 10 MB per file |
| Accepted formats | PDF, Word (.doc/.docx), plain text |
| Knowledge-base chunk size | ~1,500 characters with 200-character overlap |
| Bot name | 100 characters |
| Bot description | 240 characters |
| Welcome message | 120 characters |
| Conversation starters | Up to 6 per bot, each up to 120 characters |
| Avatar | PNG, JPG, or WebP; max 2 MB |
| Portal message length | 5,000 characters |
| Image attachments per turn | 2 images; max 800 KB decoded per image |
| Raw photo upload (mobile) | 15 MB; downscaled to 1,024 px longest edge |
| Portal rate limit | 60 questions/minute (paid) · 20 questions/minute (free-tier) |
| Webhook secret | Minimum 16 characters |
| Webhook circuit breaker | Auto-disables after 15 consecutive failures |
| Conversation retention minimum | 7 days |
| Monthly question quota | Optional, admin-configured per bot or across the organization. No hard cap by default. |
More help
- Workforce Bots Overview
- Ask AI — the assistant answers Workforce Bots questions from these articles.