[2020] Add Incoming Call Notification via Telegram API to FreePBX/RasPBX/IncrediblePBX

For our PBX system, we are looking for a solution where we get notified for incoming calls via Telegram App. Following guide will enable a simple Incoming Call Notification via Telegram using API. This method is tested on FreePBX, RasPBX and IncrediblePBX.

Why Telegram?

Telegram is an open-source cloud-based instant messaging and voice over IP service with support for Android, iOS, Windows Phone, Windows, macOS and Linux. Users can send messages and exchange photos, videos, stickers, audio and files of any type.

STEP 1 : Creating BOT in Telegram

The very first thing we need to do is BOT CREATION. For that, we need to search for a username @BotFather

Once located, we need to use the following commands to create our bot.


  • /newbot – executing command for creating new bot;
  • Google Cloud Platform – choosing a name for our bot;
  • gcponlinebot – choosing username for our bot;
  • /setuserpic – this is optional, but you can apply some kind of a ‘profile picture’ for your bot;

In above screenshot, you can see highlighted API token, (1273621638:AAG1EmfaptRrot2LCJrxobYfryrlIC9o-ow), which we will use later on. Remember this API Key.

Open a new chat with your bot and execute the /start command – it`s required for bot activation. Without this, BOT will not work.

Now, add your bot to the group chat. You can do it the same way as you are inviting new participants to the group chat – just search for your bot`s username in search and add to the group. Now in your group chat execute the following command:

/join @gcponlinebot

In your case, it will be username of your bot after @ symbol. Then you need to open following URL in web-browser:

XXXXXXXXXXXXXXXXXXXXXX – your token. In our case it looks like this:


Let’s get Group Chat ID.  In our case, it’s -452784357. You can also take out Group Chat ID from Replace ‘g‘ with ‘‘ for Telegram Group Chat in AGI Script below. If you want to forward notifications to normal user, just remove ‘-‘ sign.

Let’s start Asterisk script creation.

STEP 2 : Creating PHP-AGI Script for Asterisk

Script is written on PHP and it will be called from Asterisk dialplan through AGI. Script content is below:

nano /var/lib/asterisk/agi-bin/telegram.php

#!/usr/bin/php -q
$agi = new AGI(); 
$cid = $agi->request['agi_callerid'];
$dnid = $agi->request['agi_rdnis'];
# $phoneFieldset1 = "Incoming Call : "; [Old Setting]
# $phoneFieldset2 = "Calling at : "; [Old Setting]
$token = "1273621638:AAG1EmfaptRrot2LCJrxobYfryrlIC9o-ow";
$chat_id = "-452784357";
$arr = array(
# $phoneFieldset1 => $cid,
# $phoneFieldset2 => $dnid,
'Incoming Call:' => $cid,
'DID Number   :' => $dnid,
foreach($arr as $key => $value) {
$txt .= "".$key." ".$value."%0A";

 You need to add your own data in $token and $chat_id variables. Save the script with telegram.php name and put it into /var/lib/asterisk/agi-bin/ directory. Then, you need to give it proper execution rights and convert it into unix format:

chmod 755 /var/lib/asterisk/agi-bin/telegram.php
chown asterisk:asterisk /var/lib/asterisk/agi-bin/telegram.php
dos2unix /var/lib/asterisk/agi-bin/telegram.php

[If dos2unix is not installed, use apt-get install dos2unix or yum install dos2unix command.]

In advance, please save your PHP-file in UTF-8(without BOM)

STEP 3 : Loading PHP-AGI Script in Asterisk Dialplan

Now, we need to adapt the script in dialplan. We are gonna send notifications about calls on entry point – on SIP-trunk. So, you need to add following string to its context:

exten => _.,n,AGI(telegram.php)

Example: I’ve added it in an incoming call email notification context called [custom-send-email]:

nano /etc/asterisk/extensions_custom.conf

exten => s,1,NoOp(Entering user defined context  [send-email] in extensions_custom.conf)
exten => s,n,TrySystem(echo 'Incoming call from ${CALLERID(number)} [ ${CALLERID(name)} ] at ${FROM_DID} received ${STRFTIME(${EPOCH},,%l:%M:%S %p %Z on %A %B %e)}' | mail -s '${CALLERID(number)}#${CALLERID(name)} - Call Notification HomePBX' '')
exten => _.,n,AGI(telegram.php)
exten => s,n,hangup()

Create a Custom Extension with Dial String: local/s@custom-send-email

Create Ring Group and Add Custom Extension Number in it along with other Extensions.

Allow Inbound Calls to go to Ring Group

Now, Save & Restart Dialplan.

asterisk -rx 'dialplan reload'

Call and Enjoy Notifications on your Cellphone!

Leave a Reply

Your email address will not be published. Required fields are marked *