3CX Integration with HubSpot

The integration offers five key features:

• Caller ID to Contact Name: Incoming calls automatically trigger HubSpot contact lookup to display caller information
• Contact Lookup: Search for HubSpot contacts by name, number, or email directly from the 3CX web client
• Call & Chat Journaling: All calls and chats are automatically logged in HubSpot contact records as CRM activities
• New Contact Creation: Create new HubSpot contacts directly from the 3CX client when receiving calls from unknown numbers
• Click to Call: Make calls directly from HubSpot using 3CX Click2Call browser extensions for Chrome and Edge

You'll need:

• A HubSpot account with CRM access
• A HubSpot Developer Account (free to create)
• Administrative access to your 3CX Management Console
• The URL for your 3CX Management Console
• Phone numbers stored in E164 format in HubSpot

Follow these steps:

1. Log into your HubSpot Developer Account
2. Select "Create an app"
3. Name it "3CX Integration"
4. Go to the Auth tab
5. In Redirect URL, enter your 3CX Management Console URL + "/api/oauth2crm" (e.g., "https://my-pbx.example.com/api/oauth2crm")
6. Add these scopes: "crm.objects.contacts.read", "crm.objects.contacts.write", "crm.objects.companies.read", "crm.objects.owners.read", "timeline"
7. Click "Save"
8. Copy the "Client ID" and "Client Secret" for later use

Each scope serves a specific purpose:

• crm.objects.contacts.read: Allows 3CX to look up existing contacts for caller ID
• crm.objects.contacts.write: Enables creating new contacts and updating existing ones
• crm.objects.companies.read: Provides access to company information linked to contacts
• crm.objects.owners.read: Identifies HubSpot users for call journaling assignment
• timeline: Allows logging calls and chats as timeline activities in contact records

I see a warning about an "unverified app" - is this safe?

Yes, this warning is normal and safe to ignore. Since you created the app yourself for your own organization, it hasn't gone through HubSpot's verification process for public apps. Click "Connect app" to proceed with authorization.

In your 3CX Management Console:

1. Go to "Settings" > "CRM Integration" > "Server Side" tab
2. Select "HubSpot" from the dropdown
3. Choose your desired contact lookup order
4. Enter the "Client ID" and "Client Secret" from your HubSpot app
5. Click "Authorize" to open the HubSpot authorization page
6. Select your HubSpot account (choose the one with your CRM data, not the developer account)
7. Verify the "Refresh Token" field is automatically populated

Yes, if you want your team to create new HubSpot contacts when unknown callers contact you. When enabled, if an incoming number doesn't match any existing contact, 3CX will prompt users to create a new contact by filling in details through a dialog box.

HubSpot performs exact number matching - it doesn't recognize partial numbers. For successful contact lookup, the incoming caller ID must be identical to the number stored in HubSpot, including any country code prefix. E164 format (e.g., +14155551234) ensures consistency between your phone system and CRM.

You can use 3CX's Caller ID Reformatting feature to convert incoming numbers to E164 format before they're passed to HubSpot. This ensures proper matching even if your trunk provider uses different formatting.

Go to "Advanced" > "Contacts" > "Options" in your 3CX console and set the matching strategy to "Match exactly". This ensures precise number matching with your HubSpot contacts.

Call journaling automatically creates activity records in HubSpot for external calls. For this to work:

• The email address on the 3CX extension must match a HubSpot user's email
• This allows 3CX to map the extension receiving the call to the correct HubSpot user
• All external calls (inbound/outbound, answered/missed) are logged with customizable descriptions

You can customize:

• Call Subject: The subject line for call activities
• Answered Inbound Call: Description for successful inbound calls
• Missed Call: Description for missed calls
• Answered Outbound Call: Description for successful outbound calls
• Unanswered Outbound Call: Description for failed outbound calls

Yes, you can use variables like [Number] for the external phone number. Available variables are listed in the 3CX CRM template documentation.

Check the "Enable Chat Journaling" checkbox in your CRM settings and configure the "Chat Subject" parameter. Like call journaling, you can use variables in the chat descriptions to include relevant information.

Verify these common issues:

• Phone numbers in HubSpot are stored in E164 format
• Incoming caller ID is also in E164 format (use Caller ID Reformatting if needed)
• Contact matching strategy is set to "Match exactly"
• The OAuth2 connection is active (check for valid refresh token)
• Required scopes are properly configured in your HubSpot app

Check that:

• The 3CX extension email matches a HubSpot user's email exactly
• "Enable Call Journaling" is checked in CRM settings
• The HubSpot user has appropriate permissions
• The "timeline" scope is included in your OAuth2 app

Common solutions:

• Ensure the redirect URL in your HubSpot app exactly matches your 3CX console URL + "/api/oauth2crm"
• Verify you're selecting the correct HubSpot account (the one with your CRM data)
• Check that all required scopes are added to your HubSpot app
• Try the authorization process again after fixing any URL or scope issues

Install the 3CX Click2Call browser extension:

• For Google Chrome: 3CX Click2Call Chrome Extension
• For Microsoft Edge: 3CX Click2Call Edge Extension

Once installed, you can click phone numbers in HubSpot to initiate calls through your 3CX system.

The browser extension should automatically detect your 3CX system once the CRM integration is properly configured. Ensure you're logged into both your 3CX web client and HubSpot for seamless functionality.

The integration uses refresh tokens, so it should maintain connection automatically. However, if you experience authentication issues, you may need to re-authorize through the 3CX Management Console.

For technical support:

• 3CX Community Forums for integration-specific discussions
• 3CX documentation for general CRM integration guidance
• HubSpot developer documentation for API-related questions