Setup Guide
Call Agent AI for HubSpot
Call Agent AIis an inbound & outbound AI voice agent. This guide walks through installing the HubSpot integration, configuring it, the permissions it requests, the data it shares, and the day-to-day user journey — so you know exactly how it works before you install.
What this integration does
- Matches every inbound and outbound call to the right HubSpot Contact by phone number.
- Logs each conversation to the contact's timeline (call activity + an optional AI summary note).
- Powers outbound calling campaigns sourced directly from your HubSpot Lists.
- Writes call outcomes back to the HubSpot contact properties you choose.
1. Prerequisites
| Requirement | Details |
|---|---|
| Call Agent AI account | Sign up at admin.callagentai.com. A paid plan or active trial is required to place/receive calls. |
| HubSpot account | Any Sales/Service hub tier that allows contacts, lists, and engagements. |
| HubSpot permission | You must be a HubSpot user with Super Admin (or App Marketplace install) permission to authorize the app. |
| At least one assistant | Create an inbound or outbound AI assistant first — HubSpot is connected per assistant. |
2. Installation — connect HubSpot
- Log in to admin.callagentai.com.
- Open the assistant you want to connect (or create one) and go to Integrations → HubSpot.
- Click Connect HubSpot. You'll be redirected to HubSpot's authorization screen.
- Choose the HubSpot account (portal) you want to connect and review the requested permissions (see below).
- Click Connect app. HubSpot redirects you back to Call Agent AI and the integration shows Connected, with your portal name.
The connection uses HubSpot OAuth 2.0. Call Agent AI stores only the OAuth access/refresh tokens and your portal ID — never your HubSpot password. You can disconnect anytime from the same panel, which revokes the token with HubSpot.
3. Configuration
Caller lookup (inbound & outbound)
Call Agent AI looks up the caller/callee by phone number against your Contacts. If no contact is found on an inbound call, you can enable “Create contact for unknown callers” so a new contact (lifecycle stage lead) is created automatically.
Activity logging
Log calls — each call is written as a HubSpot Call activity on the contact timeline with direction, duration, status, the numbers involved, and (if available) a recording link. Log a summary note — optionally attach a Note with the AI-generated conversation summary.
Outbound campaigns from HubSpot Lists
When building an outbound campaign, choose HubSpot List as the source. Pick any active list; Call Agent AI reads its members and their contact properties (name, phone, mobile, company, email) to drive the calls.
Write-back of call outcomes (optional)
Map a call outcome (e.g. interested, callback requested, do not call) to a HubSpot contact property. Available properties are discovered live from your portal's contact property schema, so your custom properties appear in the picker.
4. Permissions (scopes)
Call Agent AI requests only the scopes it needs:
| Scope | Why it's needed |
|---|---|
crm.objects.contacts.read | Look up contacts by phone; read list members' properties. |
crm.objects.contacts.write | Create contacts for unknown callers; write call-outcome properties; log Call/Note activity to the contact timeline. |
crm.schemas.contacts.read | Populate the property picker used for outcome write-back mapping. |
crm.lists.read | List your HubSpot Lists and read their members for outbound campaigns. |
oauth | Standard OAuth token management. |
5. Data shared
| HubSpot object | Direction | What happens |
|---|---|---|
| Contacts | Sync from HubSpot | Read to match callers and source campaign members. |
| Contacts | Sync to HubSpot | Create contacts for unknown callers; update mapped properties; attach Call & Note activity. |
| Contact Lists | Sync from HubSpot | Read list membership to build outbound campaigns. |
| Contact Properties | Sync from HubSpot | Read property definitions for outcome mapping. |
6. Typical user journey
Inbound call
- A customer calls your Call Agent AI number.
- The AI agent answers and looks the caller up in HubSpot by phone number.
- If matched, the agent can greet by name and use known context; if not, a new contact is optionally created.
- When the call ends, a Call activity (and optional summary Note) is logged, and any mapped outcome property is updated.
Outbound campaign
- You create an outbound campaign and select a HubSpot List as the source.
- Call Agent AI dials each member in turn using the assistant's script.
- Each completed call is logged back to the matching contact with its outcome.
7. Troubleshooting
| Symptom | Resolution |
|---|---|
| “Connect HubSpot” loops back without connecting | Make sure you authorized the correct portal and have install permission; try again from the assistant's Integrations panel. |
| Calls aren't appearing on the contact timeline | Confirm the contact was matched by phone, and that Log calls is enabled in the assistant's HubSpot config. |
| A custom property isn't in the outcome picker | The picker reads live from your portal; refresh the page and confirm the property exists on the Contact object. |
| Campaign shows no members | Verify the selected list is active and contains contacts with phone numbers. |
| Connection stopped working | The OAuth token may have been revoked in HubSpot; reconnect from the Integrations panel. |
8. Support & uninstall
Questions? Email support@callagentai.com or visit our Help Center.
To uninstall, disconnect from Integrations → HubSpot in Call Agent AI, then remove the app from HubSpot → Settings → Connected Apps if desired.