Bot Connect Overview

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 Admin → Apps → All Apps.
• 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

1. Enable Bot Connect from Admin → Apps → All Apps.
2. 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, Agent connections, Settings). An employee who opens Bot Connect from Apps lands on the first assistant they can use.
3. Open Apps → Bot Connect → Assistants and click Connect a bot.
4. Give the assistant a name (up to 120 characters). A URL-friendly slug is auto-generated from the name if left blank.
5. Choose how it connects:
   • Embed by URL (iframe) — MangoApps frames your existing chat URL. Provide the Chat URL (it must start with https://).
   • 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 returns the answer — word by word in Ask AI when your bot streams; the pop-up and the full-page tab show the whole answer once it is complete. 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.
6. 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 desktop page (the phone app’s pages do not show it).
   • Full-page tab — a dedicated page at a shareable link.
   • Home dashboard widget — a card on the Home dashboard.
7. Optionally, under Your sites that may show this assistant’s page, list your own sites (one per line) that may put the full-page tab inside their pages.
8. Toggle Enabled on so users can see the assistant.
9. 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 five tabs: Assistants (the registry), Analytics (usage data), Agent handoffs and Agent connections (partner AI agents — see §4), and Settings (global toggles and demo 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 — shown word by word in Ask AI; the pop-up and full-page tab show the finished answer

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 holding one of its keywords — or matching its topics, when MangoApps’ own agents are unsure — are answered by it instead of native agents
Pop-up chat bubble	A floating bubble on every desktop page. At most one assistant appears as the pop-up (the first enabled pop-up assistant alphabetically — your own before sample ones)
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, skus, 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, marked with the assistant’s name. Each question is routed on its own: a follow-up with none of the keywords or topics (“and in Dallas?”) goes to MangoApps’ own agents, so repeat a keyword to keep asking the bot. 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 two fields per assistant (a third, What does it answer?, is display only):

• Keywords — comma-separated exact words, matched as whole words (list the plurals people use too: sku, skus). A keyword in a question is the strongest routing signal. When two assistants list the same keyword, each of their cards on the Assistants page says which one gets a question where that keyword is the only match; an exact tie goes to the assistant added first. When one assistant lists a longer keyword that holds another’s (brake pads and brake), a question with the longer one goes to the assistant that listed it.
• Topics / domains — broader topic phrases. Individual words from these phrases contribute a weaker signal.
• What does it answer? — a short description shown under the assistant’s name on Home and, for an API assistant, as the greeting when users open its chat panel. Ask AI does not route by it.

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 — and has its own switch in notification settings, Bot Connect assistant alerts (in-app and email by default). The card shows the last error in words. When the assistant recovers — or an admin’s Test gets an answer — the Failing badge clears and the failing notification is marked read.

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); a reply with none of these counts as a failed request. 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.

Your sites that may show this assistant’s page — controls which of your own sites may put the assistant’s full-page tab inside their pages (for an API assistant as well as an embedded one). Each entry is a site origin (e.g. https://portal.yourcompany.com). MangoApps adds these origins to the page’s frame-ancestors Content Security Policy. It does not allow-list your bot’s chat URL.

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, Agent connections, 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. Opening Bot Connect from Apps takes them to the first assistant they can use, and the app’s rail lists those assistants (plus Agent handoffs for employees a partner connection allows). On the phone, assistants answer in Ask AI and from the Home card; the pop-up bubble is a desktop surface. 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 (by day in your time zone), a breakdown by surface (Ask AI, pop-up, full page — the Home card opens the full page), a per-assistant table, and the 20 most recent requests with the reason any of them failed. Use the period picker (7, 30, 90 days, or all time) to adjust the window. Click Export CSV to download every request in the period, failure reasons included (question text is not exported).

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 answered — or why not, for example that it refused the API key. 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 and Topics / domains fields under the Ask AI routing section (What does it answer? is the greeting and Home subtitle — Ask AI does not route by it). Keywords cause exact-word matches and are the strongest signal; list the plurals people use yourself. Topics contribute softer word-level signals. When two assistants list the same keyword, each card says which one gets a question where that keyword is the only match — an exact tie goes to the one added first. 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 and clears the badge. Without a Test it clears within 15 minutes of the bot answering employees again.

Agent connections and handoffs

Agent connections (admins) link Bot Connect to a partner company’s AI agent over the A2A protocol. Each connection has two halves, each switched on separately:

• Partner requests to Workforce — the partner’s agent reads service tickets as the employee you choose, with only that employee’s current access. Optionally it may also ask Ask AI as that employee, and — on a second switch — propose changes, which the partner approves itself (nobody here is asked). On the connection’s page, click Create inbound token and give the partner the token; it is shown once, and Replace inbound token stops the old one at once.
• Employees ask the partner — employees in the approved group send a ticket ID to the partner’s approved read-only skill. Save the partner’s card URL, endpoint, skill and bearer token, then click Verify partner card. Changing the endpoint, card URL, skill, partner tenant, employee or group needs verification again and stops requests already in flight from continuing.

Each half lists what it needs on the connection’s page (connection enabled, token issued or stored, card verified, group active…), so you can see which one is missing. There is no Remove: switch a connection off to stop it.

Agent handoffs is where an employee in the approved group asks the partner (Ask a partner), follows each request by its ticket number, answers when the partner needs more information, and uses Ask again on one that failed. They are notified when the partner answers, needs more information or fails (notification settings: Bot Connect agent handoffs). A handoff opened after its connection was changed or switched off — or after the employee left the group — says so and to ask a Bot Connect administrator.

Loading sample data

Go to Bot Connect → Settings → Demo data and click Load Sample Data to create five demo assistants (in iframe mode) so you can preview the app populated. Click Remove Sample Data to remove them. Sample assistants carry a Sample badge and never interfere with real ones; if you point one at your own chat URL or connect it by API, it becomes yours and Remove Sample Data leaves it alone.

5. Settings

Setting	Where	Default	What it changes
Route assistants inside Ask AI	Bot Connect → Settings	On	When on, Ask AI sends a question to the assistant whose keywords match it best — or whose topics match it, when MangoApps’ own agents are unsure. A question that @mentions an agent, is asked about the page or a file someone attached, or is one MangoApps always answers itself (your pay stub or paycheck deductions, where the handbook is, returned equipment) stays with MangoApps’ own agents, as does everything else. 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, one assistant with the Pop-up placement — the first enabled one by name, your own before sample ones — shows as a floating bubble on desktop pages. 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.