Installing and connecting

Install the addon, connect an AI service through the environment file, create the persona, and get the first grounded answer. Includes why the API key cannot be entered on a screen.

6 min readUpdated 6 August 2026install, provider, env, api-key

Install the addon the way you install any other, then work down this page in order. Each step is inert until the one above it is done — a model picker with no provider connected is an empty dropdown, and a persona with no knowledge behind it escalates every question.

Before you start

Bicrypto core installed and running
Your purchase details for this addon
Shell access to the server and the ability to restart the backend — the AI credential cannot be entered from a screen, for the reason below
Outbound HTTPS from the server to whichever AI service you connect

1. Install the addon

Open Admin → System → Extensions — the screen is at /admin/system/extension.
Find "AI Support" — the extension identifier in the database and in error messages is ai_support.
Activate it with your purchase details.
Confirm the navigation — an AI Support entry appears in the admin navigation and points at /admin/ai/support.

Each console screen carries its own permission rather than sitting behind one addon-wide key. access.ai.support opens the Overview screen at /admin/ai/support; Settings and Workflows need access.ai.support.settings, Provider needs access.ai.support.provider, Knowledge and Gaps need view.ai.support.knowledge, Agents needs view.ai.support.agent, the Handbook needs view.ai.support.handbook, and the Live Inbox runs on the desk's existing view.support.ticket so it appears for your agents with no grant step. Grant the ones your support lead needs in Admin → Roles before handing the console over, or they will see the navigation entry and a permission error behind it. The full map is in Permissions.

Generation is licence-gated inside the addon, not only at the admin routes, because the assistant is triggered from the customer's own reply route. An install whose licence has lapsed — or one that simply cannot reach the licence service — has an assistant that looks configured, reports a healthy Overview and answers nothing at all. See Troubleshooting for the log line to grep for.

2. Connect an AI service

Open Admin → AI Support → Configuration → Provider. Three options:

Option	What you provide	Where it runs
Managed connection	Nothing — it is included with your licence	Our gateway
Your own key	An API key from the AI vendor	Their API, billed to you
Any compatible endpoint	A base URL and a key	Wherever you point it

The third option speaks the widely-supported chat-completions shape, so a self-hosted model or a third-party router needs no code change — but on top of the base URL and the key it needs three more environment variables of its own, because on that provider the console can neither pick the model nor price it. The model is one, the rate card is the other two, and both are covered below.

GET /api/settings is a public endpoint — it has to be, because the storefront reads branding and feature flags from it before anyone signs in. It returns every settings row minus a small denylist. An API key written to the settings table would therefore be readable by anyone loading your public site.

So credentials live in the environment file and nowhere else. The Provider screen never accepts a credential and never displays one; it reports whether the key is present, its first few characters, and offers a live probe against the service. Connecting a provider needs shell access and a backend restart.

Add the keys your chosen option needs to .env at the project root:

# The AI vendor's own API
ANTHROPIC_API_KEY=sk-ant-...

# Any compatible endpoint
AI_SUPPORT_OPENAI_BASE_URL=https://your-endpoint.example/v1
AI_SUPPORT_OPENAI_API_KEY=sk-...
AI_SUPPORT_OPENAI_MODEL=the-model-your-endpoint-serves
AI_SUPPORT_OPENAI_INPUT_USD_PER_MTOK=0.60
AI_SUPPORT_OPENAI_OUTPUT_USD_PER_MTOK=2.40

# The managed connection
AI_SUPPORT_GATEWAY_TOKEN=...
AI_SUPPORT_GATEWAY_SECRET=...

The compatible endpoint needs its model and its prices in `.env` too

Everything about that provider that the console cannot know lives here.

AI_SUPPORT_OPENAI_MODEL is the model. Not aiSupportModel — the Model tab's answering-model picker is empty and inert on this provider, because the endpoint behind it could be serving anything and a list of models it may not have is worse than a note saying where the value comes from. Leave the variable unset and the adapter falls back to a hosted model id your endpoint probably does not serve, and that the addon has no price for.
The two rate-card variables are what make a spend cap enforceable. The adapter cannot know what your endpoint charges — it may be a local model that costs nothing, a metered API, or a flat subscription — so unless you say, every answer records a cost of zero. Set both, in USD per million tokens, to whatever your endpoint charges. Half a rate card is treated as none.

If either budget ceiling is above zero and any model call this month recorded no cost, the assistant stops answering with the reason unpriced_model rather than running unbounded against a ceiling it cannot measure. Two ways out, and they are both decisions only you can make: set the two rate-card variables above, or set the caps to 0, which has always meant "no ceiling" and is the right answer for a genuinely free local model. See Error codes.

Restart the backend, then press Test connection on the Provider screen. It makes one real call. A green result means the credential works, the model responds and the round trip is inside the timeout — not merely that a string is present.

3. Choose which provider is active

Setting the provider is Super-Admin only, and it is one of twelve keys that are. They are the ones that decide whether the assistant speaks to customers, what it may spend, and what it is allowed to do rather than say:

Key	What it decides
`aiSupportEnabled`	The master switch
`aiSupportAutonomy`	Draft, answer tickets, or answer everything
`aiSupportProvider`	Which AI service is active
`aiSupportDailyBudgetUsd` · `aiSupportMonthlyBudgetUsd`	The two spend ceilings
`aiSupportAccountToolsEnabled`	Whether it may read a customer's account at all
`aiSupportOperationsEnabled` · `aiSupportWorkflowsEnabled` · `aiSupportWorkflowKeys`	Whether it may act for a customer, and which actions
`aiSupportAdminAssistantEnabled` · `aiSupportAdminActionsEnabled` · `aiSupportAdminActionKeys`	The same pair for your own operator assistant

If you are not a Super Admin the fields are visible but greyed. They are shown rather than hidden on purpose: a switch you cannot find is a switch you assume does not exist.

The greying is what keeps a save from failing: the Settings screen writes as one batch, and a payload containing a key your role may not write is refused whole with a 403 rather than having the offending key dropped.

4. Create the persona

Configuration → Agents → Create default agent. One click writes a working persona: a name, a tone, the model, and the disclosure line that tells a customer they are talking to an assistant.

An agent is optional and the engine falls back field by field, not row-or-nothing: with no agent at all the assistant answers as "Assistant" and still carries a disclosure — "You're chatting with an AI assistant. It can look up your account and point you to the right page. It cannot move funds, change your account, or approve anything. Ask for a person any time."

Disclosure is not optional and cannot be switched off; only its wording is yours. So the fallback is safe, not silent — it is simply anonymous, and an assistant with no name and a generic notice is the worst version of this product to put in front of your customers. The button exists so nobody has to start from a blank textarea.

The same field-by-field fallback is why a half-configured agent is safe too: a persona named with no disclosure text written still gets the default notice rather than a named assistant with nothing attached.

Only the oldest active agent ever answers. Creating a second one does not create a second voice; the create-default route refuses outright if an agent already exists. See Agents.

5. Give it something to answer from

This is the step that decides whether the addon looks like a product or a demo.

The documentation shipped with the platform describes the software. It says nothing about your withdrawal fees, your KYC tiers, the countries you serve or how long your payouts take — which is what support tickets are actually about. On a fresh install, a correctly-built assistant escalates almost everything, and the honest conclusion an operator draws is that the addon does nothing.

Knowledge → Sources opens on a list of seeded questions covering exactly those gaps. Answering them is what converts the install. See Knowledge.

6. Switch it on, in copilot

Turn on the master switch with autonomy left at COPILOT. The assistant now drafts replies and your agents press Send. Nothing reaches a customer that a person has not read.

Watch it for a while on your own tickets, then read Autonomy before promoting it.

Upgrading

Update the addon the way you update any other, then do one extra thing.

Settings survive an update. The knowledge index does not always. If the documentation packs changed in the release, re-index from Knowledge → Sources — otherwise the assistant keeps answering from the previous release's text, which is the failure mode that looks like nothing at all until a customer is told about a screen that no longer exists.