The Health Check Monitor is a built-in diagnostic tool that automatically checks your Salesforce org for common misconfiguration issues with the Aircall integration. It is read-only: nothing is written or modified in your org. Results appear instantly and can be exported as a CSV.
Use it when you are setting up the Aircall integration for the first time, after a package upgrade, or when troubleshooting issues such as fields not populating or calls not logging.
IMPORTANT: The Health Check Monitor is available in Salesforce Lightning only. It is not available in Salesforce Classic.
Who should run this
Salesforce administrators, or any other permissioned Salesforce Users responsible for setting up or maintaining the Aircall<>Salesforce integration in your org.
What it checks
The monitor runs checks across three categories:
Package Installation: verifies the Aircall package is correctly installed, all required components are present, and remote site settings are configured.
User Permissions: verifies the integration user has API access, correct CRUD permissions on required objects, the required permission set assigned, and View All on key objects.
Field-Level Security: verifies the integration user can read and write all required Aircall fields on key objects.
NOTE: Additional check categories are planned for future releases, including Apex Endpoint Reachability, Data and Flows, CTI and Voice Configuration, and Connectivity. The monitor currently covers the V3/CTI integration only. Service Cloud Voice (SFV) support is planned for a future phase.
Setting up the Health Check Monitor
Once the Aircall package is installed, two manual steps are required to make the Health Check tab available in your Lightning app.
Step 1: Add the Health Check tab to your Lightning app
Steps
- Go to Setup > App Manager.
- Find your Lightning app and click Edit.
- Go to Navigation Items and add the Health Check tab.
- Save your changes.
Step 2: Set the tab to Default On for the System Administrator profile
Steps
- Go to Setup > Profiles.
- Open the System Administrator profile.
- Go to Custom Tab Settings.
- Find aircallHealthCheckDashboard and set it to Default On.
- Save your changes.
Running the Health Check
Steps
- Navigate to the Health Check tab in your Lightning app.
- Click Run V3 Health Check.
- Results appear inline. Expand each category to see individual check details.
The dashboard displays the name, role, email, and profile of the user currently running the check in the top-right corner. Before running, confirm you are logged in as the correct user, as checks reflect the running user's permissions.
NOTE: Results are not stored and disappear on page refresh. Use the Download Report button to export all results as a CSV before closing or refreshing the page.
Understanding your results
Each check returns one of three statuses:
| Status | What it means | What to do |
|---|---|---|
| PASS | The check passed, no action required. | Nothing. |
| FAIL | A misconfiguration was detected. | Expand the row to see the error message, remediation steps, and a link to the relevant documentation. |
| WARNING | Informational, not a failure, but worth reviewing. | Review the details shown in the check row. |
When a check fails, expand the row directly to see what went wrong and how to fix it. Each failed check includes an error message, specific remediation steps, and a link to the relevant documentation.
Fixing common issues
Fields not populating on Salesforce records
Affected fields include SMS, Call Resolution, AI Insights, Call Recording, and Tags.
Likely cause: missing Field-Level Security (FLS) on Aircall fields for the integration user.
Steps
- Run the Health Check and look for failures in the Field Security category.
- Assign AirCall_PermissionSet to the integration user. This grants Read and Write FLS on all required Aircall fields.
- If the permission set is already assigned, verify it is assigned to an active user.
Integration user setup failing or calls not logging
Likely cause: missing API Enabled permission or insufficient CRUD access on required objects (Task, Contact, Lead, Account, Case, Opportunity).
Steps
- Run the Health Check and look for failures in the User Permissions category.
- Assign AirCall_PermissionSet and confirm that API Enabled is set on the user's profile.
- If only inactive users hold the permission set, reassign it to the active integration user.
Package upgrade failing with "AI Object Permission Error"
Likely cause: AirCall_PermissionSet is assigned to a Guest License user. Salesforce blocks package upgrades in this state.
Steps
- Run the Health Check and look for failures in the Package Installation category.
- Go to Setup > Permission Sets > AirCall_PermissionSet > Manage Assignments.
- Remove any Guest License users from the assignment.
- Retry the package upgrade.
FAQs
Does the Health Check make any changes to my org?
No. It is completely read-only. No data is written or modified.
How long does it take to run?
A few seconds.
Whose permissions does the check reflect?
The check reflects the permissions of the user currently running it, not the integration user's permissions. Make sure you are running the check as the correct user. The running user's name, role, email, and profile are shown in the top-right corner of the dashboard.
Which integration does this cover?
Currently V3/CTI only. Service Cloud Voice (SFV) support is planned for a future phase.
What should I do if a check fails?
Expand the failed check row. It shows the error message, what to fix, and a link to the relevant documentation. For common failure scenarios, see the "Fixing common issues" section above.
If you need to contact Aircall Support
If you have run the Health Check and cannot resolve the issue, collect the following before contacting Aircall Support:
- The CSV export from the Health Check (click Download Report).
- Your Salesforce Org ID.
- The Aircall package version (shown in the Package Version Warning check).
- The running user's profile name (shown in the top-right user info box).
- A screenshot of any failed checks.
For Salesforce debug logs, go to Setup > Debug Logs and capture an Apex execution log while running the Health Check. Include this in your support ticket if available.