Configure Smart Routing to the HubSpot Contact Owner using the Ring-to (via API) widget in Smartflows

Configure smart routing to the HubSpot contact owner on a shared Aircall phone number to ensure that callers are efficiently connected to their dedicated point of contact.

NOTE:
The video tutorial may show the previous version of the Test Response section. Always rely on the written steps in this article for the most current guidance.

In this guide you will learn:

• How using the Ring-to (via API) widget enhances efficiency and customer experience

• How to set up smart routing to the HubSpot contact owner

  • Step one: Creating custom fields in HubSpot and generating a bearer token

  • Step two: Setting up the Ring-to (via API) widget in Smartflows

IMPORTANT:
The Ring to (via API) widget is available only on the Professional plan. To upgrade, please contact your Aircall account manager.

How using the Ring-to (via API) widget enhances efficiency and customer experience

Smart routing on a shared phone number provides major benefits for efficiency, accuracy, and customer experience. By directing incoming calls intelligently based on CRM data, smart routing ensures that each caller reaches the right person quickly, reducing wait times and improving first-call resolution rates.

Using Aircall’s Ring-to (via API) widget in Smartflows, a common implementation routes inbound callers directly to their HubSpot contact owner. This prevents the entire team from being interrupted by calls not meant for them and removes the need to place callers on hold while being transferred to their dedicated contact.

How to set up smart routing to the HubSpot contact owner

Step one: Create custom properties in HubSpot and generate a bearer token

IMPORTANT:
This step requires familiarity with HubSpot Custom Fields and HubSpot Private Apps.

Start in HubSpot by creating a custom property to store the contact owner’s email address.

Steps

1. Navigate to Contact Properties in HubSpot settings.

2. Select Create property.

3. Complete the property details as follows:

Setting	Value
Object type	Contact
Label	Aircall Contact Owner Email
Internal/API name	aircall_contact_owner_email
Field type	Single-line text

NOTE:
Configure the Rules section as desired, but make sure special characters are not restricted, since email addresses include characters such as **@** and **.**

4. You can then create a HubSpot workflow to populate this field automatically:

• Enroll all new contacts upon creation.

• To include existing contacts, select Yes, enroll existing contacts who meet the trigger criteria as of now in the Review & Publish step of your workflow setup.

5. Once the property is created, populate it with an email address. You’ll need this value later to test the path validity within the Ring-to (via API) widget.

6. Next, generate a Bearer Token in your HubSpot Developer Portal. This token will authenticate your API request when configuring the Ring-to (via API) widget in Smartflows. For detailed instructions, see HubSpot’s guide to Private Apps.

Step 2: Set up the Ring-to (via API) widget within Aircall Smartflows

IMPORTANT:
This section requires familiarity with HubSpot REST API, JSON, and Smartflows.

1. Go to Aircall Dashboard > Numbers, and open the Smartflows number to configure.

   • It is important to note that the Aircall users who will have calls routed to them via the API do not need to be assigned to the Smartflows Call Distribution. If they are assigned, the user will receive any missed call notifications in their To-Do list if they miss the transferred call. However, they will not receive these notifications if they are not assigned to the number.

2. Navigate to the phone number you wish to configure the Ring-to (via API) widget on. Add the Ring-to (via API) widget to your desired spot in your Smartflows distribution to open the widget editor.

3. Set Authentication method to Bearer Token, then click Set Credentials. In the credentials pop up form, paste the Bearer Token created in the previous step.

4. Return to the widget editor and complete the request configuration:

• URL: https://api.hubapi.com/crm/v3/objects/contacts/search

• Method: POST

• Body:

  {
    "properties": [
      "firstname",
      "lastname",
      "company",
      "email",
      "hubspot_owner_id",
      "aircall_contact_owner_email",
      "hs_calculated_phone_number",
      "hs_calculated_mobile_number",
      "hs_searchable_calculated_phone_number",
      "hs_searchable_calculated_mobile_number",
      "last_used_aircall_phone_number"
    ],
    "filterGroups": [
      {
        "filters": [
          {
            "propertyName": "hs_calculated_mobile_number",
            "operator": "EQ",
            "value": "{{callerNumber}}"
          }
        ]
      },
      {
        "filters": [
          {
            "propertyName": "hs_calculated_phone_number",
            "operator": "EQ",
            "value": "{{callerNumber}}"
          }
        ]
      }
    ],
    "sorts": [
      {
        "propertyName": "lastmodifieddate",
        "direction": "DESCENDING"
      }
    ],
    "limit": 10
  }

5. Set the response configuration:

• Response type = User (ID or email)
• Path = results[0].properties.aircall_contact_owner_email

6. Run a test in the dedicated Test Response field:

• Enter a valid phone number in the international E.164 format.

• Confirm that a JSON payload is returned.

• Confirm that the Path is valid to find the value used to transfer or route the inbound call.

• Confirm that the existing contact's email address matches an existing user's email address in Aircall.

TIP:
Adjust the ringing settings directly beneath the test to suit your business operations.

You should now be ready to start testing inbound calls for smart routing to the HubSpot Contact Owner using the Ring-to (via API) widget.

Food for thought

• Adding a team beneath the Ring-to (via API) widget can be a helpful addition to your flow. This works purely as a catchment for situations when the Contact Owner is not available, to ensure no calls are missed.

• You can set this configuration up with other HubSpot Objects such as the Company owner or the Deal owner.

• Remember Aircall can only route inbound calls using the Ring-to (via API) widget with simple logic (i.e. no branching based on conditions, no looping, etc.). In other words, there must exist either:

  • Under the profile of the HubSpot Object (i.e. Contact, Company, etc.)

  • Under an indirectly accessible related HubSpot Object (e.g. User) to the main HubSpot Object (i.e. Contact, Company, etc.)

• The values you are routing to must exist before configuring the Ring-to (via API) widget.

If you need an extra hand with implementing this smart routing configuration, or would like to learn about similar automations to enhance your operations, please reach out to the Customer Success team.