After implementing this tutorial, your website visitors will be able to fill a simple form to be called back, directly from one of your landing pages. Once this form is submitted, an outbound call will automatically be triggered from the first available agent's Aircall Phone!

Steps

1. Build the HTML form
2. Setup the API endpoint called when users submit the form
3. Get all available agents
4. Automatically start an outbound call

1. Build the HTML form

On one of your landing page, you'll need to include an HTML form, with at least the following fields:

• First name & Last name
• Email
• Phone number

html
<form action="https://mywebsite.com/callback_request" method="POST">
  <label for="name">First name & last name</label>
  <input type="text" id="name"/>

  <label for="email">Email</label>
  <input type="text" id="email"/>

  <label for="Phone number">Phone number</label>
  <input type="text" id="Phone number" />
  <input type="submit" value="Call me back!" />
</form>

For simplicity, this tutorial is written with a classic HTML form. You can, of course, change it to make it asynchronous with some JavaScript!

2. Setup the API endpoint called when users submit the form

When visitors will hit the Call me back! button, a [POST] /callback_request request will be sent to your backend web server, hosted on https://mywebsite.com/.

Here is an example on how to handle this API request with a simple NodeJS web server:

javascript
/**
 *  server.js
 *  Using express to run a NodeJS server
 */

const express = require('express'),
      bodyParser = require('body-parser');

const app = express();
app.use(bodyParser.urlencoded({ extended: true }));
app.use(bodyParser.json());

/**
 *  [POST] /callback_request
 */
app.post('/callback_request', (req, res) => {
  // 1. Extracting params from the request's body
  const { name, email, phone_number } = req.body;

  // TODO: fetch all available agents

  res.sendStatus(200);
});


const PORT = 5000;
app.listen(PORT, () => {
  console.info('[server] server started');
  console.info('[server] visit http://localhost:' + PORT);
});

3. Get all available agents

The first thing we need to do when a callback request is sent is to find one available agent.

We'll use the [GET] https://api.aircall.io/v1/users/availabilities Public API endpoint for that. Here is an example of payload this request will return, with both agents 234 and 345 available:

json
[GET] https://api.aircall.io/v1/users/availabilities

{
  "meta": {
    "count": 3,
    "total": 3,
    "current_page": 1,
    "per_page": 20,
    "next_page_link": "https://api.aircall.io/v1/users?&page=2",
    "previous_page_link": null
  },
  "users": [
    {
      "id": 123,
      "availability": "unavailable"
    },
    {
      "id": 234,
      "availability": "available"
    },
    {
      "id": 345,
      "availability": "available"
    }
  ]
}

In the following webserver example, the fetchAircallAvailableAgents method shows how to retrieve available agents from Aircall's Public API. Then, from all available agents, we randomly select one:

javascript
/**
 *  server.js
 *  Using express to run a NodeJS server
 */

const express = require('express'),
      bodyParser = require('body-parser'),
      axios = require('axios');

const app = express();
app.use(bodyParser.urlencoded({ extended: true }));
app.use(bodyParser.json());

/**
 *  [POST] /callback_request
 */
app.post('/callback_request', (req, res) => {
  // 1. Extracting params from the request's body
  const { name, email, phone_number } = req.body;

  // 2. Fetch available agents
  let availableAgents = await fetchAircallAvailableAgents();

  // 3. Randomly select an agent
  let selectedAgent = availableAgents[Math.floor(Math.random() * availableAgents.length)];

  // TODO: start an outbound call

  res.sendStatus(200);
});


/**
 *  Send a Public API request to Aircall's Public API
 *  and returns all available agents
 */
const fetchAircallAvailableAgents = async () => {
  const apiId = YOUR_API_ID;
  const apiToken = YOUR_API_TOKEN;

  let apiUrl = 'https://api.aircall.io/v1/users/availabilities';
  // Set HTTP Authorization header
  let options = {
    headers: {
      'Authorization': 'Basic ' + Buffer.from(`${apiId}:${apiToken}`).toString('base64')
    }
  };

  try {
    const payload = await axios.get(apiUrl, options);
    const { users } = payload.data
    return users.filter(u => u.availability === 'available');
  } catch (e) {
    console.error('Error while retrieving Aircall availabilities:', e.response.status);
    return {};
  }
};

const PORT = 5000;
app.listen(PORT, () => {
  console.info('[server] server started');
  console.info('[server] visit http://localhost:' + PORT);
});

4. Automatically start an outbound call

Now that we have an available agent, we can start an outbound call from their Aircall Phone.

The Aircall Public API offers a dedicated endpoint to start an outbound call (documentation available here).

javascript
/**
 *  server.js
 *  Using express to run a NodeJS server
 */

const express = require('express'),
      bodyParser = require('body-parser'),
      axios = require('axios');

const app = express();
app.use(bodyParser.urlencoded({ extended: true }));
app.use(bodyParser.json());

/**
 *  [POST] /callback_request
 */
app.post('/callback_request', (req, res) => {
  // 1. Extracting params from the request's body
  const { name, email, phone_number } = req.body;

  // 2. Fetch available agents
  let availableAgents = await fetchAircallAvailableAgents();

  // 3. Randomly select an agent
  let selectedAgent = availableAgents[Math.floor(Math.random() * availableAgents.length)];

  // 4. Start the outbound call,
  //     from the available agent's phone
  //     to the phone_number the visitor requested to be called back on.
  startOutboundCall(selectedAgent.id, phone_number)

  res.sendStatus(200);
});


/**
 *  Return all available agents on Aircall
 */
const fetchAircallAvailableAgents = async () => {
  ...
};


/**
 *  Start an outbound call from an Aircall number
 *  - *userId*: the available agent's Aircall ID
 *  - *numberToCallback*: the e164 phone number the visitor requested to be called back on
 */
const startOutboundCall = (userId, numberToCallback) => {
  const apiId = YOUR_API_ID;
  const apiToken = YOUR_API_TOKEN;

  let apiUrl = 'https://api.aircall.io/v1/users/' + userId + '/calls';

  // Set HTTP Authorization header
  let options = {
    headers: {
      'Authorization': 'Basic ' + Buffer.from(`${apiId}:${apiToken}`).toString('base64')
    }
  };

  let body = {
    'number_id': 123,
    'to': numberToCallback
  };

  axios.post(apiUrl, body, options);
};



const PORT = 5000;
app.listen(PORT, () => {
  console.info('[server] server started');
  console.info('[server] visit http://localhost:' + PORT);
});

Watch out, starting an outbound call via the Public API only works on the Desktop Phone. It's on our mobile apps roadmap!

Notes

In this tutorial, the following points have not been taken care of:

• If all agents are unavailable when a callback request is sent, a retry method needs to be implemented.
• Phone number submitted by visitors must be e164 formatted.
• An Insight Card can be sent to the agent with visitor's info.