Skip to main content
Submit or View Requests
Deutsch Español (España) Français (France) Italiano (Italia)

Smartflows widgets: Ring to (via API) technical documentation

The Smart Routing: Ring to (via API) widget uses an API response to determine which Aircall user, team, internal number, or external number to route a call to, based on data stored outside of Aircall.

This widget provides powerful and flexible dynamic routing capabilities by connecting Aircall with third-party systems such as CRMs or help desks.

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

Prerequisites

Before configuring the widget, ensure that the following requirements are met.

Authentication credentials

The authentication method depends on the external platform whose data you plan to retrieve. Supported methods include:

  • Basic Authentication
  • Bearer Token
  • API key
  • OAuth

Example (Aircall API):

  1. Navigate to Integrations & API > API keys in the Aircall Dashboard.
  2. Generate a new API key.
  3. Save both the API key ID and token.
  4. In the Ring to (via API) widget configuration, go to Credentials and set:
    • Username = API key ID
    • Password = API token

Learn more about finding your Aircall API key in our article Where to find my Aircall API Key.

Knowledge of the platform API

You must understand the structure and endpoints of the external platform’s public API.

While Where to find my Aircall API Key uses the Aircall API as an example, you can also use platforms such as HubSpot, Salesforce, Zendesk, Intercom, Pipedrive, or internal CRMs.

Knowledge of JSON

The widget uses JSON (JavaScript Object Notation) to exchange data with APIs. You should be familiar with basic JSON structures to correctly configure data paths.

TIP:
If you need assistance configuring the widget, our Technical team can provide consulting and implementation support. Please, reach out to our Account Management team.

Considerations for use

The Ring to (via API) widget allows dynamic (“smart”) call routing based on external data. It can query any system that supports REST APIs and standard authentication methods.

NOTE:
Requests made by Ring to (via API) will time out after 10 seconds. Ensure your endpoint responds within this time limit, or the widget may not be able to retrieve the routing target.

The API response must return data in a format that Aircall can interpret for routing. Supported response types include:

Response type Description
User Routes to a specific agent using their Aircall User ID or email.
Team Routes to a specific Aircall team using its Team ID.
Aircall number Routes internally to another Aircall number using its Number ID.
External number Routes externally to a phone number (must be in international E.164 format).
Dynamic Target (ID) Allows your external API to specify both the target type and target ID dynamically.

When using Dynamic Target (ID), you must define two JSON paths in the widget:

  • Path to target type (user, team, number or external)
  • Path to target value (the target’s unique ID)
NOTE:
For Dynamic Target responses, the widget accepts only the following values for the target type: agent, team, internal, and external.

If the resolved target is a team, standard ringing rules apply. If it’s a user or number, those rules do not apply.

Any advanced logic (e.g., conditional routing, prioritization) must be processed in your external system before returning the API response.

Configuration steps

The widget determines whether to ring to a User, Team, Aircall Number, External Number, or Dynamic Target (ID) based on the configured API call.

Steps:

  1. In the Smartflows editor, add a Ring to (via API) widget.
  2. Choose the HTTP method (GET or POST), depending on the API section you want to use.
    • Example: When using the Search Calls endpoint of the Aircall API, select GET.

  3. Enter the API URL, for example:

    https://api.aircall.io/v1/calls/search?order=desc&phone_number={{callerNumber}}

    This searches for the most recent calls associated with the caller’s phone number.

  4. Use variables like callerNumber, targetNumber, or callUUID to dynamically insert call-specific data into your request. Refer to the Aircall API documentation for a full list of query parameters.

Response configuration

In the Response configuration section, define how the API response will be parsed to determine the routing target.

Supported response types:

  • User (ID or email)
  • Team (ID)
  • Aircall number (internal)
  • External number (E.164 format)
  • Dynamic Target (ID)

Example JSON path:

calls[0].user.id

This path references the first item in the “calls” array and retrieves the user ID.

Example Dynamic Target JSON response:

{
  "calls": [
    {
      "target_type": "team",
      "target_id": 12345
    }
  ]
}
  • Path to Target Type: calls[0].target_type
  • Path to Target Value: calls[0].target_id

If the target type is team, ringing rules will be applied accordingly.

Testing the configuration

Use the Test response field to simulate API requests and confirm that your configured paths return the correct values.

Example test input:

{
  "callerNumber": "+15551234567",
  "targetNumber": "+15557654321",
  "callUUID": "abcd-1234-efgh-5678",
  "lineId": 12345
}

Each key in the JSON corresponds to a variable used in your URL or request body. When you run the test, the widget will substitute these variables and display the parsed results.

If an error occurs, consult the Errors section in the Aircall API documentation for troubleshooting guidance.

Ringing settings

After configuring and testing your API integration, adjust the Ringing settings to define how calls are distributed. These settings work the same way as those in the standard Ring to widget.

For more details, see our Help Center article Smartflows routing overview.

TIP:
If you're interested in leveraging this feature but lacking technical expertise - contact our Account Management team, who will connect you with our technical team for support and implementation guidance.
Jordan W.