Put simply, the “Ring to (via API)” widget uses an API response to know which Aircall Team, User, internal Number, or external number to ring to based on data that lives outside of Aircall.
While the Ring to (via API) is a flexible widget that can be used to achieve a number of desired workflows based on a number of external platforms, in this tutorial we will look at an example using the Aircall API to dynamically route calls to an Aircall User.
Prerequisites
Before configuring the Ring to (via API) widget, ensure you have the following:
Authentication Credentials
Authentication method will depend on the external platform whose data you plan to retrieve. Ring to (via API) currently supports Basic Authentication, Bearer Token, API key, and OAuth.
In this example, using the Aircall API as an example, we will use the Basic Authentication method. We’ll generate an API key by navigating to the “Integrations & API” section of the Dashboard, clicking on the “API keys” tab, and generating the key.
📚 Where to find my Aircall API Key
We’ll now save the API key’s ID and token, then in the Ring to (via API) widget configuration we’ll go to “Credentials” and set the API key ID as the username and the token as the password.
Knowledge of Platform API
Based on the platform from which you would like to fetch data, it is important to have a good understanding of what is included in that platform’s public API.
This documentation will use the Aircall API as an example, but users can use other partner platforms such as HubSpot, Salesforce, Zendesk, Intercom, Pipedrive, or in-house CRMs as the platforms where data is requested to make routing decisions.
Knowledge of JSON
Ring to (via API) also uses JSON, or JavaScript Object Notation, a standard text-based format commonly used to transmit data between web applications.
We recommend being familiar with the basic concepts of JSON before attempting to configure the Ring to (via API) widget.
If you require assistance in the set-up of the Ring to (via API) widget, Aircall’s Professional Services team is able to provide technical consulting and hands-on implementation to ensure success.
Configuration Steps
The end behavior of the Ring to (via API) widget is that it will choose to ring to either an Aircall User, an Aircall Team, an Aircall Number, or an external number outside of Aircall.
In this example, we’ll look at ringing to an Aircall User by utilizing the Search Calls endpoint of the Aircall API.
The API, or the section of the API, that we choose to utilize will determine whether we select GET or POST as the “Method” in the Ring to (via API) configuration. In this case, as we will utilize the Search Calls endpoint of the Aircall API, we will choose GET as the method.
For the URL, we will use the following as an example:
https://api.aircall.io/v1/calls/search?order=des&phone_number={{callerNumber}}
Based on this URL, the Ring to (via API) will search for phone numbers in descending order, meaning it will search starting from the most recent calls. Aircall almost always uses either phone numbers or email addresses as a unique identifier in partner platforms, so this is a common URL that can be used to search for a relevant phone number.
Other variables that could be included in this URL are listed under the query parameters on the Search Calls Aircall API documentation.
Response Configuration
Now we’ll look at the “Response configuration” section of the Ring to (via API) widget.
The response types supported are:
- User (ID or email)
- Team (ID)
- Aircall number (internal)
- External number
Much like the standard Ring to widget, the response type will determine who inbound calls are directed to. “User” will ring to an individual Aircall agent, “Team” will ring to an Aircall team, “Aircall number” will ring to another Aircall number, and “External number” will ring to a number outside of Aircall.
The “Path” section will parse through the response provided by the API. Since we are leveraging the “Search Calls” endpoint of the Aircall API, we can see the response in the Aircall API documentation.
Let’s use the following as an example:
calls[0].user.id
Looking at the Aircall API documentation, we can see that the path is referencing the “calls” section of the response, with each dot referencing a subsection of the “calls” section (in this case, the “user” and “id” value). The value, 0, contained in brackets, is an array that indicates the response will begin with the first call in the list.
We can then make sure that the path we’ve chosen is correct via the “Test response” section of the Ring to (via API) widget by entering a phone number on which we’d like to run the query.
Please ensure the number entered in the “Test response” field is in E.164 format.
If there is an error, please consult the Errors section of the Aircall API documentation which indicates the reason for the error and assists with troubleshooting.
Finally, we can set up the Ringing settings, which are identical to the Ringing settings on the standard Ring to widget. For more information on ringing settings, please consult our Help Center article on call routing.
If you require assistance in the set-up of the Ring to (via API) widget, Aircall’s Professional Services team is able to provide technical consulting and hands-on implementation to ensure success.