Build An Assistant That Acts, With Permission
This guide builds an Assistant that works in another system for you — looking things up freely, but asking before it changes anything. In this example we will build Sales Helper, which finds contacts and companies in HubSpot and asks before it creates a record or replies to a customer. The same approach works for any Connector.
By the end of this guide you will have an Assistant that only the sales team can use. It will read HubSpot without interrupting anyone, and stop to ask before anything that writes to HubSpot or reaches a customer.
Before You Start
You will need the following:
- The HubSpot Connector is installed and has its key. Follow HubSpot — it covers creating the HubSpot service key and adding it in Optima. That needs the Optima Connectors permission.
- You are an Assistant Admin. Only an Assistant administrator can give an Assistant an Optima Connector.
- A chat model that handles tools well is running. Most current models do — Qwen, Llama 3.1 and later, Mistral and Hermes among them.
Warning
Everyone who can use Sales Helper acts in HubSpot through the same key. Give the HubSpot service key only the scopes the Assistant needs. To keep it read-only, leave out the write scopes, as the HubSpot page explains.
1. Create The Assistant
- Open Assistants and click New Assistant.
- Enter a Name — Sales Helper — and a Description for people: Looks up and updates contacts, companies and deals in HubSpot.
- Choose a Model and click Create.
2. Write Its Instructions
The instructions tell the Assistant what it is for and how careful to be. On the Behaviour tab, under Instructions, enter something like the following:
You are Sales Helper for Example Ltd's sales team. You look up and update
contacts, companies and deals in HubSpot.
- Always search HubSpot before creating anything, to avoid duplicates.
- When you are asked to create or change a record, say exactly what you will
create, then do it.
- Never reply to a customer unless you are asked to. Show the reply you will
send first.
- If a search finds nothing, say so. Do not invent contact details.
Click Save.
3. Give It HubSpot, And Choose What Must Ask
Next, give the Assistant the HubSpot Connector, and choose which of its tools must ask permission first.
- Open the Tools tab. Under Optima connectors, tick HubSpot.
- Leave All tools, including ones added later.
- Click Ask permission before specific tools… and tick every tool that changes something in HubSpot: those that create contacts, companies, deals and tickets, log notes, reply to conversations and post comments. Leave the tools that find, list and read unticked.
- Click Save.
Lookups will now run straight away. Anything that writes to HubSpot will pause the conversation until the person allows it.
Tip
Ask first, or everything? Tick The assistant must ask permission to use this connector instead to ask before every HubSpot tool, lookups included. That is safer while people are learning, but most teams find it tiresome for searches. Asking before writes is a good balance.
4. Choose Who Can Use It
On the Access tab:
- Under Available in, tick Chat. Leave API off — see Where it works.
- Give access to the sales team: search for each person and add them.
- Click Save.
Keep HubSpot To The People You Chose
An Optima Connector has no list of people of its own. Anyone who chats with a model directly, without an Assistant, can use every Optima Connector — HubSpot included. To make Sales Helper the only way to reach HubSpot:
- Open Settings → Assistants.
- Turn on Only allow assistants.
People can then chat only through the Assistants shared with them, and only the sales team has the one with HubSpot. Assistant administrators keep direct access. See Who Can Use Connectors.
5. Try It
In Optima Chat, choose Sales Helper and ask:
- Find the contact jane@example.com. — this will run without asking.
- Create a contact for Sam Patel at Northwind, sam.patel@northwind.example. — the conversation will pause and show what the tool would send.
The person can then choose one of the following:
| The person clicks | What happens |
|---|---|
| Allow | It runs this once. Sales Helper asks again next time |
| Allow for this conversation | It runs, and does not ask again for that tool in this conversation |
| Deny | It does not run. Sales Helper is told, and carries on without it. A reason typed in the box first — such as use the company domain instead — is passed on |
See Using Tools.
Where It Works
Tools that must ask are only offered in Optima Chat, where someone is there to answer. On the API and in Scheduled Tasks nobody can, so Sales Helper does not get those tools there: it can still look things up, but cannot create or reply. That is deliberate. If an integration needs to write to HubSpot without a person, give it a separate Assistant, with only the tools it needs and nothing set to ask.