LinkedIn Iris and Oncall opensource tool

Iris and Oncall tutorial and Integration with twilio


This tutorial is aimed to setup iris and oncall locally and to integrate with twilio

Follow the links below to set things up first in your local environment and to understand the basics



Note: In this tutorial I have hosted oncall, iris and iris-relay in one server and I'm running make commands in different terminal accessible within localhost.


In simple terms, Oncall manages and schedules the on-call shifts.

Oncall Ldap Integration

Below is my configuration for LDAP

Remember to comment out the module: ‘oncall.auth.modules.debug and module: ‘oncall.auth.modules.ldap_example’.

Only enable the “oncall.auth.modules.ldap_import” module and set debug to 'False'

Now that users are imported from LDAP so that when user tries to login it will check whether the user already exists or not.

If not then the user will be added to the database.

User Sync Configuration

Below is the user_sync and ldap_sync process so that users in on call can be accessed by iris.

Iris will import these users as targets. This process has to run separately.


In simple, Iris is an open-sourced solution for automated incident escalation and also provides reliable messaging service

Here I have created a custom application named “oncall” in iris with plans and templates by following iris documentation.

Iris - Oncall Integration

As you can see above, In the role_lookups plugin I have included “oncall” and commented out remaining.

Configure the oncall-api url , app name and key so that iris can communicate with oncall.

Once configured, run the below command in the iris root directory where the Makefile is located.

make targets

This command will sync the users, team from oncall to iris.

Now the iris can determine who the target is and it can import the targets to communicate.

Iris-twilio integration


You need to have iris-relay installed and running. you can download it here

It acts as forwarder. It helps in providing instructions to twilio server and twilio interacts with it

Register your mobile number in

When the incident has been raised, you need a message_vendor to be configured so that iris can create messages for that incident and escalate that incident via call or sms to the concerned recipient who is on call rotation.

To satisfy this purpose there is a component called Iris sender.

To activate Iris Sender, you need to run the below command at the root directory of iris project where Makefile is located.

make sender

Let’s see a scenario where using twilio to make calls when the escalation happens and when the primary person responds that call that has a voice message saying “Press 2 to claim alert” so that an alert can be claimed by pressing the keypad on mobile.

Interesting right? Above scenario is possible with combination of iris and iris-relay with the help of twilio.

In iris configuration, you need to configure the twilio registered number with Sid and Auth_token. In relay_base_url, you need to provide the iris-relay service url

You actually need a domain url and you cannot configure such as “localhost:port” in relay_base_url.

Since I have configured iris-relay to run locally, I have used ngrok to create public url for a website running and listening on 16648 port number locally on my development machine.

Iris-relay is a separate service that has to be running.

Note: In the iris documentation, you may be asked to create TwilML Bin url and apply that url in relay_base_url. That is needed only when you don’t want any keypad presses (Gather action) happening from recipients and you just need twilio to say the content. In our case, It’s different!.

Below is the Configuration that you need to configure for iris-relay.

Note: You need to provide the relay_app_name as the application name which you have created at iris. In our case its “oncall”.

That’s it! Now you can test it by adding a primary person for on-call rotation, Do an escalation and test whether you're receiving your phone call or not!