Implement click-to-dial

Getting started

Implement click to dial so users can click a phone number in your app and continue the call in Aircall Workspace or the Aircall Phone app.

Click to dial is useful when you want the user to stay in control of the call. Your app can either open the default phone app with a phone link, or use the Aircall API to pre-fill a specific user’s Phone app with a destination number.

Use this guide to choose between two options:

• Use tel: or callto: links when you want the simplest browser-based implementation.
• Use POST /v1/users/:id/dial when your backend knows which Aircall user should receive the pre-filled number.

Option 1: Use phone links

Phone links let the browser or operating system open the user’s default phone app. If Aircall Workspace is installed and configured as the default phone handler, clicking the link opens Aircall Workspace with the phone number ready to use.

Use tel: for the most common implementation:

<a href="tel:+393930000000">Call customer</a>

Some desktop environments also support callto: links:

<a href="callto:+393930000000">Call customer</a>

Use phone links when:

• you want a lightweight implementation with no backend API call
• you do not need to target a specific Aircall user through the API
• you are comfortable relying on the user’s default phone app settings

This approach is simple, but it gives your integration less control. The operating system decides which app opens the link based on the user’s local settings.

Option 2: Use the REST API

Use POST /v1/users/:id/dial to pre-fill a specific user’s Aircall Phone app with a destination number. The call does not start automatically. The user reviews the number, chooses the outbound Aircall number if needed, and starts the call from the Phone app.

Before you send the request:

1. You must have an Aircall account. Sign up as a customer here or if you qualify to be a tech partner you can then sign up for a developer account here.
2. Set up authentication with OAuth or Basic Auth. This guide uses Basic Auth.
3. Install Aircall Workspace or the Aircall Phone desktop app for the user who will place the call.
4. Get the Aircall user ID for the user whose Phone app should be pre-filled. You can fetch it with GET /v1/users or find it in the Aircall Dashboard.
5. Format the destination phone number in E.164 format, including the country code. For example, +393930000000.

Send the click-to-dial request

Create a server-side endpoint that receives the Aircall user ID and destination number, then calls Aircall with the authenticated request.

import express from "express";

const app = express();

// Parse incoming JSON so your endpoint can read userId and to from req.body.
app.use(express.json());

// Aircall Basic Auth
const credentials = Buffer.from(
  `${process.env.AIRCALL_API_ID}:${process.env.AIRCALL_API_TOKEN}`
).toString("base64");

// Your app calls this endpoint when a user clicks a phone number in your UI.
app.post("/click-to-dial", async (req, res) => {
  const { userId, to } = req.body;

  // Validate the required inputs before making the Aircall request.
  if (!userId || !to) {
    return res.status(400).json({
      error: "userId and to are required",
    });
  }

  try {
    // This endpoint pre-fills the user's Aircall Phone app.
    // It does not automatically start the call.
    const aircallResponse = await fetch(
      `https://api.aircall.io/v1/users/$USERID/dial`,
      {
        method: "POST",
        headers: {
          // Send the Base64-encoded API ID and API token as a Basic Auth header.
          Authorization: `Basic ${credentials}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          // Use E.164 format for the destination number, for example +393930000000.
          to,
        }),
      }
    );

    // Aircall returns 204 No Content when the Phone app is pre-filled successfully.
    // Convert it to a JSON response that is easier for your frontend to consume.
    if (aircallResponse.status === 204) {
      return res.status(200).json({
        message: "Phone app pre-filled",
      });
    }

    // Non-204 responses contain details that help you debug invalid numbers,
    // authentication issues, or user availability errors.
    const errorBody = await aircallResponse.text();

    return res.status(aircallResponse.status).json({
      error: "Aircall request failed",
      details: errorBody,
    });
  } catch (error) {
    // This catches network errors or unexpected server-side failures.
    return res.status(500).json({
      error: "Unable to pre-fill the Phone app",
      details: error.message,
    });
  }
});

app.listen(3000, () => {
  console.log("Server listening on port 3000");
});

Your application should send this JSON body to your Express endpoint:

{
  "userId": "YOUR_USER_ID",
  "to": "+393930000000"
}

Handle the response

A successful Aircall request returns 204 No Content. This means the user’s Phone app was pre-filled successfully, and no response body is returned by Aircall.

In the Express example above, your server converts that successful 204 No Content response into this JSON response for your app:

{
  "message": "Phone app pre-filled"
}

After that, the user starts the call from Aircall Workspace or the Aircall Phone app.

Troubleshooting

The phone link opens the wrong app

Confirm that Aircall Workspace is installed and configured as the default app for phone links on the user’s device. Phone links are handled by the operating system, not by your web app.

400 invalid number

Confirm that to contains a valid phone number in E.164 format, including the country code.

401 Unauthorized

Your API request was not authenticated. Check that your API ID and API token are correct, and that you are sending them with Basic Auth.

405 user not available

The user may be unavailable or already on a call. Confirm that the user is available in Aircall Workspace or the Aircall Phone desktop app before sending the click-to-dial request.

Nothing appears in Aircall Workspace

Confirm that the userId belongs to the Aircall user whose Phone app should be pre-filled, and that the user has Aircall Workspace or the Aircall Phone desktop app open.