HubSpot

Connect HubSpot to NextSay

NextSay reads the open deal before each call — contact, deal, stage, next step — in Copilot and Intel, and, if you allow it, logs a one-line read of the call back onto the deal afterward. You control the direction; NextSay never sees your password.

Set up once, by an admin. The connection is workspace-wide — your other members just get the features (contact search, live deal context, auto-logged calls) and never touch any of this. Plan ~15 minutes.

Before you start

A HubSpot admin

Creating the app (Step 1) needs access to HubSpot's developer tools (Projects).

A NextSay workspace admin

Connecting is admin-only in NextSay — and it's one-time for the whole workspace.

Node.js + the HubSpot CLI

Apps are created and uploaded with the CLI (hs). Install is Step 1.1.

1 · Create the app with the CLI

HubSpot retired UI app-creation on 23 June 2026 — apps are now made with the HubSpot CLI. Run these once. Each block is a single command; the file edit in 1.4 is edited in your editor, not pasted into a terminal.

Install the CLI (needs Node.js).
```
npm install -g @hubspot/cli@latest
```
Authenticate. This opens your browser to generate a Personal Access Key — paste it back when prompted.
```
hs account auth
```
Keep the key out of git. hs saves your Personal Access Key into hubspot.config.yml. Add that file to .gitignore (or keep it in your home folder) and never commit it.
Create the app. At the features checklist, select none — press Enter to submit (an OAuth API app needs no features). Replace <APP_NAME> with something like nextsay-hubspot.
```
hs project create \
  --name <APP_NAME> \
  --project-base app --auth oauth --distribution private \
  --platform-version 2026.03 \
  --dest ~/<APP_NAME>
```
Set the redirect URL + scopes. Open ~/<APP_NAME>/src/app/app-hsmeta.json in your editor and replace the two fields inside config.auth. Use the exact Redirect URL shown in NextSay's Set up dialog (production is https://nextsay.ai/app):
```
"redirectUrls": ["<REDIRECT_URL_FROM_NEXTSAY>"],
"requiredScopes": [
  "oauth",
  "crm.objects.contacts.read",
  "crm.objects.deals.read",
  "crm.objects.contacts.write",
  "crm.objects.deals.write"
]
```
Upload it.
```
cd ~/<APP_NAME> && hs project upload
```
Copy the keys. Open the app, then in HubSpot go to Project components → your app → Auth and copy the Client ID and Client secret (the Auth page also shows the redirect URL and scopes you set — a good cross-check).
```
hs project open
```

Deeper CLI detail (auth, marketplace distribution): Create an app with the CLI · OAuth quickstart · Scopes

2 · Connect in NextSay

Settings → Integrations → HubSpot → Set up.
Paste the Client ID and Client secret from Step 1.6, then Save.
Connect. You approve on HubSpot's own page and pick the account to install into. NextSay stores only the returned token, server-side — never your password.

The Redirect URL in the Set up dialog must match what you put in app-hsmeta.json byte-for-byte, or HubSpot rejects the connection with a redirect mismatch.

3 · Choose the sync direction

On the connected card, set the Sync switch (you confirm before it changes).

Inbound only

Reads context from HubSpot; never writes back.

Bidirectional

Also logs a call activity onto the matched deal. There is no outbound-only — writing includes reading.

What's synced & to which object

Reads (live, never copied) — fetched when you pick the prospect, used for the call, not stored:

Contact	name, email, company, job title
Deal (associated)	name, stage, amount, close date, next step

Writes (only when Sync = Bidirectional) — one object:

Call activity	on the contact and its deal — a one-line read + the single top ⚠ Risk + a pull-link back to NextSay.

Never written: HubSpot-owned fields — deal stage, amount, close date, next step. The full read, transcript, and signals stay in NextSay, linked not copied. The write is self-healing, idempotent (a retry never duplicates), and the deal link is best-effort.

Integration status

A session's Details tab shows the CRM sync state:

Success	The read was logged — tap it to open the record with the call in its timeline.
Pending	The log is in flight.
Failed	It didn't log — the saved error shows inline (expand it); Retry re-runs it.
Not synced	CRM-linked but nothing logged yet (e.g. Inbound-only) — opens the contact.

Searching for a prospect

Everywhere you start a call — Prospects, Copilot setup, Role Play — the picker searches HubSpot live:

Live search

Type a name or email; results come straight from HubSpot, nothing stored.

Enter manually

Always offered for anyone not in the CRM.

More than one CRM

A compact source dropdown picks which to search; a picked prospect logs back to the CRM it came from.

Where it shows up

Prospects

Search HubSpot contacts; "View in HubSpot" on any saved prospect.

Session detail

Sync status in the header (opens the call); "Sync to HubSpot" in the ⋮ menu.

Copilot & Intel

Live deal state rides along as context.

Security

NextSay never receives your password.

Tokens server-side

Stored on our servers, never in your browser; refreshed automatically.

Admin-only, reversible

Only admins connect or change sync; disconnect any time.

FAQ

Do all users have to set this up?

No. An admin connects once; the connection is workspace-wide. Other members just get contact search, deal context, and auto-logged calls — they never repeat the setup or see any keys.

Does NextSay change my HubSpot records?

No. It only adds a Completed-call activity; it never edits fields HubSpot owns (deal stage, amount, close date).

Where is a call logged, and could it duplicate?

As a completed Call activity on the matched contact and its deal. One per call — it updates in place, never duplicates.

Can I keep NextSay read-only?

Yes. Set Sync to Inbound only.

Do you copy my HubSpot data into NextSay?

No. Fields are read live; NextSay stores only a reference, never a mirror.

Does NextSay see my HubSpot password?

No. You sign in on HubSpot; NextSay gets only a token, kept server-side.

Private app or public app?

A private app (as above) connects NextSay to your own account — ideal for a single workspace. A public/marketplace app is only needed to distribute one app across many customer accounts.

What happens to logged calls if I disconnect?

They stay in HubSpot. Disconnecting only stops future reads and write-backs.

Troubleshooting

Redirect URL mismatch

The app's redirectUrls doesn't match NextSay's exactly. Copy it from the Set up dialog, fix app-hsmeta.json, and re-run hs project upload.

Missing-scope error

A required scope isn't on the app. Add the four crm.objects scopes (keep oauth) and re-upload.

hs project create seems stuck

It's the interactive features checklist — select none and press Enter.

Config edits did nothing

Don't paste the JSON into a terminal — edit the file src/app/app-hsmeta.json, then hs project upload.

"Inbound-only" on log

Sync is Inbound only. Switch to Bidirectional.

Note only shows a link

A very short call synced before its read existed. Open the session once and it fills in.

Disconnect

Settings → Integrations → HubSpot → expand → Disconnect. Reads and write-backs stop immediately; your HubSpot data is untouched, and you can reconnect any time.