We will build a smart call-overflow system, based on your business' opening hours:

• If an incoming call is made during business hours, it will ring on a cascading defined in the Aircall Dashboard.
• Otherwise, if it's made outside business hours or during a bank holiday, the call will be routed on another line (either external phone number or another Aircall number), offering a 24/7 support.

Before getting started

Make sure to have:

• Two Aircall numbers:
  1. The main number: a public number that customers will call.
  2. The overflow number: a private number call made outside of business hours will be redirected to.
• Webhooks: read our complete guide to Webhooks tutorial!
• Authentication to the Aircall API: either by using OAuth for Partners or an API Key for Customers.
• A web server, listening to webhook events and sending API requests to Aircall.

1. Setting up your Aircall Numbers

We need to set up two Aircall Numbers with two lines.

The first number will be the public one, the one you can share with your customers. The business hours property must be set to always open, so that we will be able to transfer the call to the right number also when the call is coming in outside business hour and callers won't hear any Unanswered call message.

The second one will be the internal line, used to manage the overflow strategy when calling outside of business hours.

Check our Knowledge Base if you need help buying a new phone number or setting up your call distribution behind each number!

Store somewhere the ID of those two numbers, we will need in step 4 to transfer incoming calls to the right number. You can find each number IDs in the Dashboard's URL:

2. Listening to call.created events

Now that we have setup both numbers, we need to listen to the call.created Webhook event.

Aircall will send a call.created event each time inbound and outbound calls start on your account. Based on the timing of the event, we will then be able to either let the call follow the main number if happening during business hours, or we will transfer the call to the overflow number if happening outside business hours.

The following tutorial will guide you to set up a Webhook from the Aircall Dashboard. It will also help you create an endpoint to listen to the Webhook events sent by Aircall:

Here is an extract example of a body payload sent via Aircall to your server for a call.created event:

json
{
  "event": "call.created",
  "resource": "call",
  "timestamp": 1585001000,
  "token": "45XXYYZZa08",
  "data": {
    "id": 812,
    "direct_link": "https://api.aircall.io/v1/calls/812",
    "direction": "inbound",
    "started_at": 1584998199,
    "answered_at": null,
    "ended_at": null,
    "duration": 0,
    "number": {
      "id": 1234,
      ...
    },
    ...
  }
}

Useful fields are:

• event: allows us to confirm that the webhook event sent is call.created.
• data['id']: the Call id, a unique identifier that we'll use to transfer the call.
• data['direction']: direction of the Call, can be either inbound or outbound. We will work only on inbound calls.
• data['number']['id']: the Number unique identifier. We will filter events based on this value later.

Here is a code example of a simple web server listening to Aircall call.created Webhook events:

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

app.use(bodyParser.json());


/**
 *  [POST] /aircall/calls
 *  Creates a public endpoint for Aircall Webhooks
 */
app.post('/aircall/calls', (req, res) => {
  if (req.body.event === 'call.created') {
    // TODO: Implement the overflow logic
  }
  res.sendStatus(200);
});

3. Is current time outside of business hours?

Once your webhook is setup in Aircall and your backend server is ready to receive call.created webhook events, we can now start building the logic:

call.created events are sent in real-time. Anytime our web server will receive one of those, we can check the current server time and take a decision accordingly.

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

app.use(bodyParser.json());


/**
 *  [POST] /aircall/calls
 *  Creates a public endpoint for Aircall Webhooks
 */
app.post('/aircall/calls', (req, res) => {
  // On each webhook event sent by Aircall,
  // we're filtering `call.created` events`
  // and inbound calls only.
  if (
    req.body.event === 'call.created' &&
    req.body.data.direction === 'inbound'
  ) {
    if (isOutsideOfBusinessHours()) {
      // TODO: Implement the redirect logic
    }
    else {
      // Do nothing.
    }
  }
  res.sendStatus(200);
});


/**
 *  Returns true if current time is outside of
 *  business opening hours, false otherwise.
 */
const isOutsideOfBusinessHours = () => {
  const businessHours = [
    {from: 10, to: 17}, // Sunday, from 10am to 5pm
    {from: 8,  to: 18}, // Monday, from 8am to 6pm
    {from: 8,  to: 18}, // Tuesday, from 8am to 6pm
    {from: 8,  to: 18}, // Wednesday, from 8am to 6pm
    {from: 8,  to: 18}, // Thursday, from 8am to 6pm
    {from: 8,  to: 18}, // Friday, from 8am to 6pm
    {from: 10, to: 17}  // Saturday, from 10am to 5pm
  ];

  // Get current day of the week (0 for Sunday, 1 for Monday...):
  const currentDay = (new Date()).getDay();

  // Get hour, according to local time (from 0 to 23):
  const currentHour = (new Date()).getHours();

  return !(
    businessHours[currentDay]['from'] <= currentHour &&
    currentHour < businessHours[currentDay]['to']
  );
}

This code example can be easily adapted to take into account bank holidays.

Web servers are often set to UTC timezone. Don't forget to update the code example to reflect your timezones!

4. Implement the overflow logic

Incoming calls are now filtered, we can implement the transfer logic, using the following Public API endpoint:

Request
POST https://api.aircall.io/v1/calls/:id/transfers

Body:
{
  number: "Overflow number, in e164 format"
}

More info on how to use the Transfer feature in our API References.

To send a transfer request, we'll need an Aircall API ID and API Token, as shown in the following tutorial:

We can start writing the transfer logic, now that we have:

1. an API ID and API Token
2. the main number Aircall id
3. the overflow phone number, in an e164 format (ex: +18001234567)

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

app.use(bodyParser.json());


/**
 *  [POST] /aircall/calls
 *  Creates a public endpoint for Aircall Webhooks
 */
app.post('/aircall/calls', (req, res) => {
  // On each webhook event sent by Aircall,
  // we're filtering `call.created` events`
  // and inbound calls only.
  if (
    req.body.event === 'call.created' &&
    req.body.data.direction === 'inbound'
  ) {
    if (isOutsideOfBusinessHours()) {
      transferCall(req.body.data);
    }
    else {
      // Do nothing.
    }
  }
  res.sendStatus(200);
});

...


/**
 *  Transfer the incoming call to the overflow number
 */
const transferCall = (callObject) => {
  // We set the ID of the two Aircall we created in step 1.
  const MAIN_NUMBER_ID = 123;

  // Do nothing if the Webhook event is not associated to the main number:
  if (callObject.number.id !== MAIN_NUMBER_ID) {
    return;
  }

  // Encoding credentials:
  const apiId = YOUR_API_ID;
  const apiToken = YOUR_API_TOKEN;
  let encodedCredentials = Buffer.from(apiId + ':' + apiToken).toString('base64');

  // Format the URL
  const apiUrl = `https://api.aircall.io/v1/calls/${callObject.id}/transfers`;

  // Define the POST body, with the E164 overflow number
  const body = {
    number: '+18001234567'
  };

  // Define HTTP options
  const httpOptions = {
    headers: {
      'Authorization': 'Basic ' + encodedCredentials,
      'Content-Type': 'application/json'
    }
  };

  // Finally, send the POST API request to Aircall
  axios.post(apiUrl, body, httpOptions);
}

And that's it! From now on, each incoming call made on the main number will either follow the call distribution set in the Aircall Dashboard or will be transferred to the overflow number, depending on your business hours!