Asterisk Unattended Dialout

From XAP Automation
Jump to: navigation, search

Introduction

Asterisk xAP Connector (axc) provides support to allow xAP messages to initiate automated, unattended, dial-out to a telephony number and generate a text-to-speech (TTS) message when the callee answers. Potential applications include:

  • alerts/warnings of HA-monitored conditions (e.g., alarm trip; high-temp limit reached)
  • notifications (e.g., presence/occupancy established)
  • reminders (e.g., "wake-up calls", other reminders if criteria not met)

Configuring Asterisk

Each inbound xAP message "targets" (or more accurately, is routed to) an asterisk "context". So, for each style/form of message sending, a separate asterisk dial-plan context must be created. The examples shown here use the Asterisk Extension Language (AEL) and would be typically found in /etc/extensions.ael (just create the file if it does not exist).

The following is a sample AEL context:

context axc-notify {
  s => {
     if ("${xapresponse}" != "") {
           &speak(${xapresponse},"");
           set(xapresponse="");
     };
     Hangup();
  };
};

Supporing asterisk macro and global variables

The speak macro is used to "wrap" the actual TTS implementation. This is particularly useful if you anticipate eventually changing or wanting to experiment with other speech engines since you only have to alter the global TTS variable; your dial-plan references to &speak will remain the same. Note that the "escapedigits" accepts a list of digits, that if pressed, will interrupt speaking (e.g., 12* will allow the 1, 2 or the * key to interrupt speaking).

macro speak(text,escapedigits) {
       NoOp(TTS=${TTS});
       if ("${TTS}" = "cepstral") {
          agi(cepstral.agi,${text},${escapedigits});
       } else if ("${TTS}" = "festival") {
          Festival(${text},${escapedigits});
       } else if ("${TTS}" = "swift") {
          Swift(${text});
       } else if ("${TTS}" = "flite") {
          flite(${text});
       };
};

Only a single global variable, TTS, is required. It is used to determine which TTS speech "engine" is used.

globals {
       TTS=cepstral;
};

Possible values for TTS are: (1) cepstral, (2) flite (dominant in most TrixBox installations), (3) Festival and (4) Swift (an alternative to the cepstral AGI).

Configuring axc

[axc-notify]
# optional; context will match the section title if not overriden
context=axc-notify
# optional; callerid that will be added to the line
cidnum=1234567890
# channel is required; it specifies the channel to be dialed
channel=IAX2/voicepulse01
# optional; timeout is time in seconds that the dial will be attempted
#    before hangup unless answered; default is 20
timeout=20
  • The attribute "channel" is the only required attribute. It must be set to the name of the channel used to dial the number. One exception is the case of dialing internal extensions--for example, SIP/123. In this case, channel would be set to "SIP" and the phone number supplied in the xAP message would be 123.
  • The attribute "context" can be omitted as axc will default to the section label. However, if you need or want to alter the name of the context within asterisk w/o altering your xAP scripts, then the name can be different.
  • The cidnum attribute value should be set to a proper callerid number anytime that you are using VoIP or any channel that allows you to alter your callerid. If sending over PSTN, this attribute can be ignored.
  • The "timeout" attribute specifies the maximum number of seconds that the dialed number will be attempted before dropping the call. This prevents an indefinite number of rings to the callee. A value of 20 seconds usually corresponds to approximately 4 rings. Note that there is currently no mechanism to easily detect whether the callee is a human or answering machine; so, prudent selection of a timeout may avoid calls to an answering machine if that is desirable.

Sending xAP Messages

Messages can be sent from any source that can generate messages using the Messenger.Event schema. Known "clients" include xAP Jabber. In addition, xAP "gateways" like xAP Floor Plan and misterhouse can send these messages via their in-built scripting support.

Sample xAP Messenger.Event message:

xap-header
{
  v=12
  hop=1
  uid=FF111300
  class=messenger.event
  source=mi4.jabber.Jabber
}
Message.Receive
{
  from=g.liming@someplace.somewhere
  body=axc-notify 18005551212 main alarm is tripped
}

The notable part that axc cares about is in the body attribute. It uses a syntax along the following:

body=<asterisk context> <numbertodial> <message>

Note that <asterisk context> must begin with "axc-". You can make <message> be as long as you want (subject to not overflowing the xAP packet) and using any characters you want (that are allowed by xAP). Do realize that some text, numbers, dates, etc. do occasionally have problems with TTS conversion. That's where the latest mods to axc for pronunciation come into play. Eventually, number lists for multiple number tries and/or "fancier" multi-dial capability will be integrated.