Asterisk Unattended Dialout

From XAP Automation
Revision as of 13:38, 23 February 2007 by Gregg (Talk | contribs)

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 following is a sample AEL context:

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

Ancillary asterisk macro and global variable declaration

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).

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});
       };
};

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.

Sending xAP Messages


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 w/ whatever characters you want (that are allowed by xAP). Do realize that some text, numbers, dates, etc. do occasionally have problems w/ TTS conversion. That's where the latest mods to axc for pronunciation come into play (more on that later). Eventually, number lists for multiple number tries and/or "fancier" multi-dial capability will be integrated.