3CX provides integration with Hubspot via easy and straightforward server-side configuration with the 3CX API for CRM. The integration provides many benefits to users of 3CX and Hubspot, including:
- Contact Synchronization – inbound calls from external numbers trigger a CRM contact lookup to add to 3CX Contacts and automatically show the caller name on your phone’s display when receiving the call.
- Call Pop-ups – when using the 3CX Web Client, the customer record is displayed automatically when you receive a call.
- Call Journals – calls are logged as CRM call records.
- Create a new contact automatically when a call is received from an unknown number.
- Click to Call – launch calls directly from Hubspot via 3CX, using the 3CX Browser Extension.
This guide takes you through the required steps to setup your Hubspot with 3CX.
Important: Due to Hubspot API limitations, contact lookup is performed only on contacts, not companies, using the main contact phone number only, not the mobile or fax number.
- Hubspot requires OAuth2 authentication to authorize 3CX to access your data, so you need a Hubspot Developer Account to create an app.
- After logging in with your Hubspot Developer Account, select “Create an app”.
- Set the name to “3CX Integration” and go to the Auth tab to complete the OAuth2 details.
- In the Redirect URL field, enter the URL you use to access your 3CX Management Console, adding “/api/oauth2crm” at the end. For example: “https://my-pbx.example.com:5001/api/oauth2crm”
- In the Scopes field, add “contacts” and “timeline”.
- Click on “Save”.
- Copy the values from “Client ID” and “Client secret”, as they will be needed later.
3CX CRM Server Side Configuration
Contact Matching Strategy
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.
Important: In 3CX Management Console, open “Advanced” > “Contacts” > “Options”, set the matching strategy to "Match exactly" and click “OK” to save.
- In 3CX Management Console go to “Settings” > “CRM Integration” > “Server Side” tab.
- Select “Hubspot” from the dropdown list.
- Enter the values for “Client ID” and “Client Secret” previously copied from your Hubspot Developer Account.
- Click on “Authorize” to launch the Hubspot authorization page. You will be prompted to select an account, choose your normal user account (not the developer account), and then in the “Request for Integration Permissions” page, click on “Grant access” to authorize.
- Verify the “Refresh Token” field is automatically filled for the Hubspot CRM in 3CX Management Console.
- Proceed to configure “Call Journaling” and/or “Contact Creation” as below, or click on “OK” to apply the configuration.
1. 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.
2. 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:
- CallType - the type of call, it can be “Inbound”, “Outbound”, “Missed”, or “Unanswered”.
- Number - the external contact number, i.e. the number dialed for outbound calls or the caller number for inbound calls.
- Agent - the extension number of the agent handling the call.
- Duration - the call duration in “hh:mm:ss” format.
- DurationTimeSpan - the duration of the call as a TimeSpan object with a user-defined format.
- DateTime - call start date and time, in local time zone, formatted using the 3CX server local timezone option in “Settings” > “Timezone, Office Hours & Holidays”.
- CallStartTimeLocal - the call start date & time, in local time zone, as a DateTime object with a user-defined format.
- CallStartTimeUTC - the call start date and time, in UTC time zone, as a DateTime object with a user-defined format.
- CallEndTimeLocal - the call end date and time, in local time zone, as a DateTime object with a user-defined format.
- CallEndTimeUTC - The call end date and time, in UTC time zone, as a DateTime object with a user-defined format.
To create new contacts in the CRM when a call is received from an unknown number, i.e. not found in either 3CX or CRM, check the “Enable Contact Creation” checkbox and configure the available parameters:
- “New Contact First Name” - first name for the newly created Contact.
- “New Contact Last Name” - last name for the newly created Contact.
Please note that you can use these variables in this field, denoted as
- Number - the external contact number, i.e. the number dialed for outbound calls or the caller’s number for inbound calls.