Bot Connect FAQ
Answers to common setup and operating questions about Bot Connect.
For what the app is and how to set it up from scratch, see the
Bot Connect Overview.
Setup
Do I need to turn on both a global setting and a per-assistant placement?
Yes. The pop-up bubble and Ask AI routing each have two gates. The global toggles in Bot Connect → Settings — Route assistants inside Ask AI and Allow the site-wide pop-up bubble — must be on, and the individual assistant must also have that placement selected. If either gate is off, the assistant does not appear on that surface. Both global toggles default to On, but the per-assistant Enabled switch defaults to Off, so a newly connected assistant does not appear until you explicitly enable it.
What does my API endpoint need to return?
MangoApps POSTs a JSON body containing the question, conversation context, assistant slug, and user identity. Your endpoint should return a JSON object with the answer in an answer field. The proxy also accepts reply, message, text, or the OpenAI choices[0].message.content shape. A reply with none of these counts as a failed request — Test says so — rather than showing an empty answer. To stream, reply with a text/event-stream content type and send data: lines carrying the text deltas; send data: [DONE] to signal the end.
How do I verify my bot is reachable before rolling it out?
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. Test requests are excluded from usage analytics, so they do not affect your success-rate numbers.
Permissions and access
Who can manage assistants and settings?
Business admins (Admin or above) and users granted the Bot Connect app-admin role. No other role can see the Assistants, Analytics, Agent connections, or Settings tabs. End users interact with assistants only through the surfaces they are placed on; opening Bot Connect from Apps takes them to the first assistant they can use.
Can I limit which employees see a connected assistant?
For the app as a whole, yes — not per assistant. Bot Connect respects the app’s visibility rules: if you scope the app to specific groups in Admin → Apps → All Apps, only users in those groups see the assistants — in Ask AI, the pop-up bubble, the full-page tab, and the Home widget. Users outside the scoped groups are told they do not have access.
Day-to-day
How does Ask AI decide which assistant answers a question?
For each API-mode assistant placed in Ask AI, the router scores the question against the assistant’s configured Keywords and Topics / domains. A keyword match is the strongest signal (exact word-boundary match). Topic words contribute a weaker signal and only claim the question when the native agent’s own confidence is low. An assistant whose keyword is in the question beats one matched only by topic words; after that the higher score wins, then the longer keyword (“brake pads” over “brake”), and an exact tie goes to the one added first. A question that @mentions an agent, is about the page or an attached file, or is one MangoApps always answers itself (your pay stub or paycheck deductions, where the handbook is, returned equipment) is never routed to an assistant. If no assistant scores above zero, the question falls through to native MangoApps agents.
Can my bot answer follow-up questions?
In its chat panel (the pop-up and the full-page tab), yes: the panel sends up to 10 prior conversation turns with each question so your bot can answer in context. Each prior turn’s content is capped at 2,000 characters. The turns arrive in the request’s context.history array. In Ask AI, each question is routed on its own — a follow-up with none of the assistant’s keywords or topics goes to MangoApps’ own agents, so employees should repeat a keyword to keep asking your bot.
Does each proxied question cost AI credits?
Yes. Bot Connect is usage-based: each question MangoApps successfully proxies to your bot draws 1 AI credit. Test-connection pings do not draw credits.
What does HMAC signing do, and should I enable it?
When you enter an HMAC signing secret on an assistant, MangoApps attaches an X-MangoApps-Signature header to every request. The header carries an HMAC-SHA256 signature of the raw JSON body, signed with your secret. Your backend can verify the signature to confirm the request genuinely came from MangoApps. It is optional but recommended for production bots.
What happens to API credentials and logs when I remove an assistant?
Removing an assistant deletes the assistant, its encrypted credential record, and all its usage logs in a single transaction. Nothing is orphaned. If you only switch an assistant from API mode to iframe mode (without removing it), the credential record is also deleted immediately.
When something looks wrong
“I typed my question in Ask AI but a different assistant answered”
The router matched a different assistant’s keywords or topics more strongly. Open Assistants → Edit on the assistant you expected and check its Keywords and Topics / domains. Keywords are exact word-boundary matches and score highest — add the specific terms employees use, plurals included. If two assistants share overlapping terms, a keyword in the question beats any number of topic words, then the higher score wins; an exact tie goes to the one added first. Each card on the Assistants page names the keywords it shares with another assistant and which one gets a question where that keyword is the only match. The answer in Ask AI names the assistant that gave it, and Analytics lists which assistant handled each request.
“The bot says it couldn’t be reached right now”
MangoApps could not get an answer from the bot’s API endpoint within 25 seconds, or the bot answered with an error. Open the assistant’s card and click Test to check reachability — it says what went wrong. Common causes: the endpoint URL is wrong, the API key has expired, or the bot’s server is down. If the last 3 requests within an hour all failed, the health monitor (every 15 minutes) marks the assistant as Failing, shows the last error on its card, and notifies admins.
“I can’t see the chat bubble anywhere on the site”
Three things must all be true for the pop-up bubble to appear: the global Allow the site-wide pop-up bubble toggle in Settings must be on, the assistant must have the Pop-up chat bubble placement selected and be Enabled, and the user must be within the app’s visibility scope. If Bot Connect is scoped to certain groups, users outside those groups do not see the bubble. Only one assistant is the pop-up — the first enabled one by name, your own before sample ones — and it shows on desktop pages, not in the phone app.
“The iframe shows blank — nothing loads”
In iframe mode, your chat URL’s domain must be allowed by MangoApps before it can be framed, and your bot’s own site must allow being framed (no X-Frame-Options: DENY, and a sign-in that works inside a frame). Until both are true, the iframe renders blank. Employees can still use Open in a new tab on the assistant’s page. The Your sites that may show this assistant’s page field does not allow-list your bot’s URL — it is for your own sites that frame MangoApps. Consider switching to Connect by API mode, which does not require domain allow-listing and also supports analytics, health monitoring, and Ask AI routing.
Partner agents
What are Agent connections and Agent handoffs?
They connect Bot Connect to a partner company’s AI agent over the A2A protocol. A partner’s agent can read service tickets as an employee you choose (with that employee’s access only), and employees in a group you approve can hand a ticket ID to the partner’s read-only skill and follow the answer under Agent handoffs. See the overview’s “Agent connections and handoffs” section.
“Employees in the group don’t see the partner”
Open the connection under Agent connections: the What employee requests need list shows which condition is missing — most often the partner card is not verified for the current settings, or no partner bearer token is stored.
Licensing and limits
Does Bot Connect require a licence?
Yes. Bot Connect is disabled by default and requires a licence. An admin enables it from Admin → Apps → All Apps. Usage is billed through AI credits (1 credit per proxied question).
What are the limits I should know about?
| Limit | Value |
|---|---|
| Assistants per organization | Unlimited |
| Assistant name | Up to 120 characters |
| Question length | Up to 4,000 characters |
| Follow-up context | Up to 10 prior turns, each up to 2,000 characters |
| Request timeout | 25 seconds |
| Request signing | HMAC-SHA256 |
| Health-check cadence | Every 15 minutes |
| Consecutive failures before alert | 3 requests within 1 hour |
| Analytics periods | 7, 30, 90 days, or all time |
| AI credit cost per question | 1 credit |
More help
- Bot Connect Overview
- Ask AI — the assistant answers Bot Connect questions from these articles.