Populate custom contact's info on a call
Leverage contextual information from your backend during an incoming call.

Select a language:

    This tutorial shows how simple it is to populate Contact's information into the incoming call view of your agents' app.

    For all incoming calls, we are going to retrieve in your Database the first name, last name and company name of the caller, and display those info into the Phone.

    Populate contact info

    Getting started

    Before starting to code, you will need to have:

    1. An Aircall account - sign up here;
    2. Your API ID and your API Token. You can create one in the Company section of your Aircall Dashboard;
    3. A server running your application with a valid webhook endpoint (See the Create a Webhook integration tutorial to learn more about it);
    4. Your own database where you can match a phone number to a contact of yours.

    Step by step

    Now we are all setup, here are the steps we are going to follow:

    1. Listen to the call events
    2. Get custom details about a specific call
    3. Broadcast those details to the Aircall Phone

    1. Listen to the call events

    Aircall sends the event type in the body of the requests made to the route /aircall/calls of your application, set as the event attribute.

    The call.created Webhook event is sent by Aircall when a call is starting on all your Aircall numbers, regardless if it is an inbound or an outbound call. You may want to create a demo account to avoid being spammed by your production environment.

    /**
     *  [POST] /aircall/calls will listen to Aircall webhook
     */
    app.post('/aircall/calls', (req, res) => {
      if (req.body.event === 'call.created') {
        // TODO: do something with this event
      }
      else {
        console.log('Event non-handled:', req.body.event);
      }
      res.status(200);
    });
    

    2. Get more information about a call

    Webhook requests contain a lot of useful information about a call, such as the direction (inbound or outbound) and the callee/caller number (raw_digits).

    You will find more information about all those details in the Call object description here.

    Remember, we want to send extra-information on incoming calls calls, related to the caller:

    • data.direction field is the call direction, we will use only inbound calls in this tutorial;
    • data.raw_digits field is the caller's number in Inbound calls, formatted as E.164.
    /**
     *  [POST] /aircall/calls will listen to Aircall webhook
     */
    app.post('/aircall/calls', (req, res) => {
      if (req.body.event === 'call.created') {
        myApp.handleCallCreatedEvent(req.body.data);
      }
      else {
        console.log('Event non-handled:', req.body.event);
      }
      res.status(200);
    });
    
    ...
    
    /**
     *  Your App framework
     */
    const myApp = {
      /**
       *  Main function, called on a `/aircall/calls` POST request
       *  Get custom info from a custom database and send them to Aircall
       */
      handleCallCreatedEvent: (data) => {
        // If the call is an inbound call
        if (data.direction === 'inbound') {
          // Retrieve custom informations from a custom database
          myApp.retrieveCustomInfo(
            data.raw_digits,
            (first_name, last_name, company_name) => {
              // And send them to Aircall
              myApp.sendInfoToAircall(data.id, {
                first_name: first_name,
                last_name: last_name,
                company_name: company_name
              });
            }
          );
        }
        else {
          console.log('Direction non-handled:', data.direction);
        }
      },
    
      /**
       *  Retrieve custom info based on fromNumber from your backend
       *  and return them through a callback function
       */
      retrieveCustomInfo: (fromNumber, cb) => {
        // TODO: Plug your backend here.
        // Cook your secret sauce here with `fromNumber` to get
        // contact's first_name, last_name and company_name
        const first_name = ...;
        const last_name = ...;
        const company_name = ...;
    
        if (cb) {
          cb(first_name, last_name, company_name);
        }
      },
    
      /**
       *  Broadcast first_name, last_name, company_name to Aircall Phone
       */
      sendInfoToAircall: (callId, info) => {
        // TODO: push those info to Aircall Phone
      }
    }
    

    How can I display information on certain calls only?

    Aircall's Calls webhooks also contain the details on the Aircall number the caller is calling. You can filter your action on a specific number by using the number.id field.

    Aircall Number ids are unique in Aircall database, you can find the one you want either by requesting the /numbers API route, or by going into your Aircall Dashboard, on the number's page:

    Number id

    3. Display extra information into the Phone app

    Now that we have our web-server running and our contact's informations, we need to broadcast them to Aircall Phone. We will use the /calls/:id/metadata route of the public API (see documentation here).

    As described in Aircall's API reference, this route need to be requested by a POST method and can have four parameters:

    • first_name - contact's first name;
    • last_name - contact's last name;
    • company_name - contact's company;
    • link - contact's direct link to your internal CRM.
    const myApp = {
      ...
    
      /**
       *  Broadcast first_name, last_name, company_name to Aircall Phone
       */
      sendInfoToAircall: (callId, info) => {
        const API_ID = '<your_api_id>';
        const API_TOKEN = '<your_api_token>';
    
        // Populate Aircall API url with API_ID, API_TOKEN and callId
        const uri = `https://${API_ID}:${API_TOKEN}@api.aircall.io/v1/calls/${callId}/metadata`;
    
        request.post(uri,
          {
            json: {
              first_name: info.first_name,
              last_name: info.last_name,
              company_name: info.company_name
            }
          },
          (error) => {
            if (error) {
              console.error('Error while setting metadata in Aircall', error)
            }
          }
        );
      }
    }
    

    And we are done! Open your Aircall Phone, try to make an inbound call on a number you are associated on and see the magic happens!

    We wrote other tutorials to help you out
    building awesome integrations

    Discover them now!