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. 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 responded. 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, or Settings tabs. End users interact with assistants only through the surfaces they are placed on.
Can I limit which employees see a connected assistant?
Yes. Bot Connect respects the app’s visibility rules. If you scope the app to specific groups in the Apps Marketplace, 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. The highest-scoring assistant wins. If no assistant scores above zero, the question falls through to native MangoApps agents.
Can my bot answer follow-up questions?
Yes. The chat 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.
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. If two assistants share overlapping terms, the one with more matching terms wins. Check the Analytics page to see which assistant actually handled the question.
“The bot says it couldn’t be reached right now”
MangoApps could not get a response from the bot’s API endpoint within the timeout window (25 seconds by default, 60 seconds maximum). Open the assistant’s card and click Test to check reachability. Common causes: the endpoint URL is wrong, the API key has expired, or the bot’s server is down. If the last 3 consecutive requests all failed, the health monitor marks the assistant as Failing and notifies admins automatically.
“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.
“The iframe shows blank — nothing loads”
In iframe mode, your chat URL’s domain must be allowed by MangoApps before it can be framed. Until it is, the iframe renders blank with no visible error. Consider switching to Connect by API mode, which does not require domain allow-listing and also supports analytics, health monitoring, and Ask AI routing.
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 the Apps Marketplace. 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 (60 seconds maximum) |
| 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.