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, deactivate and sync bots, manage documents, read conversations and change settings; only a business admin can delete a bot. People with the Contributor grant can manage a bot’s documents, Knowledge Gaps and syncing. Who reviews answers is set under Settings › Who can review an answer?. 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 OneMango 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 Internal Only (Intranet) — a bot you create by accepting the defaults has no portal page at all, and is reachable only by signed-in employees. Choose a portal mode deliberately when you want the bot on a public page.
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 is hidden from everyone except admins and people with the Contributor grant. A Deactivated or Retired bot still appears in the Bots list with its status, but answers no one.
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 on by default.
How do I embed a bot on our company website?
The bot must have a public portal (Portal Only or Both) — a Portal with Login page can’t complete a sign-in inside an embed. The portal page supports three embedding paths: a full-page link at /apps/workforce_bots/portal/<slug>, a chrome-stripped iframe at /apps/workforce_bots/portal/<slug>?embed=1, and a JavaScript widget snippet that renders a floating chat bubble. Embedding is refused until you name an origin: enter the allowed sites on the bot’s edit page under Allowed embed origins (or * for any site). If you leave that field blank the iframe will not render anywhere — that is the shipped default for a new bot, and there is no server-side error to look for, so check it first if your embed shows an empty box.
Can I pass our own SSO identity into an embedded bot?
Not yet. You can set an SSO shared secret on the bot’s edit page, and the portal then checks a JWT your site signs with it (HS256, with an expiry claim) and ignores one that fails — but the asserted name and email are not yet attached to the conversation, which still shows as an anonymous visitor. The secret does not restrict who can open the portal; Access mode does.
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. The button is on the bot portal, the bot’s in-app chat panel, the Ask page and the mobile app; on the portal (when signed in), the chat panel and the mobile app it also stays on earlier answers when the conversation is reopened.
Admins notified about an escalation open the conversation from the notice. Once someone has followed up, Mark handled on that conversation takes the notice out of every admin’s Inbox.
What triggers each webhook event?
Webhooks fire on four events: Conversation completed (after every answer the bot gives, on every door), Thumbs-down (poor rating) (the employee gives an answer a thumbs-down), 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 it or marking it incorrect in Low-confidence answers, or marking it addressed in Answer reviews, records the review 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. An answer someone rated poorly can be taught the same way from Answer reviews (Teach the bot the right answer). You can also upload a better document or edit the system prompt.
When you approve a low-confidence answer or mark it incorrect, you can add a Note to the person who asked. They see it with the decision and under that answer in My questions, where each conversation opens in full. The separate internal note is seen only by bot admins.
“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 Webhooks in the bot’s Actions menu. The failure count resets on the next successful delivery.
“The bot isn’t answering questions from our Knowledge Base”
Make sure a source is selected under Sync from Knowledge Base source on the bot’s edit page, and that you have clicked Sync Now or ticked Re-sync automatically every hour. 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 Admin → Apps → All Apps 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.