====== Asterisk Call Notification ======

AstLinux now supports the [[https://github.com/mattn/gntp-send|gntp-send]] CLI tool for sending Growl (GNTP) notifications\\ via the GNTP 1.0 TCP protocol and also via the legacy Growl UDP protocol.

A simple shell script can be called via an Asterisk ''System()'' command, formulate the desired notification message, and send to a listening Growl endpoint using ''gntp-send''.

The notification can include CallerID name, number and extension, additionally an optional clickable link based on the CallerID number.

{{:userdoc:asterisk-call-notify-snarl1.png?nolink|Snarl Notification}}\\

{{:userdoc:asterisk-call-notify-snarl2.png?nolink|Snarl URL}}\\

\\
!!Note: AstLinux 1.2.10 or later is required!!

===== Asterisk Dialplan Integration =====

Using the classic ''Macro()'' call:

  [macro-growl-notify]
  exten => s,1,Set(OK=0-9a-zA-Z!#%&*+./<>?@[]_{}~\x20\x28\x29\x2c\x2d\x7c)
  exten => s,n,System(/mnt/kd/bin/asterisk-growl-notify-tcp '${FILTER(${OK},${CALLERID(name)}|${CALLERID(num)}|${ARG1})}' ${ARG2})
  ;
  ;...
  exten => 1234,n,Macro(growl-notify,${EXTEN},192.168.101.13)

Using the modern ''Gosub()'' call:

  [growl-notify]
  exten = s,1,Set(OK=0-9a-zA-Z!#%&*+./<>?@[]_{}~\x20\x28\x29\x2c\x2d\x7c)
   same = n,System(/mnt/kd/bin/asterisk-growl-notify-tcp '${FILTER(${OK},${CALLERID(name)}|${CALLERID(num)}|${ARG1})}' ${ARG2})
   same = n,Return()
  ;
  ;...
  exten => 1234,n,Gosub(growl-notify,s,1(${EXTEN},192.168.101.13))

Either executable shell script ''asterisk-growl-notify-tcp'' or ''asterisk-growl-notify-udp'' (below) can be called via the ''System()'' command, depending on the listening endpoint.

!!Tip ->!! The ''FILTER()'' function call is used to prevent remote command injection.

!!Tip ->!! Growl (GNTP) uses TCP port 23053, legacy Growl uses UDP port 9887.

\\
===== Growl (GNTP) over TCP =====

Below is an example shell script ''asterisk-growl-notify-tcp'' that can be customized to formulate the desired message notification.

!!Tip ->!! The ''growl_notify'' function call is run in the background since the return value is not needed and TCP takes longer to handle the connection.

  #!/bin/sh
  ##
  ## asterisk-growl-notify-tcp
  ##
  ## Usage: asterisk-growl-notify-tcp 'tel_name|tel_num|ext_num' client_ip
  ##
  
  ## Define ACTION_URL to add a clickable link, tel_num will be appended
  #ACTION_URL="http://local.example.com/lookup.php?num="
  
  ## Set to "yes" for North America Numbering, USA/Canada/etc.
  NANPA="yes"
  
  PASS="secret"
  
  ICON=""
  
  tel_name="$(echo "$1" | cut -s -d'|' -f1)"
  
  tel_num="$(echo "$1" | cut -s -d'|' -f2)"
  
  ext_num="$(echo "$1" | cut -s -d'|' -f3)"
  
  client_ip="$2"
  
  if [ -z "$client_ip" -o -z "$tel_num" ]; then
    echo "Usage: asterisk-growl-notify-tcp 'tel_name|tel_num|ext_num' client_ip" >&2
    exit 1
  fi
  
  ## Silently fail if client_ip is not reachable
  #if ! fping -t 200 "$client_ip" >/dev/null 2>&1; then
  #  exit 2
  #fi
  
  format_NANPA_number()
  {
    echo "$1" | \
    sed -r -e 's/^([2-9])([0-9]{2})([2-9])([0-9]{2})([0-9]{4})$/\1\2-\3\4-\5/' \
           -e 's/^(1)([2-9])([0-9]{2})([2-9])([0-9]{2})([0-9]{4})$/\1-\2\3-\4\5-\6/'
  }
  
  growl_notify()
  {
    local num date title msg url
  
    if [ "$NANPA" = "yes" ]; then
      num="$(format_NANPA_number "$tel_num")"
      date="$(ldate '+%l:%M %p on %A, %B %e')"
    else
      num="$tel_num"
      date="$(ldate '+%X %A, %B %e')"
    fi
  
    title="Incoming Call"
  
    msg="$tel_name"
    msg="$msg${msg:+\n}$num"
    msg="$msg${ext_num:+\nfor $ext_num}"
    msg="$msg\n${date## }"
  
    url="${ACTION_URL:+$ACTION_URL$tel_num}"
  
    gntp-send -s "$client_ip" -p "$PASS" -a "Incoming Call" -n "Incoming Call Notify" \
              "$title" "$(echo -e "$msg")" "$ICON" "$url"
  }
  
  growl_notify >/dev/null 2>&1 &

\\
===== Growl over UDP =====

Below is an example shell script ''asterisk-growl-notify-udp'' that can be customized to formulate the desired message notification.

!!Note ->!! The UDP version of Growl is compatible with older Growl implementations, such as Growl 1.2.2 for Mac OS X.

!!Note ->!! A clickable URL or custom icon is not supported with the older UDP version.

  #!/bin/sh
  ##
  ## asterisk-growl-notify-udp
  ##
  ## Usage: asterisk-growl-notify-udp 'tel_name|tel_num|ext_num' client_ip
  ##
  
  ## Set to "yes" for North America Numbering, USA/Canada/etc.
  NANPA="yes"
  
  PASS="secret"
  
  tel_name="$(echo "$1" | cut -s -d'|' -f1)"
  
  tel_num="$(echo "$1" | cut -s -d'|' -f2)"
  
  ext_num="$(echo "$1" | cut -s -d'|' -f3)"
  
  client_ip="$2"
  
  if [ -z "$client_ip" -o -z "$tel_num" ]; then
    echo "Usage: asterisk-growl-notify-udp 'tel_name|tel_num|ext_num' client_ip" >&2
    exit 1
  fi
  
  format_NANPA_number()
  {
    echo "$1" | \
    sed -r -e 's/^([2-9])([0-9]{2})([2-9])([0-9]{2})([0-9]{4})$/\1\2-\3\4-\5/' \
           -e 's/^(1)([2-9])([0-9]{2})([2-9])([0-9]{2})([0-9]{4})$/\1-\2\3-\4\5-\6/'
  }
  
  growl_notify()
  {
    local num date title msg
  
    if [ "$NANPA" = "yes" ]; then
      num="$(format_NANPA_number "$tel_num")"
      date="$(ldate '+%l:%M %p on %A, %B %e')"
    else
      num="$tel_num"
      date="$(ldate '+%X %A, %B %e')"
    fi
  
    title="Incoming Call"
  
    msg="$tel_name"
    msg="$msg${msg:+\n}$num"
    msg="$msg${ext_num:+\nfor $ext_num}"
    msg="$msg\n${date## }"
  
    gntp-send -u -s "$client_ip" -p "$PASS" -a "Incoming Call" -n "Incoming Call Notify" \
              "$title" "$(echo -e "$msg")"
  }
  
  growl_notify >/dev/null 2>&1

\\
===== Desktop Clients =====

=== Mac OS X ===
[[https://bitbucket.org/pmetzger/growl/downloads/|Growl 1.2.2f1]] (forked) version for Mac OS X works in the legacy UDP mode on newer OS versions (tested up to 10.13.6).\\ But it does neither support an icon nor a clickable URL in the notification.

[[https://itunes.apple.com/us/app/growl/id467939042?mt=12&ign-mpt=uo%3D4|Growl 2.x]] (__4 USD__ from the Mac AppStore) was __not tested__. The [[http://growl.info|Growl homepage]] notes: supported up to 10.9.5 (development has stalled!). 

=== Windows ===

[[http://snarl.fullphat.net|Snarl]] 3.1 and 5.0-beta-1 ([[https://sourceforge.net/projects/snarlwin/files/Snarl/R5/|from 01/2017]]) have been tested to work in TCP mode with the GNTP 1.0 protocol (tested on Win 10 64-bit, Win 7 32-bit).

[[http://www.growlforwindows.com/gfw/default.aspx|Growl for Windows]] Last version 2.0.9 is from 2012, __not tested__ (development has stalled!).

=== Linux Desktop ===

[[https://github.com/mattn/growl-for-linux|Growl for Linux]] Typically compile from source, __not tested__.  Same author as ''gntp-send''.

/*
The following dialplan approach replaces the deprecated "Notify()" application (app_notify). \\ An example dialplan (extensions.conf) snippet:

  [macro-notify]
  ;
  ; For Asterisk 1.8
  exten => s,1,Set(OK=0-9a-zA-Z!#%&*+./<>?@[]_{}~\x20\x28\x29\x2c\x2d\x7c)
  exten => s,n,System(/bin/echo -ne '${FILTER(${OK},${CALLERID(name)}|${CALLERID(num)}|${ARG1})}\\x00' | /usr/bin/nc -u -w1 ${ARG2} 40000 &)
  ;
  ; For Asterisk 1.4
  ;exten => s,1,Set(OK="0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!#%&*+./<>?@[]_{}~ \(\)\,-\|")
  ;exten => s,n,System(/bin/echo -ne \'${FILTER("${OK}","${CALLERID(name)}|${CALLERID(num)}|${ARG1}")}\\x00\' | /usr/bin/nc -u -w1 ${ARG2} 40000 &)
  ;
  ;...
  exten => 1234,n,Macro(notify,${EXTEN},192.168.101.13)

The desktop IP address may be numeric, as shown, or a DNS name may be specified, using the rightmost argument to the ''Macro(notify,...)'' call.  The UDP port number defaults to 40000 in the macro definition. 

=== Desktop Clients ===

**[[http://www.mezzo.net/asterisk/app_notify.html#osxclient|Mac OS X]]** - supports Growl, speech, iCal, Address Book
**[[http://www.mezzo.net/asterisk/app_notify.html#winclient|Windows]]** - using SNARL
**[[http://www.mezzo.net/asterisk/app_notify.html#linclient|Linux]]** - GNOME and Ubuntu
*/