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 a call flow, authenticated with Zendesk OAuth.

 

Note: Zendesk is retiring API tokens as an authentication method. This article uses OAuth, the replacement method. Please see Why this article uses OAuth instead of an API token below if you're currently using an API token for this setup.
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: 

  • Why this article uses OAuth instead of an API token.

  • How using the Ring-to (via API) widget enhances efficiency and customer experience.
  • How to set up smart routing to the Zendesk contact owner.
    • Step one: Create the custom user field in Zendesk
    • Step two: Create a confidential OAuth client in Zendesk
    • Step three: Configure the Ring-to (via API) widget in the Flow editor
    • Step four: Test the configuration
Note: The Ring-to (via API) widget is only available on the Professional plan. If you are not on the Professional plan, please contact your Customer Success Manager for assistance.

Why this article uses OAuth instead of an API toke

Zendesk is phasing out API tokens as an authentication method for Support API requests, in favor of OAuth. Existing API tokens will continue to work for a transition period, but Zendesk will eventually deactivate them entirely.

Important: If you already have this routing working with an API token, don't wait until it stops working. Build the OAuth configuration on a second Ring-to (via API) widget, confirm it works, and only then switch your live widget over. See "Going live" below for the cutover steps.

The Ring-to (via API) widget authenticates to Zendesk using the OAuth client credentials grant. Aircall requests an access token from your Zendesk account using your client ID and client secret, then sends that token to the Zendesk API as an Authorization: Bearer header. Aircall caches the token and requests a new one automatically when it expires, so there's no manual token to rotate.

Note: For Zendesk's exact retirement timeline, see Zendesk's own announcement on removing API tokens.
 

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

Smart routing on a shared phone number offers significant benefits, improving efficiency, accuracy, and customer experience. By intelligently directing incoming calls based on CRM data, smart routing ensures each caller is quickly connected to the most appropriate agent, reducing wait times and improving first-call resolution rates.

Using Aircall’s Ring-to (via API) widget in a call flow, a common use case is routing inbound VIP callers directly to their Zendesk contact owner (dedicated Customer Support agent). This prevents the entire team from being interrupted by unrelated customer calls and removes the need to place callers on hold while being transferred to their assigned agent.

How to set up smart routing to the Zendesk contact owner

Step one: Create the custom field in Zendesk

Important: This step requires familiarity with Zendesk custom fields and authentication methods.

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

  1. In the Zendesk Admin Center, navigate to People → Configuration → User Fields and select Add Field.

    • Field type: Text

    • Display name: Owner Email

    • Field key: owner_email

    Screenshot 2024-11-04 at 7.17.32 PM.png

  2. The field will be automatically added to all end-user profiles. Once it is created and visible on the end-user profile, populate it with an email address. You will need this later to test the path validity in the Ring-to (via API) widget.

    Screenshot 2024-11-04 at 7.13.45 PM.png
Note: The email address you enter must match the email address of an existing Aircall user,otherwise the call cannot be routed to them.

Step two: Create a confidential OAuth client in Zendesk

Important: The client credentials grant is only available to confidential OAuth clients. A public client cannot be used for this setup. You need Zendesk admin rights to create an OAuth client.
  1. In the Zendesk Admin Center, go to Apps and integrations > APIs > OAuth clients, then click Add OAuth client.
  2. Complete the fields:
    • Name: any name you like, for example "Aircall - Ring to (via API)"
    • Identifier: auto-populated from the name. This value is your Client ID. You can change it if you want.
    • Client kind: Confidential. This is required.
    • Redirect URLs: the client credentials grant doesn't use this value. If the form won't save without one, enter an absolute HTTPS URL such as https://localhost.
    • Scopes: optional. If you leave this empty, the client may request any scope. If you do set it, it acts as a ceiling, the widget can't request a scope outside this list. If you set it, include the scope you'll enter in the widget in step three.
    • Expire tokens: you can leave this as it is. For OAuth clients created on or after 30 April 2026, the checkbox is disabled, because tokens issued by those clients already expire by default.
  3. Click Save. The page refreshes and a Secret field appears.
  4. Copy the Identifier and the Secret and store them somewhere safe.
 
Important: The Secret is displayed in full only once. After you leave the page, you can only see its first nine characters. If you lose it, you'll need to create a new OAuth client.
 
Important: Actions taken with a client credentials token are attributed to the Zendesk user who created the OAuth client, normally an admin. This affects your audit logs. It also means that if that user is later deleted, downgraded, or otherwise loses the permissions needed to manage OAuth clients, tokens issued by this client stop working and this routing will fail. If either point matters to you, create the OAuth client from a dedicated service account before you continue.

Step three: Set up the Ring-to (via API) widget in the Flow editor

Important: This step requires familiarity with Zendesk REST API and call flows.

  1. Go to Aircall Dashboard > Numbers, and open the call flow 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 call flow configuration. 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.

  1. 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 call flow configuration to open the widget editor.

  2. Set Authentication to OAuth, then click Set Credentials. Complete the credentials form as follows:

    Login URL https://MyDomainName.zendesk.com/oauth/tokens (replace MyDomainName with your Zendesk subdomain; use your core Zendesk subdomain, not a host-mapped domain)
    Client IDThe Identifier from your OAuth client
    Client SecretThe Secret from your OAuth client
    Scope users:read read to start with. Zendesk doesn't publish a scope-per-endpoint mapping, so treat this as a starting point and confirm it with the test in step four. If the test returns a scope error, Zendesk names the scopes it requires, enter exactly those.
  • A few tips for setting OAuth:
    • Choose the Authentication value first, then enter the credentials. Changing the Authentication selection clears any credentials already stored on the widget, and you'll need to enter them again.
    • If you don't see a Scope field in the OAuth credentials form, refresh your Aircall Dashboard. The Scope field is required for Zendesk, and without it Zendesk rejects the token request.
    • Scope is a space-separated list. Aim for the narrowest set that works. Zendesk has been observed to require a broad "read" alongside the resource-specific scope, which is why "users:read read" is suggested above.

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

    • URL: https://MyDomainName.zendesk.com/api/v2/users/search.json?query={{callerNumber}}
      (Replace “MyDomainName” with your actual Zendesk domain name.)

    • Method: GET

  2. Configure the response settings as follows:

    • Response type: User (ID or email)

    • Path: users[0].user_fields.owner_email

Step four: Test the configuration

Run a test in the dedicated Test Response field:

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

  • Ensure a JSON payload is returned.

  • Confirm that the Path is valid for finding the value used to route the inbound call.

  • Check that the existing contact’s email address matches an existing Aircall user’s email address.

Screenshot 2025-09-16 at 7.08.50 PM.png
Tip: Adjust the ringing settings directly beneath the test field to suit your business operations.

 You should now be ready to start testing inbound calls for smart routing to the Zendesk contact owner using the Ring-to (via API) widget.

Going live

Once your tests are complete and the routing works as expected, make sure to populate the Owner Email field in Zendesk for every end-user profile where you want calls to be automatically routed.

If you were previously authenticating this widget with an API token, switch your live widget to the OAuth credentials now, and remove the old API token from Zendesk Admin Center once you've confirmed the OAuth configuration is working.

Troubleshooting

SymptomCause and fix
An error requesting the access token, or HTTP 401 from the lookupThe credentials were rejected. Confirm the OAuth client is Confidential, and that the Client ID matches the Identifier exactly. If the Secret was re-copied after leaving the Admin Center page, it's truncated to nine characters, create a new client and use the full Secret.
An isolated test or call fails, and the same test passes immediately afterwardsThis can happen at the moment a cached access token expires and is being renewed. Retry the test. If it recurs consistently rather than occasionally, treat it as a genuine credential or scope problem and work through the rows below.
{"error":"Forbidden","description":"You are missing the following required scopes: ..."}The token was issued but lacks the scope the endpoint needs. Edit the widget's OAuth credentials and set Scope to the scopes named in the error message.
HTTP 400 with invalid_scope The scope requested by the widget is outside the Scopes list configured on the OAuth client in Zendesk. Either add the scope to the client's allowed scopes, or change the widget's Scope to stay within them.
Credentials appear to have been wipedChanging the Authentication selection clears stored credentials. Re-enter them after selecting the method.
Test returns a payload, but the call doesn't routeThe value at the configured Path must match an existing Aircall user. Confirm the Owner Email value on the Zendesk profile matches an Aircall user's email address.
Routing worked previously and stopped, with no configuration changeConfirm the Zendesk user who created the OAuth client still exists and still has permission to manage OAuth clients. Client credentials tokens act on behalf of that user and stop working if they lose that access.

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 Customer Success team to book time with our Technical Consultants.