Configure smart routing on a shared phone number to ensure callers are efficiently connected to their point of contact using the Ring-to (via API) widget in Smartflows.

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 Salesforce contact owner.

    • Step one: Setting up the OAuth connected app within Salesforce

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

Important: The Ring-to (via API) widget needs to be enabled via a feature request. Please reach out to your Aircall point of contact for this to be enabled before getting started.

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

Smart routing on a shared phone number offers a multitude of benefits, mainly enhancing efficiency, accuracy, and customer experience. By intelligently directing incoming calls based on criteria from your CRM, smart routing ensures that each caller is swiftly connected to the most appropriate agent, reducing wait times and improving first-call resolution rates.

Using Aircall’s Ring-to (via API) widget in Smartflows, a popular implementation is routing inbound callers to the Salesforce contact owner. This eliminates the whole team being interrupted by inbound calls from customers that are not theirs, and removes the possibility of the caller being placed on hold while being transferred to their dedicated point of contact.

How to set up smart routing to the Salesforce contact owner

Step 1: Setting up the OAuth connected app within Salesforce

Important: This section requires familiarity with Salesforce App Manager and Salesforce Connected Apps.

Start in Salesforce by creating an OAuth connected app to gain access to Salesforce’s REST API.

  1. In your Salesforce environment, navigate to Setup → App Manager (use the Quick Find box), then click New Connected App in the top right.

    Screenshot 2024-02-14 at 5.36.09 pm.png

  2. Provide a name for your new OAuth connected app, as well as a contact email address.

  3. Complete the API (Enabled OAuth Settings) section as follows:

    • Enable OAuth Settings: Enabled

    • Callback URL: https://login.salesforce.com/services/oauth2/success

      Tip: A callback URL is the URL invoked after OAuth authorisation for the connected app. In some contexts, the URL must be an actual redirect, but in this case it is not used. You may use any URL, including the example above.

    • Selected OAuth Scopes: Manage user data via APIs (api)

      Note: This allows access to the current, logged-in user’s account using APIs, such as REST API and Bulk API 2.0. It will be used with “Enable Client Credentials Flow” so that every Salesforce API request runs using a specific Salesforce user (a Salesforce Admin).

    • Enable Client Credentials Flow: Enabled

  4. Click Save.

    Screenshot 2024-02-14 at 5.45.15 pm.png

  5. If prompted with a message warning that the OAuth credentials could be used to access the org, click OK.

  6. Click Manage Consumer Details to access the consumer key (Client ID) and consumer secret (Client Secret).

    Important: Ensure you copy the values of both to somewhere safe and secure.
    Screenshot 2024-02-14 at 5.51.50 pm.png

  7. Return to the Manage Connected Apps page. In the Quick Find box, search for Connected and select Manage Connected Apps. Find your OAuth app, open it, and select Edit Policies.

    Screenshot 2024-02-14 at 5.59.27 pm.png

  8. Under Client Credentials Flow, click the magnifying glass beside Run As and select the profile of an existing Salesforce Admin. This user will be used to run every Salesforce API request.

    Screenshot 2024-02-14 at 6.03.21 pm.png

Once these steps have been completed, the Salesforce setup is finished. Continue in the Aircall Dashboard.

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

Important: This section requires familiarity with Salesforce REST API, JSON, and Smartflows.

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

    Note: 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 missed call notifications in their To-Do list if they miss the transferred call. 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 OAuth, then click Set Credentials. Complete the credentials pop up form as follows:

    • Login URL: https://MyDomainName.my.salesforce.com/services/oauth2/token
      (enter your Salesforce domain name in place of MyDomainName)

    • Client ID: the Consumer Key retrieved from your Salesforce OAuth connected app

    • Client Secret: the Consumer Secret retrieved from your Salesforce OAuth connected app

      Screenshot 2025-10-24 at 10.27.07.png

  4. Complete the request configuration:

    • Method: GET

    • URL: https://MyDomainName.my.salesforce.com/services/data/v51.0/parameterizedSearch/?q={{callerNumber}}&sobject=Contact&Contact.fields=id,name,Contact.Owner.Email&Contact.limit=10&Contact.orderBy=LastModifiedDate+DESC

      (enter your Salesforce domain name in place of MyDomainName)

      Using this API endpoint searches for the inbound caller’s number (in international E.164 format) across all Salesforce Contacts. If at least one is found, it returns the last updated Contact with a matching phone number and includes the Contact ID, Contact Name, and Contact Owner’s Email Address in the JSON payload.

  5. Configure the response:

    • Response type: User (ID or email)

    • Path: searchRecords[0].Owner.Email

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

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

    • Make sure a JSON payload is returned.

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

    • Ensure the existing contact’s email address matches an existing user’s email address in Aircall.
       

      Screenshot 2025-09-16 at 7.08.50 PM.png
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 Salesforce contact owner using the Ring-to (via API) widget.

Food for thought

  • Adding a team beneath the Ring-to (via API) widget can be helpful as a catchment when the contact owner is not available, to ensure no calls are missed.

  • You can set this configuration for other Salesforce Objects such as the Account owner or the Lead owner.

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

    • Under the profile of the Salesforce Object (for example, Contact, Lead).

    • Under an indirectly accessible related Salesforce Object (for example, User) to the main Salesforce Object.

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

Professional Services

If you need an extra hand with implementing this smart routing configuration, or would like to learn about similar automations to enhance your operations, check out our Professional Services page to book time with our Technical Consultants.