How to integrate 3CX and HubSpot

Step 1: Configure HubSpot

1. Create a HubSpot Developer App

   • Log in to your HubSpot Developer Account (you’ll need one if you don’t already).

     • You can create a HubSpot Developer Account (different this a standard HubSpot account) here: https://app.hubspot.com/signup-hubspot/developers

   • Select “Create an app.”

2. App Details & OAuth2

   • Name the app “3CX Integration.”

   • Go to the Auth tab.

   • In Redirect URL, enter your 3CX Management Console URL plus /api/oauth2crm.

     e.g. https://my-pbx.yourdomain.com/api/oauth2crm

   • Under Scopes, add:

      

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


   • Click Save, then copy the Client ID and Client Secret for use in Step 2.

Step 2: Configure 3CX

1. In the 3CX Management Console, navigate to Settings > CRM Integration > Server Side.

2. From the Provider dropdown, select HubSpot.

3. Choose your preferred Contact Lookup Order, then paste in the Client ID and Client Secret you copied.

4. Click Authorize—this will open the HubSpot OAuth page.

   • Select the HubSpot account where your CRM data lives (not the developer account).

   • If you see an “unverified app” warning, it’s safe to ignore since you created it—just click Connect app.

5. Confirm that the Refresh Token field populates automatically.

6. (Optional) If you’d like users to be able to create new HubSpot contacts directly from the 3CX client when a number isn’t recognized, enable “Allow contact creation”.

Step 3: Ensure E.164 Numbers & Exact Matching

1. HubSpot only matches whole numbers exactly, so both systems must use E.164 format (e.g. +1234567890).

2. Verify your SIP trunk delivers Caller ID in E.164; if not, use Caller ID Reformatting in 3CX to adjust it.

3. In 3CX go to Advanced > Contacts > Options, set Matching Strategy to “Match exactly”, and click OK.

Step 4: Set Up Call & Chat Journaling

1. Make sure each 3CX extension’s email address matches a HubSpot user’s email—this lets 3CX map calls/chats to the correct CRM user.

2. To log calls in HubSpot, enable “Call Journaling” and configure the message templates:

   • Call Subject, Answered Inbound Call, Missed Call, Answered Outbound Call, Unanswered Outbound Call

   • You can use variables like [Number] in these templates.

3. To log chats, enable “Chat Journaling” and set the Chat Subject (also supports variables).