Giving an agent access
On this page
Nine times out of ten, “the integration isn’t working” means it was connected but never attached — or attached but never mentioned in the instructions. This short page prevents both.
Why this is separate
Connecting HubSpot tells Vociply that your HubSpot exists and that it may act on your behalf. It does not decide which agents may use it. That is a second, deliberate choice.
The separation is worth having. Your inbound receptionist probably should look callers up in the CRM. Your outbound collections agent probably should not be able to create deals. Same connection, different permissions.
Attaching an integration
Open the integration
Integrations, click the connected app to open its panel.
Choose the agents
Select which agents get access. Grant it only to agents that genuinely need it — an unused integration on an agent is one more option for it to weigh on every turn, which costs a little speed and a little focus.
Save
The agent now has an action available on calls. It will not use it yet, because nothing has told it when to.
Telling the agent when to use it
This is the step that turns capability into behaviour. In the agent’s instructions, name the action and give the trigger.
You have access to our CRM and calendar.
At the start of every call, use search_contacts with the caller's number to see whether we already know them. If you find them, greet them by name and do not ask for details we already hold. Before offering any appointment time, use check_availability. Never offer a slot you have not checked. After booking, use create_note to log what was agreed on their contact record. If a lookup fails, do not guess — say you'll confirm by email and take their address.
| Write this | Not this |
|---|---|
| “Use search_contacts with the caller’s number at the start of every call.” | “Check who is calling.” |
| “Use check_availability before offering any time.” | “You can see the calendar.” |
| “Use create_deal only when the caller confirms they want a quote.” | “Create deals when appropriate.” |
| “If the lookup fails, take their email and say we’ll confirm.” | Nothing about failure at all |
check_availability is unambiguous. “Look at the calendar” could mean three things. The action names are listed on each integration’s panel — use them verbatim.
How the names are formed
Each connected app becomes one tool named execute_<app> — execute_hubspot, execute_google_calendar, execute_slack — and the actions on its panel are the things that tool can be asked to do. Writing the short action name in your instructions is usually enough; use the full execute_slack with action send_message form when two apps share an action name, or when an integration action collides with a call-control tool.
Proving it works
Do not assume. Prove it in three minutes:
- Set up the data first. Put yourself in the CRM as a contact, or block out your calendar so there is something real to find.
- Test-call the agent and drive it straight at the integration — “what have you got free on Thursday?”, “do you have me on file?”
- Check the other side. Did the appointment actually appear in the calendar? Did the note land on the right contact? An agent saying it did something is not evidence it did.
- Read the transcript in Call History. A short pause where the lookup happened is the sign it genuinely went and checked.
When the lookup fails
Integrations fail occasionally — an API is slow, a token expired, a record is missing. What matters is what the agent does next, and by default it will improvise. Tell it not to.
If any lookup fails or returns nothing, never guess. Say you'll confirm and follow up, take their contact details, and continue the call politely.
| Symptom | Likely cause | Fix |
|---|---|---|
| The agent never uses the integration | No trigger in the instructions | Name the action and the moment to use it. |
| “I don’t have access to that” | Connected but not attached to this agent | Attach it on the integration panel. |
| Works on one agent, not another | Attached to only one | Attach it to both. |
| Worked yesterday, not today | Credentials expired or were revoked | Reconnect the app — ideally as a service account. |
| It books at times that are not free | Availability is never checked | “Use check_availability before offering any time.” |
| It creates duplicate contacts | It creates without searching first | “Always search_contacts before create_contact.” |
Attachment questions
Can I give an agent read access but not write?
Not per-action within an integration — attaching gives the agent the integration’s actions. Control it with instructions (“never create a deal; only log notes”), and where the provider allows it, connect with a read-only key, as WooCommerce does.
How many integrations should one agent have?
As few as the job needs. Two or three is typical for a good agent. Six is usually a sign the agent is doing several jobs and should be split — see Agents.
Does attaching an integration slow calls down?
Having it available costs almost nothing. Using it costs a second or two while the other system answers. Cover it in the instructions — “say ‘let me check that for you’ before looking anything up” — and callers barely notice.