Before Getting Started

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.

To send SMS messages using the Aircall API, you need to:

1. Have a valid Aircall account with the necessary permissions, including being on the Professional Plan. To upgrade your plan, contact your account manager.
2. Obtain an API key or access token following the Basic Auth /OAuth Authentication process described in the Aircall documentation.
3. Know the Id of the number from which you want to send the SMS. You can obtain it programmatically using Retrieve a number API.
4. Configure the number to be used via API

Note: A number can either be used for Third party configuration, native or Public API.

Steps

1. Setup HTTP Request for Sending SMS
2. Send SMS via Aircall API

Step One: Configure a number for Public API

⚠️ A number configured to send SMS via API will not be usable to send SMS in the Aircall app.

javascript
/**
 *  configure-number.js
 */

const https = require('https');

// Function to configure a line as Public API
const configurePublicApiNumber = (accessToken, lineId, callbackUrl) => {
  // Define the HTTP options:
  const options = {
    host: 'api.aircall.io',
    path: `/v1/numbers/${lineId}/messages/configuration`,
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + accessToken
    }
  };

  // Define the request body
  const body = {
    callbackUrl: callbackUrl
  };

  // Define the POST request:
  const req = https.request(options, res => {
    let responsePayload = '';

    res.on('data', data => { responsePayload += data });
    res.on('end', () => {
      // Handle the response
      if (res.statusCode === 200) {
        console.log('Number configured successfully:', JSON.parse(responsePayload));
      } else {
        console.error('Failed to configured number:', res.statusCode, responsePayload);
      }
    });
  });

  // Handle potential request errors
  req.on('error', e => {
    console.error(`Problem with request: ${e.message}`);
  });

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

// Example usage with an access token, lineId and callbackUrl
const accessToken = 'your_access_token';
const lineId = 'your_line_id';
const callbackUrl= 'your_callback_url'

configurePublicApiNumber(accessToken, lineId, callbackUrl);

Step Two: Send SMS via Aircall API

In the example above, we defined a function sendSms that takes four parameters:

• accessToken: Your Aircall API access token.
• lineId: The ID of the number from which the SMS will be sent.
• recipientNumber: The phone number of the SMS recipient.
• messageContent: The content of the SMS message.

This function sets up an HTTPS POST request to the Aircall API, formats the request body with the necessary details, and sends the SMS. The response is handled to provide feedback on whether the SMS was sent successfully or if there was an error.

Number should be configured to use with Public API.

We will define a function to send an SMS using the Aircall API endpoint POST v1/numbers/{lineId}/messages/send. This function will take the lineId, the recipient's phone number, and the message content as input.

javascript
/**
 *  send-message.js
 */

const https = require('https');

// Function to send SMS
const sendSms = (accessToken, lineId, recipientNumber, messageContent) => {
  // Define the HTTP options:
  const options = {
    host: 'api.aircall.io',
    path: `/v1/numbers/${lineId}/messages/send`,
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + accessToken
    }
  };

  // Define the request body
  const body = {
    to: recipientNumber,
    body: messageContent
  };

  // Define the POST request:
  const req = https.request(options, res => {
    let responsePayload = '';

    res.on('data', data => { responsePayload += data });
    res.on('end', () => {
      // Handle the response
      if (res.statusCode === 200) {
        console.log('SMS sent successfully:', JSON.parse(responsePayload));
      } else {
        console.error('Failed to send SMS:', res.statusCode, responsePayload);
      }
    });
  });

  // Handle potential request errors
  req.on('error', e => {
    console.error(`Problem with request: ${e.message}`);
  });

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

// Example usage with an access token, lineId, recipient number, and message content
const accessToken = 'your_access_token';
const lineId = 'your_line_id';
const recipientNumber = '+1234567890';
const messageContent = 'Hello from Aircall!';

sendSms(accessToken, lineId, recipientNumber, messageContent);

Step Three: Get the Configuration of a number

This function is to validate if the number is configured for Public API usage or not.

If not configured, it will return an error.

If configured, it will return the configuration.

javascript
/**
 *  get-number-configuration.js
 */

const https = require('https');

// Function to configure a line as Public API
const getNumberSettings = (accessToken, lineId) => {
  // Define the HTTP options:
  const options = {
    host: 'api.aircall.io',
    path: `/v1/numbers/${lineId}/messages/configuration`,
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + accessToken
    }
  };

  // Define the GET request:
  const req = https.request(options, res => {
    let responsePayload = '';

    res.on('data', data => { responsePayload += data });
    res.on('end', () => {
      // Handle the response
      if (res.statusCode === 200) {
        console.log('Number Settings::', JSON.parse(responsePayload));
      } else {
        console.error('Failed to configured number:', res.statusCode, responsePayload);
      }
    });
  });

  // Handle potential request errors
  req.on('error', e => {
    console.error(`Problem with request: ${e.message}`);
  });

  req.end();
};

// Example usage with an access token, lineId
const accessToken = 'your_access_token';
const lineId = 'your_line_id';

getNumberSettings(accessToken, lineId);

Step Four: Delete the Configuration of a number

This endpoint is to out the number to use with Public API and can be used natively.

javascript
/**
 *  delete-number-configuration.js
 */

const https = require('https');

// Function to configure a line as Public API
const deleteNumberSettings = (accessToken, lineId) => {
  // Define the HTTP options:
  const options = {
    host: 'api.aircall.io',
    path: `/v1/numbers/${lineId}/messages/configuration`,
    method: 'DELETE',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + accessToken
    }
  };

  // Define the DELETE request:
  const req = https.request(options, res => {
    let responsePayload = '';

    res.on('data', data => { responsePayload += data });
    res.on('end', () => {
      // Handle the response
      if (res.statusCode === 200) {
        console.log('Number settings deleted Successfully:', JSON.parse(responsePayload));
      } else {
        console.error('Failed to configured number:', res.statusCode, responsePayload);
      }
    });
  });

  // Handle potential request errors
  req.on('error', e => {
    console.error(`Problem with request: ${e.message}`);
  });

  req.end();
};

// Example usage with an access token, lineId
const accessToken = 'your_access_token';
const lineId = 12345; // integer value

deleteNumberSettings(accessToken, lineId);

Conclusion

This guide demonstrates how to send SMS messages using the Aircall API with plain JavaScript. You can expand this setup with more advanced features such as error handling, logging, and integration with other systems as needed.

For example, you could start by listening to call events to lookout for missed call, and automate the process further.

For more details on Aircall’s API endpoints and parameters, refer to the Aircall Developer Documentation.