To use Aircall telephony in Mavibot, you need to create a pair of API keys in your Aircall account and enter them in the integration settings.
Aircall is a cloud-based phone system for sales and support teams, offering phone numbers in 100+ countries. It is designed for companies whose employees already use the Aircall app: the bot places calls on behalf of an employee, rather than from a separate bot number.
The bot can connect an employee with a client, retrieve call recordings, and send call events to the conversation.
Getting the required data
- Sign up at aircall.io, purchase a phone number in the required country, and create Aircall users for your employees.
- Open Dashboard → Settings → Integrations & API → API Keys and create a pair of keys:
- API ID
- API Token
- Find the Number ID for the number that will be used for outgoing calls and the User IDs for your employees. These IDs are visible in the address bar when you open the corresponding pages in the Aircall dashboard.
API Token is shown only once when it is created. If you lose it, create a new pair of API keys and revoke the old one.
Connection
In the telephony settings, select Aircall and enter:
- API ID — the API key identifier.
- API Token — the secret API token.
- Number ID — the numeric ID of the Aircall line that will be used for outgoing calls.
The integration is now connected.
To disconnect the integration, clear the API ID field and save the settings.
Employees
In the employee settings, fill in the Aircall User ID field with the numeric ID of the employee's Aircall account.
Enter the user ID, not the employee's phone number. Without this ID, the call button in the client card will not work for that employee.
Calling from the client card
A call button will appear next to the client's phone number in the conversation card.
Aircall first starts the call in the employee's Aircall app — on desktop or mobile. Once the employee answers, Aircall calls the client and connects both parties.
The call will not go through if the employee is offline, already on another call, or not assigned to the selected number in Aircall. This is an Aircall limitation: calls can only be placed through an available user.
Calculator Functions
Employee-to-Client Call
aircall_employee_call(client_phone, employee_user_id, number_id)
Parameters:
- client_phone — the client's phone number in international E.164 format. Required.
- employee_user_id — the Aircall User ID of the employee who will receive the call in their Aircall app. Required.
- number_id — the ID of the Aircall number used to place the call. Optional. If omitted, the number configured in the integration settings is used.
Get Call Recording Link
aircall_get_record_link(call_id)
Requests a fresh link to the call recording.
Parameters:
- call_id — the Aircall call ID. Optional. If omitted, the client's most recent call is used.
Callbacks During a Call
As the call progresses, callbacks are sent to the conversation in the following format:
aircall_call_event call.answered
Possible events:
| Event | When it is triggered |
|---|---|
| call.created | The call has been created |
| call.ringing_on_agent | The employee is receiving the call |
| call.answered | The call has been answered |
| call.hungup | One of the parties has hung up |
| call.ended | The call has fully ended |
| call.voicemail_left | The client left a voicemail |
A typical "no answer → send a message in the messenger" scenario can be triggered by call.ended and checking the aircall_missed_reason variable.
Client Variables After a Call
After a call, the following variables are available for the client:
| Variable | Value |
|---|---|
| aircall_call_id | Aircall call ID |
| aircall_call_direction | Call direction: inbound or outbound
|
| aircall_call_status | Call status: initial, answered, or done
|
| aircall_call_duration | Call duration in seconds |
| aircall_missed_reason | Reason why the call was not completed |
| aircall_record_link | Link to the call recording |
Call Recordings
Call recording must be enabled in your Aircall settings. Recordings are stored in your Aircall account.
⏳ Aircall recording links are available for a limited time — typically only for several hours after the call. After that, the links stop working. This is how Aircall works and is not a Mavibot limitation.
What this means:
- In a scenario that sends a call recording, call
aircall_get_record_link()at the moment the recording is sent instead of using a previously saved link. - If you need to keep a recording permanently, save the file to your own storage immediately after the call.
- The recording archive remains available in the Aircall dashboard, where recordings can be played and downloaded later.
Call recording is regulated by law. In Germany, France, Spain, and many U.S. states, consent from both parties may be required, and in some jurisdictions a verbal notification at the beginning of the call may also be necessary. The Aircall account owner is responsible for complying with applicable laws and regulations.
Troubleshooting
| Error | Cause / Solution |
|---|---|
| Authorization error when placing a call | The API ID / API Token pair is incorrect. The token is shown only once when it is created. If it has been lost, create a new pair under API Keys and revoke the old one. |
| Call is not created or the employee does not receive the call | The employee is offline in the Aircall app, already on another call, or is not assigned to the selected number in Aircall settings. |
| "Aircall User ID is not specified" | The Aircall User ID field in the employee settings is empty, or a phone number was entered instead of the numeric user ID. |
| Calls work, but no callbacks appear in the conversation | The webhook was not registered. Save the Aircall integration settings again to register it. |
| Recording link does not open | The link has expired. Request a fresh link using aircall_get_record_link() or open the recording directly in the Aircall dashboard. |