HubSpot CRM Integration

Introduction


3CX provides integration with HubSpot via the 3CX API for CRM with the following features:

  • Caller ID to Contact Name – inbound calls trigger a HubSpot contact lookup.
  • Contact Lookup in HubSpot based on Name, Number or Email if you search for a name in the 3CX Webclient.
  • Call & Chat Journalling – calls and chats are logged in the HubSpot Contact Card as CRM call records.
  • Create a new HubSpot contact from the 3CX client for calls from new numbers.
  • Click to Call – launch calls straight from HubSpot via 3CX, using the 3CX Click2Call Browser extensions for Google Chrome and Microsoft Edge.

Configure HubSpot CRM with HubSpot CLI

HubSpot has discontinued the creation of new legacy Public Apps from the Developer Platform interface. New HubSpot apps must now be created using HubSpot's Projects framework and HubSpot CLI.

This guide explains how to create the HubSpot OAuth application required by the 3CX HubSpot CRM integration.

Note: Existing legacy Public Apps continue to function.

Step 1: Determine the 3CX OAuth Redirect URL

Before creating the HubSpot project, determine the public URL used to access the 3CX system.

For example, if the 3CX Admin Console is accessed through:

https://mypbx.3cx-example.com

...then the HubSpot OAuth redirect URL must be:

https://mypbx.3cx-example.com/api/oauth2crm

Step 2: Install the HubSpot CLI

The HubSpot CLI is a Node.js application, so Node.js with npm must first be installed.

HubSpot CLI 8 requires Node.js 20 or later.

  • Open a new Command Prompt.
  • In the Command Prompt, run:

npm install -g @hubspot/cli@latest

  • When the installation finishes, check the HubSpot CLI version:

hs --version

  • A HubSpot CLI version should be displayed.

Step 3: Sign In to HubSpot from the CLI

  • In the Command Prompt, run:

hs account auth

The CLI will guide you through authenticating your HubSpot account. Follow the prompts:

  • Give the HubSpot account a recognizable local name if requested.
  • A browser window will open, or the CLI will display instructions for opening HubSpot.
  • Sign in to the HubSpot account in which the project/application will be created.

  • Generate the requested Personal Access Key.
  • The key should be automatically returned to the terminal window.
  • If the CLI asks you to paste the Personal Access Key into the terminal, paste it and press Enter.
  • Enter an account name if prompted.
  • If you are asked whether this should be the default account, select Yes.

Step 4: Create the HubSpot OAuth Project

  • In the Command Prompt
  • Create a project folder, e.g.:

mkdir C:\HubSpotProjects

cd /d C:\HubSpotProjects

  • In this folder run:

hs project create --project-base app --distribution private --auth oauth

  • The CLI will ask for additional information.

  • Project name, example: "3CX HubSpot Integration"
  • Local folder, default  or use something simple such as: "3cx-hubspot"
  • Features
  • The 3CX CRM integration itself does not require a HubSpot App Card, webhook, workflow action, settings page, or other project feature. If the CLI asks you to choose features, leave all features unselected and continue by pressing Enter.

  • After the command completes, a new directory should exist, e.g.: "C:\HubSpotProjects\3cx-hubspot"
  • Change to that directory:

cd /d C:\HubSpotProjects\3cx-hubspot

  • The important files should include:

C:\HubSpotProjects\3cx-hubspot\hsproject.json

C:\HubSpotProjects\3cx-hubspot\src\app\app-hsmeta.json

Step 5: Configure OAuth and required scopes for 3CX

Open the following file in Notepad: "C:\HubSpotProjects\3cx-hubspot\src\app\app-hsmeta.json".

The generated file may contain additional properties that can be ignored; the important section is the application's config and particularly the auth section.

Configure the app with your distribution, requiredScopes and redirectUrls as shown below, replacing "https://pbx.example.com/api/oauth2crm" with the actual public 3CX URL determined in Step 1.

{

  "uid": "3CXHubSpotIntegration_app",

  "type": "app",

  "config": {

    "description": "OAuth application for the 3CX HubSpot CRM integration",

    "name": "3CX HubSpot Integration-App",

    "distribution": "private",

    "auth": {

      "type": "oauth",

      "redirectUrls": [

        "https://pbx.example.com/api/oauth2crm"

      ],

      "requiredScopes": [

      "oath",

           "crm.objects.contacts.read",

                "crm.objects.contacts.write",

                "crm.objects.companies.read",

                "crm.objects.owners.read",

                "timeline"

      ],

      "optionalScopes": [],

      "conditionallyRequiredScopes": []

    },

    "permittedUrls": {

      "fetch": [

        "https://api.hubapi.com"

      ],

      "iframe": [],

      "img": []

    },

    "support": {

      "supportEmail": "[email protected]",

      "documentationUrl": "https://example.com/docs",

      "supportUrl": "https://example.com/support",

      "supportPhone": "+18005555555"

    }

  }

}

Step 6: Validate and upload the Project to HubSpot

  • From the project directory, run:

hs project validate

  • If validation succeeds, continue.
  • If validation reports an error, correct the indicated JSON property and run the command again.
  • Then run:

hs project upload

  • The first time the project is uploaded, HubSpot may display a message similar to:

  • "The project does not exist in this account. Would you like to create it?"
  • Answer "Y" and continue.
  • The CLI will:
  • upload the files
  • create a HubSpot build
  • deploy the application

Step 7: Obtain the Client ID and Client Secret in HubSpot

  • In your browser login to your HubSpot and navigate to Development > Projects
  • Open 3CX HubSpot Integration (or the project name you created).
  • Under Project Components, click the application's name.
  • Open the Auth tab.

  • HubSpot will display the following Client credentials:
  • Client ID
  • Client secret
  • Copy both values somewhere secure.

Step 8: Add additional HubSpot CRM Accounts to the Private OAuth App (Optional)

This is an important new step compared with the old Public App procedure.

Because the project was created with "distribution": "private", HubSpot only permits OAuth authorization for accounts that have been explicitly approved. By default, only the account that created the App has access ("private").

In HubSpot:

  • Open Development.
  • Open Projects.
  • Open the 3CX project.
  • Under Project Components, select the 3CX application.

  • Open the Distribution tab.
  • Click Add approved account(s).
  • Under the available production accounts, select the HubSpot CRM account that contains the contacts and companies that will be integrated with 3CX.
  • If your HubSpot login has access to both a development account and the company's normal CRM account, make sure the CRM account containing the actual customer data is approved.
  • Click Save changes.

Configure and Authorize HubSpot in 3CX

  • Go to 3CX Admin Console > Integrations > CRM.
  • Select "HubSpot" from the dropdown list.
  • Select the desired Contact Lookup Order
  • Enter the OAuth values previously copied from your app for "Client ID" and "Client Secret".
  • Click Save
  • Click Authorize

  • A HubSpot authorization page should open.
  • Sign in to HubSpot if required.
  • Select the HubSpot CRM account containing the contacts and companies that should be used by 3CX.
  • Review the requested permissions.
  • HubSpot may warn that the application is unverified. This is expected for an application created for your own account and not submitted to the HubSpot Marketplace.
  • Confirm the installation/authorization.
  • 3CX now receives the OAuth authorization code and exchanges it for HubSpot OAuth tokens.
  • Verify the "Refresh Token" field is automatically filled for the HubSpot CRM in 3CX Admin Console.
  • If you want to enable contact creation from the 3CX client, check this option. When the caller’s number cannot be matched to a contact, the 3CX client will let the user create the contact by filling the details in a dialog.

Configure e164 Contacts and Caller ID

  • To get a match with HubSpot, the incoming Caller ID must be identical to the CRM entry, including any prefix, as HubSpot performs whole number lookups. Querying HubSpot using a subset of the digits, does not return any data.
  • To make HubSpot integration work, you must store the numbers in HubSpot using E164 format, and your SIP Trunk must provide the caller’s number in E164 format as well, so both match. If this is not the case, you can use Caller ID Reformatting to adjust the caller’s number before being passed on to the CRM.
  • Go to Admin > System > Phonebook > Options, set the matching strategy to "Match exactly" and click "OK".

Configure Call & Chat Journaling, including Transcription

  • To report external calls and chats to HubSpot, the email address configured for the 3CX extension must match the email address of a HubSpot user. This way 3CX can map the 3CX extension receiving the call or chat to the HubSpot user.
  • Check the "Enable Call Journaling" option to report external calls to the CRM, and configure these "Call Journaling" parameters:
  • Call Subject - the call’s subject.
  • Answered Inbound Call - description for answered inbound calls.
  • Missed Call - description for missed calls.
  • Answered Outbound Call - description for answered outbound calls.
  • Unanswered Outbound Call - description for unanswered outbound calls.
  • Please note that you can use variables in the "Call Journaling" parameters, denoted as
    [variable_name]
    , e.g. the external number is specified as
    [Number]
    . The available variables to use are listed     here.

  • If you want to report chats to the CRM, check the Enable Chat Journaling checkbox and configure the parameters below:
  • Chat Subject - the subject of the chat session.
  • Please note that you can use variables in the "Chat Journaling" parameters, denoted as
    [variable_name]
    , e.g. the external number is specified as
    [Number]
    . The available variables to use are listed     here.

See Also

Last Updated

This document was last updated on 10 September 2026

https://www.3cx.com/docs/hubspot-pbx-crm-integration/

Discuss this article