AI assistance

Scoring, triage, drafting and summaries — using your own provider and your own key.

Connecting a provider

Settings → AI assistance. This is the screen on an install that runs one business. On a SaaS install the provider belongs to the super admin, and a workspace sees a smaller page, or none — see On a SaaS install.

Enter your key, switch it on, press Save, then Test the connection. It asks the provider for one short answer and tells you what came back: Connected — (model) answered, or the provider's own reason for refusing. A failed test is not recorded as a fault. Opening the page needs permission to view settings; saving, testing and disconnecting need permission to edit them.

Disconnect, beside the test button once a key is stored, removes the key, switches AI assistance off and deletes every answer already stored against a record, after you confirm. The usage figures are kept.

What it does

Each panel has one button — Score it, Summarise and so on — and Again once there is an answer, to ask afresh. Scores, triage and summaries are kept against the record, so opening the page again shows the last answer without another request. Pressing a panel needs Use the AI features and the record's own permission (viewing a lead to score it, editing tickets to triage or draft).

The assistant

The round Ask AI button in the bottom corner of every screen opens the AI Assistant panel over whatever you are looking at; ⌘K (Ctrl+K on Windows and Linux) opens and closes it too, and Esc closes it. Hover the button and up to six quick starters fan out above it — Summarise this (only on a screen about a record), Leads update, Unpaid invoices, Open tickets, New invoice, New lead, New task and My week, less any the person's role does not allow. Click an update and the panel opens with that question already asked; click a New one and it opens with the start of the sentence in the box.

Type in Message the assistant... and send. The panel's header has four buttons: Recent conversations, New conversation, Expand (a larger panel for a long answer) and Close. The green dot beside the title means a provider is connected and the assistant is ready. The last few turns travel with each new question — which is what makes it a conversation rather than a series of unrelated requests. On a phone it takes the whole screen.

It keeps your conversations, so a question worth asking once is one you can come back to. Recent conversations lists your last thirty, newest first, with the agent that ran each one. Click one to open it where you left off; the button beside it deletes it after you confirm.

The opening screen groups one-click actions under Get an update (leads, unpaid invoices, proposals and estimates, contracts, open tickets, goals, your week, attendance and leave), Create (an invoice, estimate, proposal, contract, lead, customer, task, project, calendar event, expense, item, subscription, campaign, message template, announcement, survey or goal) and Write. An update asks straight away. A Create action puts the start of the sentence in the box — "Create an invoice for " — for you to finish. Each one appears only for people whose role allows it.

They live in config/ai.php under starters, and launcher chooses the six that fan out beside the button. Agents your business writes appear under Your agents.

Open it from a lead, a customer, a ticket or a project and that record is put in front of the model, described exactly as the summary feature describes it. Open it from anywhere else and it is a general assistant.

What the assistant can do with your data

Once a provider is connected, the assistant can read your records and prepare new ones — always as the person asking, and only what their role allows on screen.

It can also prepare: a reply to a ticket; a new item, expense, subscription, lead, customer, proposal, estimate, contract or invoice; a project, task, campaign, message template, staff announcement, survey or goal; and a calendar event.

Anything else in the CRM

Beyond those, the assistant can do anything you can do in the CRM admin: read any list or record, and change, move, approve, send or delete anything your role allows — "mark the most recent open lead as lost, they went with a competitor", "add a note to Bluewater: they want a quote by Friday", "create a ticket department called Billing". It finds the action among everything the CRM admin can do, looks up the record it is about, and prepares a card. The card's title is the product's own description of the action, not the model's words, and names the records it touches.

A few things the assistant does not do, each on purpose: reading out a vault password or a token's secret (they would go to the AI provider), uploading or downloading files, exports and PDFs (it has no way to attach a file, and a download is for you rather than a model), installing plugins or updates, and anything to do with AI itself. Ask for one and it says so.

Say what you want in your own words — "invoice Northwind for ten hours of consulting at 120, due in two weeks". Names are matched to the customers, leads, staff and statuses you can see; when a name could mean two things, the assistant asks. Anything left out gets the screen's usual default rather than a question.

With contact details taken out (the default), an email address or phone number you type reaches the provider only as a marker such as [email 1]. The card and the saved record carry the real one.

Models differ in what they accept. Some of OpenAI's newer ones refuse the usual max_tokens, a temperature other than their default, or tools without their reasoning switched off; Zenta reads the refusal, adjusts the request and remembers the adjustment for that model, so nothing needs configuring.

A conversation belongs to the person who started it. There is no permission that opens a colleague's, on purpose: one that could be read by a manager is one nobody would use for the questions the assistant is most useful for.

Things to try

Plain sentences work best. These are the kind of questions it answers well; the names are examples — use your own customers and colleagues.

A few habits get better answers:

• Open it from the record. On a customer or ticket, "this" means that record, so you need not name it.
• Relative dates are fine. It knows today's date, so Friday, tomorrow and in two weeks all work, in your own timezone.
• Leave out what you do not care about. Anything you do not mention gets the screen's usual default.
• Read the card before you press Confirm. It shows exactly what will be saved. If something is wrong, press Cancel and say what to change — "make it 150 an hour" — and it prepares a new card.
• Start a new conversation for a new subject. The last few turns go with every question, so an old subject can colour the answer to a new one.

What it answers still follows your role: if you cannot open invoices, it cannot tell you about them either.

Agents you write yourself

Settings → AI assistance → Agents. The features above cover what every business wants. An agent covers what one business wants: the house style, the triage rule nobody outside this desk would recognise, the second pair of eyes on a proposal before it goes.

The list shows each agent with its description, the handle rules and reports use, where it is offered (The assistant only, or the kinds of record) and how many conversations it has run. Provider settings goes back to the AI settings. Writing agents needs the Write agents permission; on a SaaS install the page exists only for a workspace given its own AI settings.

New agent opens the form; click an agent's name to edit it. Press Save agent.

Renaming an agent never breaks anything: behind the name is a fixed handle, shown on the list, and that is what anything written against it holds on to. Delete, on an agent's form, removes it after you confirm and keeps the conversations it ran — what was said is what somebody may have acted on.

Who may use it

AI assistance is a permission module of its own, with three abilities, so a business can give it to the people it is for and leave it off for everybody else:

There is also a restriction, alongside "only these customer groups" and "only these project categories": only these AI agents. An agent that answers from the pricing sheet is not one everybody needs. Tick the agents under the AI module's restrictions on a role, or on one person's own permissions; nothing ticked means every agent.

On upgrade, every role that already existed is given use and chat — which is exactly what it could already do, since the AI buttons used to ask only for the record's own permission. Writing agents is not granted: that is new, and it is an administrator's job.

Inside your automations

This is the part worth setting up. Four of the actions in the automation builder are AI steps:

A model behind a button needs somebody to press it. A model inside a rule reads every lead that arrives at three in the morning.

The triage step applies nothing unless you tick the boxes that let it. Left alone, it writes what it found as a private note and changes nothing.

Privacy

Take contact details out before sending is on by default. Email addresses, phone numbers, card numbers and IBANs are replaced with markers such as [email] before anything leaves your server. The sentence still reads, and the model can still tell that a customer gave a number.

Two more things worth knowing:

• Private staff notes are never sent to the drafting prompt. An aside written for colleagues should not come back, paraphrased, in the answer the customer reads.
• The usage log holds no prompts and no answers — only how many tokens went where. A log that archived every customer email sent to a third party would be a bigger liability than the feature it was measuring.

Disconnect removes the key and deletes every answer already stored against a record.

Cost

You pay your provider directly, at their prices. Two things keep the bill down:

• Answers are cached against the record. Opening a lead twenty times costs one request. Editing the lead is what makes it worth asking again — nothing else does.
• A monthly token allowance. Once it is used up, requests stop until the new month. Tokens rather than money, because nothing here can read your provider's prices. Set it to 0 for no limit.

Usage for the current month is broken down by feature at the bottom of the settings screen.

On a SaaS install

When the install runs as a platform for other businesses (TENANCY_ENABLED=true), AI works differently, because every request is paid for by whoever holds the key. The super admin's screens are described in full under Tenant admin → AI assistance and AI problems; in short:

• The super admin connects the provider, under Tenant admin → AI assistance: the provider, the address, the model, the key, which features exist and whether contact details are taken out. There is one connection for the whole platform. The key is stored encrypted and is never shown again, to anyone.
• A workspace has no AI until the super admin switches it on for that workspace. The same screen lists every workspace with three settings: AI (the Ask AI button and every AI feature, for the people their roles allow), Own settings (see below) and a monthly limit in tokens — blank for no limit. The same card is on each workspace's own page under Workspaces. A plan does not decide this: AI is left out of a plan's list of modules on purpose.
• The platform's own workspace always has AI, so the super admin can use the assistant from their workspace. The tenant admin panel has an assistant of its own for running the platform (see AI assistance).
• A workspace's administrators see no AI settings by default. Tick Own settings and they get a Settings → AI assistance page of their own, different from yours: it shows the model and how much of the month's allowance is gone, lets them switch features off within what you allow, lets them take contact details out when you do not, and opens Agents. It never shows the provider, the address or the key, and it cannot switch on anything you switched off. It has no connection test and no Disconnect.
• Usage is counted per workspace. The tenant admin screen shows each workspace's tokens this month and the platform's total. A workspace that reaches its limit is told so and stops until the first of the next month; nobody else is affected.

Changing the wording

Every prompt is in config/ai.php, not buried in a class — your idea of a good lead is not ours. Edit them freely; the placeholders in each one are filled from the record.

If it stops working

Every failure is recorded in the usage table with the reason, so a run of them is visible rather than silent.

What the assistant will talk about

The assistant answers about Zenta CRM and the work done in it: your leads, customers, documents, projects, tickets, marketing, calendar, staff and leave; how to use the application; and drafting or summarising messages about that work. Any other question — general knowledge, coding, homework, entertainment, other software — is answered with "Ask me anything related to Zenta CRM". The rule is added after every agent's own instructions, so an agent cannot widen it. The name in the sentence is name in config/zenta.php.

When something breaks

A person using the assistant is told in words about anything they can act on — AI is switched off, the month's allowance is spent, the question was empty, a field on a proposed record is invalid. Anything they cannot act on is a fault, and all they see is "There's any issue. Please contact support". Faults are:

• the provider refusing the key, rate limiting, being down or unreachable;
• an answer that is empty or cannot be read;
• an assistant tool, or a confirmed action, throwing an exception;
• any other uncaught error on an AI screen or endpoint.

Each fault is:

• logged at error level in storage/logs, with the exception;
• kept under Tenant admin → AI problems — the real message, where in the code it happened, the workspace and person, how many times, and the stack trace. The same problem is one row with a count, so an hour-long outage is one entry rather than hundreds;
• sent to every super admin, in their notification bell and by email, the first time it is seen. It is not sent again unless it comes back after you press Mark as fixed, when it reopens.

The Test the connection buttons are the exception: they show the provider's real answer, and a failed test is not recorded as a fault. Automation steps that use AI log the same one-line message in the rule's history.

Addresses on this page

For reference and for anyone scripting against the panel. Everything here needs somebody signed in to the workspace whose role allows it; anybody else is refused.