HubSpot CRM Setup

Overview

This guide walks you through connecting HubSpot to VeloPBX via the Public Legacy App OAuth flow. You’ll register a private app in HubSpot’s Developer Console, copy its credentials, and authorize VeloPBX to access HubSpot data on your behalf.

Setup time: ~10 minutes. Tenant admin only.

By the end of this guide, every inbound and outbound call placed by extensions in your tenant will:

• Match against contacts and companies in HubSpot
• Pop the matched record in PortSIP ONE before the call connects
• Auto-log a call activity (with recording and optional AI transcript) on the matched contact or company

Prerequisites

Before you start, make sure you have:

• A HubSpot Developer account (free at developers.hubspot.com — separate from your regular HubSpot user account)
• A regular HubSpot user account in the production HubSpot org you want to connect to (this is who will authorize the app, not the developer account)
• Tenant Admin Full Access in VeloPBX
• Browser access to both HubSpot Developer Console and your VeloPBX Web Portal at the same time

Important: The HubSpot user who authorizes the connection must be a real user in your HubSpot account, not the developer account that creates the app. This is HubSpot’s design — the app belongs to the developer, but the data permissions belong to the user.

Step 1 — Sign into the HubSpot Developer Console

Open https://developers.hubspot.com/ in a new browser tab and sign in with your HubSpot Developer account.

Step 2 — Create a new Public Legacy App

1. In the left navigation panel, select Legacy Apps.
2. Click Create legacy app.
3. Choose Public as the app type.

Why “legacy”? HubSpot has two app frameworks. The PortSIP/VeloPBX integration uses the legacy public app framework because it’s the format HubSpot supports for OAuth-based phone integrations today.

Step 3 — Fill in App Info

In the App Info tab:

• Public app name: VeloPBX Integration (or any name your team will recognize — this shows up to users when they authorize)
• Description: optional — e.g. “VeloPBX click-to-call and auto-log integration”
• Logo: optional but recommended

Save the App Info tab before moving on.

Step 4 — Set the Redirect URL

The Redirect URL is where HubSpot sends the authorization code back after a user grants access. It must match exactly what VeloPBX expects.

For your tenant, the Redirect URL is:

https://pbx.fortis-tele.com:8887/api/auth/callback/hubspot

Replace https://pbx.fortis-tele.com:8887 with your actual VeloPBX admin URL (visible in the URL bar when you’re signed into the Web Portal).

Important: The URL must include the port (typically :8887 for self-hosted, or whatever port your VeloPBX instance uses). It must use HTTPS, and the protocol/host/port/path must match exactly — no trailing slashes, no query strings.

Paste the Redirect URL into the Redirect URL field in HubSpot’s App Info tab and save.

Step 5 — Add the required Scopes

In the Scopes section, add all five of the following permissions:

CRM scopes:

• crm.objects.contacts.read
• crm.objects.contacts.write
• crm.objects.companies.read
• crm.objects.owners.read

Other:

• timeline

Why these scopes? contacts.read/write lets VeloPBX match incoming calls against contacts and create new ones from PortSIP ONE. companies.read lets VeloPBX match calls to corporate accounts. owners.read is used to attribute call activities to the right HubSpot user. timeline is required to write call activities to the contact/company timeline.

Save the Scopes tab.

Step 6 — Generate and copy the Client ID and Client Secret

1. Click Create App (or Save & Continue depending on the HubSpot UI version).
2. HubSpot generates a Client ID and Client Secret for your app.
3. Copy both values immediately to a secure location.

Important: Treat these as production credentials. Anyone with the Client ID + Client Secret + your tenant’s Redirect URL can impersonate the integration. Store them in your password manager. If you ever suspect leakage, regenerate them from the same screen and re-paste into VeloPBX.

Step 7 — Open Integrations in VeloPBX

In a new browser tab, sign into the VeloPBX Web Portal as a tenant administrator at:

https://pbx.fortis-tele.com:8887

In the left navigation, click Integrations, then CRM.

Step 8 — Select HubSpot and paste credentials

1. From the Select a CRM solution dropdown, choose HubSpot.
2. The HubSpot configuration form appears.
3. Paste the Client ID and Client Secret you copied in Step 6 into the corresponding fields.
4. Below the credential fields, configure the integration settings (see next section for recommended defaults).
5. Click Save.

VeloPBX stores the credentials but the integration is not active yet — you still need to authorize it.

Step 9 — Authorize the app

1. After saving, an Authorize button appears.
2. Click Authorize. A new browser tab opens with HubSpot’s authorization screen.
3. Sign in with the regular HubSpot user account you want to grant access (the one in your production HubSpot org).

Critical: Do not sign in with the developer account that created the app. HubSpot will appear to authorize successfully but the integration will not be able to read or write production CRM data.

1. Review the requested permissions — they should match the five scopes you added in Step 5.
2. Click Connect app.
3. HubSpot redirects back to VeloPBX. The integration becomes active immediately.

Step 10 — Configure integration settings

Recommended defaults for the toggles below the credentials:

Save your settings.

Verify it works

1. Place an outbound call from any extension in your tenant to a phone number that exists in your HubSpot contacts.
2. The matched contact should pop in PortSIP ONE during the call.
3. After the call ends, open the contact in HubSpot:

• Activity tab should show a new Call entry with duration, direction, and outcome.
• If recording is enabled, the activity has a recording link or playback widget.
• If AI transcription is enabled at the tenant level, the transcript appears below the recording.

Settings reference

Once connected, all settings can be edited any time on Integrations → CRM → HubSpot at https://pbx.fortis-tele.com:8887. Changes take effect on the next call.

Troubleshooting

“Authorization failed — redirect URI mismatch”

The Redirect URL in HubSpot must match what VeloPBX sends, byte-for-byte. Common causes:

• Trailing slash mismatch (/callback/hubspot/ vs /callback/hubspot)
• HTTP vs HTTPS
• Port number missing or wrong
• Different host (e.g. portal.example.com vs pbx.example.com)

Fix the Redirect URL in HubSpot Developer Console App Info tab and re-authorize.

“Authorization succeeded but no data”

You signed in with the developer account during Step 9 instead of a real HubSpot user account. The integration appears to be authorized but cannot read/write production data.

Fix:

1. In VeloPBX, click Disconnect on the HubSpot integration.
2. Sign out of HubSpot completely (developer + user accounts).
3. Repeat Step 9, this time signing in with a real HubSpot user account in your production org.

Calls aren’t matching contacts

• Verify phone numbers in HubSpot are stored in E.164 format (e.g. +37491223344).
• Check Contact lookup order — if your records are mostly Companies but the lookup order is Contacts first, expand to include both.

“Pro plan required” error in HubSpot

HubSpot’s Calling Provider features (the click-to-call piece) require Sales Hub Professional or higher. Free / Starter tiers can still receive screen-pops on inbound, but click-to-call from the HubSpot UI requires the paid tier.

VeloPBX itself doesn’t require a HubSpot Pro plan — only the click-to-call-from-HubSpot-UI feature does. All other features (caller ID match, screen-pop, auto-log, recording) work on free HubSpot.

Activities are duplicated

Confirm only one PBX tenant is connected to your HubSpot org with the same Client ID. If two PBX tenants share the same HubSpot, each will write its own activity entry. Either consolidate to one tenant or use different HubSpot orgs.

FAQ

Can multiple VeloPBX tenants connect to the same HubSpot org? Yes — each PBX tenant registers its own HubSpot legacy app with its own Client ID/Secret. They write activities under the user account that authorized them, so you can tell which tenant logged which call.

What happens if the authorizing user leaves the company? The OAuth refresh token tied to that user becomes invalid when their HubSpot account is deactivated. The integration breaks. Fix: reconnect with a different active user (Step 9 again).

Can I rotate the Client Secret without losing data? Yes. Generate a new secret in HubSpot Developer Console, paste it into VeloPBX, click Save. Existing logged activities are not affected. Future calls use the new secret.

Do I need separate apps for sandbox and production HubSpot? Yes — HubSpot’s sandbox environments require their own legacy app and authorization. Use a separate VeloPBX tenant (or a separate connection within the same tenant) for sandbox vs production.

Are AI transcripts billed by VeloPBX? No — AI transcription uses your own Azure Speech / OpenAI / AWS Transcribe credentials (configured separately under Tenant → AI Transcription). VeloPBX does not mark up cloud AI costs.

Need help?

If you get stuck, talk to a routing engineer — we can pair on the OAuth flow live and have your first matched call running within 24 hours.