Webhook Slack Notifications

What is sipgate.io?
In this tutorial
Before we begin
Setting up a project
Webhook server
Slack webhook

What is sipgate.io?

sipgate.io is a collection of APIs, which enables sipgate’s customers to build flexible integrations matching their individual needs.
Among other things, it provides interfaces for sending and receiving text messages and faxes, monitoring the call history, as well as initiating and manipulating calls.
The webhook capability of sipgate.io allows for the real-time processing of call data and implementation of applications like IVRs (interactive voice recordings).

In this tutorial

We will focus on sending a Slack message to notify a person or a channel about missed calls.
The Slack message will contain the phone numbers of the caller and the callee.

Before we begin

Before we dive into the code, let’s quickly set up your sipgate account for sipgate.io.
For infos on how to do that, check out www.sipgate.io/get-started

To activate webhooks for incoming and outgoing calls, go to console.sipgate.com and select „Webhooks“ from the sidebar on the left.
The „URLs“ tab lets you configure target URLs for these webhooks.
It distinguishes incoming and outgoing calls and also allows for the explicit selection of phonelines that should trigger webhooks.
By default all phonelines are activated.

For the purpose of this application we will only be using the „Incoming“ URL since we don’t want to gather statistics about outgoing calls.
It can be any publicly accessible URL on the web.
Local addresses like localhost or 127.0.0.1 and any other local network address will not work.

When using webhooks in production you will want to run your code on a proper webserver with a proper address.
However, for the purpose of development we recommend using a service that makes your local environment accessible via the internet.
That makes it much easier to rapidly test out your written code.

There are a various services that can be used to accomplish this.
Some examples are localhost.run or ngrok.
Either one supplies you with a public URL that you can paste to the sipgate.io console.
Just make sure that you forward the correct port (in this tutorial we’ll be using port 8080, more on that later) and that the provider that you choose offers secure connections through HTTPS.

Set up a project

Now that your sipgate account is all set up, it’s time to start coding.

For this project we will be using the official sipgate.io Node.js library.
It makes working with sipgate’s APIs much easier and also provides a convenient way to set up a webhook server.

But first, let’s create a new Node project.
To do that, create a new directory that will hold our project and inside run npm init -y.

This creates a package.json file containing some meta data for the project.
Open it up and add

"scripts": {
  "start": "node server.js"
}

inside the outer curly braces to register a start script that can later be called from the command line.

Now, to install the sipgate.io Node library run npm install -S sipgateio.

That’s it for now.
We will come back and install some more dependencies later.

Webhook server

Let’s get coding!

Create a new file with the name server.js.
The following snippet creates an instance of sipgate.io’s webhook module and uses that to create a webhook server with the configuration from the webhookServerOptions object. This object contains the port and the server address in order to handle call events like the hangup event.
Since that address can vary (especially when using your local machine with an SSH tunnel as with ngrok & Co) it may be a good idea to read it from an environment variable.

const { createWebhookModule } = require("sipgateio");

const serverAddress = process.env.SERVER_ADDRESS;
if (!serverAddress) {
  console.error(
    "Please provide a server address via the environment variable SERVER_ADDRESS"
  );
  return;
}

const webhookServerOptions = {
  port: process.env.SERVER_PORT || 3000,
  serverAddress,
};

createWebhookModule().createServer(webhookServerOptions);

The createServer function returns a promise of a WebhookServer which can then be used to register callback functions for various call events:

createWebhookModule()
  .createServer(webhookServerOptions)
  .then((server) => {
    console.log(
      `Server running at ${webhookServerOptions.serverAddress}\n` + "Ready for calls ?"
    );
    server.onHangUp((hangUpEvent) => {
      console.log(
        `Hung up call from ${hangUpEvent.from} to ${hangUpEvent.to}`
      );
    });
  });

For the hangup events we just print a readable representation of the call to the console.

Now it’s time for a test drive!

Start up the server with npm start and wait for the message on the console saying that the server is running.
Make sure that it displays the correct server address. If it doesn’t, make sure that you set your environment variable correctly, for example SERVER_ADDRESS=http://your.address npm start.

Then call your sipgate number and cancel the call.
You should now see the log of the hangup event.

Now we will be notified of any call that has been hung up.
However, since we are only interested in those calls, that have been hung up without being answered, we will filter by the cause of the HangUpEvent.

createWebhookModule()
  .createServer(webhookServerOptions)
  .then((server) => {
    // ...
    server.onHangUp((hangUpEvent) => {
      if (hangUpEvent.cause === "cancel") {
        console.log(
          `Canceled call from ${hangUpEvent.from} to ${hangUpEvent.to}`
        );
      }
    });
  });

Slack webhook

Now we are ready to send a slack webhook about a canceled call.
First of all we need to configure a new slack webhook for a channel or a person to send the message.
You can find more information about how you can create a new webhook in the official slack documentation.

Once you have done that we can send a post request to the url given by slack.
For sending a post request we will be using axios, a promise-based http client.
To install it run npm install -S axios.

The next step is to import axios and retrieve the Slack webhook URl from the environment variable by inserting the following statement at the top of the server.js file:

const axios = require("axios").default;

const slackWebhookUrl = process.env.SLACK_WEBHOOK_URL;
if (!slackWebhookUrl) {
  console.error(
    "Please provide a Slack webhook URL via the environment variable SLACK_WEBHOOK_URL"
  );
  return;
}

Then we can customize the callback of the hangup event to send a post request to slack.

createWebhookModule()
  .createServer(webhookServerOptions)
  .then((server) => {
    // ...
    server.onHangUp((hangUpEvent) => {
      if (hangUpEvent.cause === "cancel") {
        axios.post(slackWebhookUrl, {
          text: `Canceled call from ${hangUpEvent.from} to ${hangUpEvent.to}`,
        })
        .catch(console.error);
      }
    });
  });

Now were are ready to test our implementation.
Before you start the server make sure to correctly set the required environment variables and start it by running npm start.

You can now call your sipgate number, cancel the call and you should see the message in slack.

You can checkout the complete source code here.

Notify a Slack channel about canceled calls with the sipgate.io Node library