Logging SMS Events with Aircall Webhooks

To synchronize Aircall SMS events with your system in real time, you can leverage Messaging webhook events. Using Webhooks, Aircall will notify your system each time an SMS event occurs.

☝️Right now, only webhooks are available as a method, it is not possible to do batch syncing using API endpoints. This means that you will not be able to fetch historical messages before you started listening to webhooks.

All requests made to the Aircall Public API and explained in this tutorial are authenticated. Make sure to follow the Basic Auth guide first, or if you are a third party application partner, the OAuth Authentication tutorial.

Real-time Synchronization

Real-time synchronization only requires setting up a web server with one public POST endpoint. It's the easiest, most reliable, and scalable way to retrieve SMS information from Aircall: you won't have to deal with Public API rate limiting, pagination, and automation as we will rely 100% on Webhook events sent by Aircall.

Step One: Setup an Aircall Webhook via Public API

This tutorial will give you insights on how to create a Webhook via the Public API.

Here, we will listen to all SMS events:

message.sent
message.received
message.status_updated

javascript
/**
 *  create-webhook.js
 */

const https = require('https');

// Takes a User accessToken and creates a Webhook in your User's Aircall account
const createWebhook = (accessToken) => {
  // Define the HTTP options:
  let options = {
    host: 'api.aircall.io',
    path: '/v1/webhooks',
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + accessToken
    }
  };

  // Define the Webhook's body, listening only to SMS events
  const body = {
    'custom_name': 'YOUR_APP_NAME',
    'url': 'https://your.server.com/aircall/webhook',
    'events': [
      'message.sent', 'message.received', 'message.status_updated'
    ]
  };

  // Define the POST request:
  const req = https.request(options, res => {
    let payload = '';
    res.on('data', data => { payload += data });
    res.on('end', () => {
      // Here the Webhook has been created
      // The unique token can be extracted from the payload:
      const response = JSON.parse(payload);
      const webhookToken = response.webhook.token;

      // TODO: store this webhookToken on your User model
      console.log('Webhook created with token:', webhookToken);
    });
  });

  // Attach the body to the request and execute it
  req.write(JSON.stringify(body));
  req.end();
}

// Example usage with an access token
createWebhook('your_access_token');

Step Two: Store SMS Metadata in Your Database

Now that the Aircall Webhook is created, we will start receiving all events related to SMS messages on the following endpoint:

[POST] https://your.server.com/aircall/webhook

Each time a Webhook event is sent to this endpoint, we will either create or update an SMS record in our database.

javascript
/**
 *  server.js
 */

// Using express to run a NodeJS server

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

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

// [POST] /aircall/webhook
// URL used by Aircall to send Webhook events
app.post('/aircall/webhook', (req, res) => {
  handleSmsEvent(req.body);

  res.sendStatus(200);
});

const handleSmsEvent = (event) => {
  const { event: eventType, data } = event;

  switch (eventType) {
    case 'message.sent':
      createOrUpdateSms('Message Sent', data);
      break;
    case 'message.received':
      createOrUpdateSms('Message Received', data);
      break;
    case 'message.status_updated':
      createOrUpdateSms('Message Status Updated', data);
      break;
    default:
      console.log('Unknown event type:', eventType);
  }
};

const createOrUpdateSms = (eventType, smsData) => {
  // TODO: save this smsData in your database
  // Example: Log the event type and SMS data
  console.log(`[${new Date().toISOString()}] ${eventType}:`, smsData);
};

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

Exposing Your Local Server

To test your webhook, you can use a tool like ngrok to expose your local server to the internet. Follow the instructions on ngrok to set it up and obtain a public URL.

ngrok http 5000

Update your Aircall webhook URL with the ngrok URL, and you should start receiving events on your local server.

Conclusion

By following this guide, you can set up a basic HTTP server to log SMS events from Aircall using webhooks. This simple setup can be expanded with additional features like error handling, data processing, and integration with various CRM systems as needed. For more details on Aircall’s webhooks and payload structures, refer to the Aircall Developer Documentation.