Bot Connect
1. What it is
Bot Connect lets you register a chatbot you already run on your own infrastructure and surface it inside MangoApps — without rebuilding it. You choose where it appears: inside the Ask AI box, as a floating pop-up bubble, as a full-page tab, or as a Home dashboard widget.
- Enablement: Bot Connect is a licensed app, disabled by default. An admin enables it from the Apps Marketplace.
- What it is not: Bot Connect does not host or train bots. It connects to a chatbot you already operate. If you need a MangoApps-hosted bot with its own knowledge base, that is the Workforce Bots app.
2. Standing it up
- Enable Bot Connect from the Apps Marketplace.
- Grant access. Only admins (Admin or above) and designated app admins can manage assistants and settings. All other users see only the surfaces an enabled assistant is placed on — they cannot open the admin tabs (Assistants, Analytics, Settings).
- Open Apps → Bot Connect → Assistants and click Connect a bot.
- Give the assistant a name (up to 120 characters). A URL-friendly slug is auto-generated from the name if left blank.
- Choose how it connects:
- Embed by URL (iframe) — MangoApps frames your existing chat URL. Provide the Chat URL and, optionally, Allowed origins (one per line) so external sites can frame the full-page embed.
- Connect by API — Provide the API endpoint, an API key / bearer token, and optionally an HMAC signing secret. MangoApps proxies questions to your endpoint and streams answers back. Credentials are stored encrypted in Integrations, never on the assistant itself. This mode is recommended because it supports Ask AI routing, analytics, health monitoring, and conversation-history forwarding.
- Under Where should it appear?, select one or more placements:
- Inside the Ask AI box — requires API mode.
- Pop-up chat bubble — a floating bubble on every page.
- Full-page tab — a dedicated page at a shareable link.
- Home dashboard widget — a card on the Home dashboard.
- Toggle Enabled on so users can see the assistant.
- Verify it works:
- For an API assistant, click Test on the assistant card. A successful test shows “Reachable — your bot responded.”
- For an iframe assistant, click Open and confirm the chat loads in the full-page tab.
The admin sidebar has three tabs: Assistants (the registry), Analytics (usage data), and Settings (global toggles and sample data).
Two things that silently do nothing until both are set: The Pop-up and Ask AI placements on an individual assistant will not appear unless the matching global toggle is also on in Bot Connect → Settings (see §5). Each placement is gated twice — once on the assistant and once globally.
3. How it fits together
Assistant — a single registered bot. Each assistant has its own slug, connection mode, placements, optional icon and accent color, and (for API mode) its own endpoint and credentials. You can register as many assistants as your organization needs. Each one appears as a card on the Assistants page showing its mode badge (API or Embed), active placements, usage stats, and health status.
Connection mode — the choice that shapes everything else:
| Embed by URL (iframe) | Connect by API | |
|---|---|---|
| How it works | Renders your chat URL in an iframe | Proxies questions to your endpoint, returns the answer |
| MangoApps sees the conversation | No | Yes |
| Supports Ask AI routing | No | Yes |
| Analytics and health monitoring | No | Yes |
| Domain allow-listing required | Yes | No |
| Streaming support | N/A (your UI handles it) | Yes, via Server-Sent Events |
An iframe-only assistant cannot be placed inside the Ask AI box — that placement requires API mode so MangoApps can actually query the bot.
Placements — where an assistant shows up. Each placement is independent, and an assistant can have several at once:
| Placement | What the user sees |
|---|---|
| Inside the Ask AI box | Questions matching the assistant’s keywords or topics are answered by it instead of native agents |
| Pop-up chat bubble | A floating bubble on every page. At most one assistant appears as the pop-up (the first enabled popup-placement assistant, alphabetically) |
| Full-page tab | A dedicated page at /apps/external/<slug> with a shareable link |
| Home dashboard widget | A card on the Home dashboard listing each home-widget assistant, linking to its full-page tab |
A worked example: You register “Parts Lookup Bot” in API mode, placed in Ask AI and Full-page tab. You set its keywords to parts, sku, catalog and its topic to store inventory. When an employee types “how many SKUs are in stock?” in Ask AI, the router sees the keyword match and sends the question to your bot. The answer streams back in the Ask AI box. The same employee can also open the full-page tab from the left rail and chat directly.
Ask AI routing — for API assistants placed in Ask AI, the platform scores each question against every routable assistant’s configured keywords and topics. A keyword match is the strongest signal. Topic-word matches score lower and only claim the question when the native agent’s confidence is weak. If no assistant matches, the question falls through to native agents. Routing requires the Route assistants inside Ask AI global toggle to be on.
For routing, you configure three fields per assistant:
- Keywords — comma-separated exact words. A question containing the word routes to this assistant.
- Topics / domains — broader topic phrases. Individual words from these phrases contribute a weaker signal.
- What does it answer? — a short description that disambiguates when several assistants are registered and that is shown as the greeting when users open the chat panel.
Health monitoring — every 15 minutes, a background check reviews the most recent log entries for each enabled API assistant. If the last 3 consecutive requests all failed, the assistant is marked Failing on its card and admins receive a notification with the last error message. The notification fires once per transition from healthy to failing — it does not repeat while the assistant stays down. When the assistant recovers, the status clears silently.
API contract — when MangoApps proxies a question, it POSTs JSON containing the message, conversation context, assistant slug, and user identity, with the bearer token in the Authorization header. If an HMAC signing secret is configured, an X-MangoApps-Signature header carries an HMAC-SHA256 signature of the request body so your backend can verify authenticity. The bot’s response is read from the answer field (or reply, message, or text). To stream, the bot replies with Server-Sent Events whose data: lines carry the text deltas.
Credential security — API keys and signing secrets are stored on an encrypted integration record, never on the assistant itself. When you remove an assistant, its credential record is deleted in the same transaction. If you switch an assistant from API mode to iframe mode, the credential record is also removed immediately.
Allowed origins (iframe mode) — the Allowed origins field controls which external domains may frame the full-page embed page. Each entry must be an http(s):// origin (e.g. https://portal.yourcompany.com). MangoApps sets a frame-ancestors Content Security Policy header with these origins on the embed page.
Relationship to Workforce Bots — Workforce Bots is a separate app that hosts, trains, and manages bots inside MangoApps with knowledge bases, approval queues, and grading tools. Bot Connect does none of that — it is purely a connector for bots you run externally. Both apps can coexist: an employee might ask a Workforce Bot about company policies and a Bot Connect assistant about parts inventory in the same session.
4. Running it
What users see
End users do not see the Assistants, Analytics, or Settings tabs — those are admin-only. Users interact with assistants through the placements: typing a question in Ask AI, chatting via the pop-up bubble, opening the full-page tab, or clicking the Home widget card. The app respects visibility rules: if Bot Connect is scoped to specific groups, only users in those groups see the assistants.
Reviewing usage
Open Bot Connect → Analytics to see total questions asked, success rate, average response time, and active assistant count. The page shows daily volume, a breakdown by surface (Ask AI, pop-up, full-page, home widget), a per-assistant table, and the 20 most recent questions. Use the period picker (7, 30, 90 days, or all time) to adjust the window. Click Export CSV to download the raw data.
Testing an API assistant
On the Assistants page, click Test on any API-mode assistant card. MangoApps sends a test ping to the endpoint and reports whether the bot responded. Test requests are excluded from usage analytics.
Editing or removing an assistant
Click Edit on its card to open the form in a drawer. You can change the name, slug, connection mode, placements, credentials, routing configuration, icon, color, and enabled state. Click Remove to delete the assistant and its stored API credentials in one step. Removing an assistant also deletes its usage logs.
Tuning Ask AI routing
Edit an assistant and adjust the Keywords, Topics / domains, and What does it answer? fields under the Ask AI routing section. Keywords cause exact-word matches and are the strongest signal. Topics contribute softer word-level signals. Test by asking questions in Ask AI and checking which assistant answered in Analytics.
Responding to a health alert
When an API assistant’s health monitor detects consecutive failures, admins and app admins receive a notification titled “Bot Connect: assistant failing” with the assistant’s name and the last error message. Open Assistants, find the card with the red Failing badge, and click Edit to check the endpoint and credentials. Click Test after correcting them — a successful test confirms the fix. The badge clears automatically on the next successful request.
Loading sample data
Go to Bot Connect → Settings → Sample data and click Load sample assistant to create five demo assistants (in iframe mode) so you can preview the app populated. Click Clear sample data to remove them. Sample assistants are tagged and never interfere with real ones.
5. Settings
| Setting | Where | Default | What it changes |
|---|---|---|---|
| Route assistants inside Ask AI | Bot Connect → Settings | On | When on, questions matching an assistant’s keywords or topics route to that assistant inside Ask AI. When off, all questions go to native agents regardless of per-assistant placement. |
| Allow the site-wide pop-up bubble | Bot Connect → Settings | On | When on, an assistant with the Pop-up placement shows as a floating bubble across the workspace. When off, no pop-up appears even if an assistant has that placement selected. |
| Enabled (per assistant) | Assistants → Edit | Off | Controls whether this assistant is visible to users. A disabled assistant does not appear in any placement and is not health-monitored. |
Both app-level settings default to On from the configuration schema. The per-assistant Enabled toggle defaults to Off, so a newly connected assistant does not appear until the admin explicitly enables it.
6. More help
- Bot Connect FAQ — specific setup and operating questions, including message limits, timeout behavior, and streaming details.
- Ask AI — the assistant answers questions about Bot Connect from these articles.