Skip to main content

mod_rayo

About​

mod_rayo is a server implementation of the Rayo protocol for FreeSWITCH. Rayo clients, like Adhearsion use this protocol to control calls.

Installing​

To use mod_rayo tell FreeSWITCH to compile in this module by editing modules.conf in /usr/src/freeswitch and adding:

modules.conf

event_handlers/mod_rayo
formats/mod_ssml

mod_ssml is REQUIRED by mod_rayo

Now recompile FreeSWITCH.

make make install

Tell FreeSWITCH to use the modules when running by adding them to modules.conf.xml in /usr/local/freeswitch/conf/autoload_configs:

modules.conf.xml

<load module="mod_rayo"/>
<load module="mod_ssml"/> 

Configuration​

The conf/autoload_configs/rayo.conf.xml file contains the following configuration settings. An example configuration is located in conf/rayo and can be installed with

make config-rayo

It is recommended that you start with the example rayo config and adjust the xmpp settings as needed

Core Settings​

rayo.conf.xml

<settings>
  <!-- maximum time in seconds to allow a call controlled by rayo to be idle.  Idle time is time measured since the last 
       command executed on the call.  Bridged (or conferenced) calls do not count as idle.  Increase this value as needed -->
  <param name="max-idle-sec" value="300"/>
  <!-- leave unchanged - this defines the mod_conference profile to use for mixers -->
  <param name="mixer-conf-profile" value="sla"/>
  <!-- if true (default), to attribute in offer has URI instead of destination number -->
  <param name="offer-uri" value="true"/>
  <!-- if true (false is default), channel variables are added to rayo client offer -->
  <param name="add-variables-to-offer" value="false"/>
</settings>

Recording Settings​

rayo.conf.xml

<record>
  <!-- This is the location to store recordings -->
  <param name="record-file-prefix" value="$${recordings-dir}"/>
</record>

Input Settings​

rayo.conf.xml

<input>
  <!-- This is the name of the ASR engine to use if none is specified by the Rayo client -->
  <param name="default-recognizer" value="pocketsphinx"/>
</input>

Fax Settings​

<fax>
  <!-- Location to store incoming faxes.  Can be a filesystem directory or an HTTP URL to PUT -->
  <param name="receivefax-file-prefix" value="/tmp/"/>
</fax>

Call Progress Analysis Settings​

Call progress analysis allows the client to request FS to monitor for dtmf, call progress tones, fax tones, voicemail beeps, etc. This feature works by mapping the dialplan applications and their detection events to Rayo CPA signal-types (fax-ced, fax-cng, beep, speech, dtmf, etc). If you have an alternative detector for specific tones, simply specify the new detector's dialplan start/stop app and the events emitted.

The only restriction is that no detector may detect the same event/subclass as previously defined detector.

<cpa> <!-- map DTMF events to CPA --> <detector name="core_dtmf_event"> <!-- map the FS core DTMF event to the Rayo dtmf signal-type --> <event class="DTMF" value-header="DTMF-Digit" duration-header="DTMF-Duration"> <signal-type value="dtmf"/> </event> </detector>

&lt;!-- map mod_spandsp fax detector to the Rayo CPA events. Fires DETECTED_FAX_* event once and quits. -->
&lt;detector name="mod_spandsp_fax_ced">
  &lt;start application="spandsp_start_fax_detect" data="event 'Event-Name=CUSTOM,Event-Subclass=DETECTED_FAX_CED' 500 ced"/>
  &lt;stop application="spandsp_stop_fax_detect" data=""/>
  &lt;event class="CUSTOM" subclass="DETECTED_FAX_CED">
    &lt;signal-type value="fax-ced"/>
  &lt;/event>
&lt;/detector>

&lt;detector name="mod_spandsp_fax_cng">
  &lt;start application="spandsp_start_fax_detect" data="event 'Event-Name=CUSTOM,Event-Subclass=DETECTED_FAX_CNG' 500"/>
  &lt;stop application="spandsp_stop_fax_detect" data=""/>
  &lt;event class="CUSTOM" subclass="DETECTED_FAX_CNG">
    &lt;signal-type value="fax-cng"/>
  &lt;/event>
&lt;/detector>

&lt;!-- map mod_spandsp call progress tone detector to Rayo CPA signal events.  Fires DETECTED_TONE events until stopped. -->
&lt;detector name="mod_spandsp_tone">
  &lt;start application="start_tone_detect" data="1"/>
  &lt;stop application="stop_tone_detect" data=""/>
  &lt;!-- map tone events to Rayo CPA signal type -->
  &lt;event class="CUSTOM" subclass="DETECTED_TONE" type-header="Detected-Tone">
    &lt;signal-type header-value="SIT" value="sit"/>
    &lt;signal-type header-value="BUSY_TONE" value="busy"/>
    &lt;signal-type header-value="REORDER_TONE" value="congestion"/>
    &lt;signal-type header-value="RING_TONE" value="ring"/>
  &lt;/event>
&lt;/detector>

&lt;!-- map mod_avmd detector to Rayo CPA beep event.  Fires avmd::beep event once. -->
&lt;detector name="mod_avmd">
  &lt;start application="avmd" data=""/>
  &lt;stop application="avmd" data="stop"/>
  &lt;event class="CUSTOM" subclass="avmd::beep">
    &lt;signal-type value="beep"/>
  &lt;/event>
&lt;/detector>

&lt;!-- Alternative beep detector using mod_vmd.  Fires vmd::beep events until stopped. -->
&lt;!--detector name="mod_vmd">
  &lt;start application="vmd" data=""/>
  &lt;stop application="vmd" data="stop"/>
  &lt;event class="CUSTOM" subclass="vmd::beep">
    &lt;signal-type value="beep"/>
  &lt;/event>
&lt;/detector-->

<cpa>

XMPP settings​

mod_rayo is an XMPP server. mod_rayo currently only supports serving a single XMPP domain.

insecure XMPP client connection example (use only on private networks!!!)

<!-- Set up server for rayo.example.com. Accept client connections to 10.50.0.10 from usera@rayo.example.com. --> <domain name="rayo.example.com" shared-secret="ClueCon"> <listen type="c2s" port="5222" address="10.50.0.10" acl=""/> <!-- Authorized users --> <users> <user name="usera" password="1"/> </users> </domain>

Secure XMPP client connection example. This example requires TLS when connecting to mod_rayo. You will need to generate a certificate and private key and store them in the certs directory.

<!-- Set up server for rayo.example.com. Accept secure client connections to 10.50.0.10 from usera@rayo.example.com. --> <domain name="rayo.example.com" shared-secret="ClueCon" cert="$${base_dir}/certs/rayo.example.com.crt" key="$${base_dir}/certs/rayo.example.com.key"> <listen type="c2s" port="5222" address="10.50.0.10" acl=""/> <!-- Authorized users --> <users> <user name="usera" password="1"/> </users> </domain>

The acl param is also available for an added layer of security. When enabled, only XMPP clients in approved networks will be accepted. Create a "rayo-clients" acl in conf/autoload_configs/acl.conf.xml and set the acl param:

<listen type="c2s" port="5222" address="10.50.0.10" acl="rayo-clients"/>

Dial gateways​

Dial gateways define call endpoint routes by mapping URI prefixes to FreeSWITCH dialstring prefixes. This allows Rayo to do things like route a call addressed by phone number to the PSTN over a FreeTDM endpoint vs. routing a call with a SIP URI over a mod_sofia gateway.

"default" is a reserved dial prefix that matches when all other matches fail.

<dial-gateways> <!-- default gateway - calls sent to outbound gateway if no dialprefix match is found --> <dial-gateway uriprefix="default" dialprefix="sofia/gateway/outbound/" strip="0"/>

&lt;!-- send SIP URI to mod_sofia -->
&lt;dial-gateway uriprefix="sip:" dialprefix="sofia/external/" strip="0"/>

&lt;!-- send tel:+16171234567 to mod_sofia after removing the tel: -->
&lt;dial-gateway uriprefix="tel:" dialprefix="sofia/gateway/outbound/" strip="4"/>

&lt;!-- Some examples of how to allow Rayo client to specify the FreeSWITCH dialstring -->
&lt;!-- pass through user and sofia unaltered -->
&lt;dial-gateway uriprefix="user" dialprefix="" strip=""/>
&lt;dial-gateway uriprefix="sofia" dialprefix="" strip=""/>

</dial-gateways>

Aliases​

Aliases are useful for testing. They allow you to map XMPP IQ requests to a short command. If the command is an IQ set command, you can omit the IQ from the alias as it is assumed by default.

An alias requires a "target". This target is used to assist with command autocompletion. That is, if the alias target is "call", then the alias will only suggest active calls when you tab autocomplete.

The possible targets are:

  • all

  • call

  • component (any component input/output/record/prompt)

  • external (clients and peer servers)

  • input (input components)

  • internal (anything not external)

  • server (mod_rayo server)

  • output (output components)

  • record (record components)

    <aliases> <!-- Answer a call offered to a Rayo client --> <alias name="answer" target="call"><![CDATA[<answer xmlns="urn:xmpp:rayo:1"/>]]></alias> <!-- Stop an active component --> <alias name="stop" target="component"><![CDATA[<stop xmlns="urn:xmpp:rayo:ext:1"/>]]></alias> <!-- Pause output --> <alias name="pause" target="output"><![CDATA[<pause xmlns="urn:xmpp:rayo:output:1"/>]]></alias> <!-- Resume recording --> <alias name="record_resume" target="record"><![CDATA[<resume xmlns="urn:xmpp:rayo:record:1"/>]]></alias> </aliases>

rayo APP​

Offer call to Rayo client. This is similar to the Outbound Event Socket "socket" application. If there are no Rayo clients connected to FreeSWITCH when the call is offered, the call is rejected.

<extension name="rayo"> <condition> <!-- Offer call to rayo client --> <action application="rayo"/> </condition> </extension>

rayo API​

Rayo admin console

This API is primarily for testing or checking the status of calls offered to Rayo clients.

rayo <alias> <jid>​

Execute an alias on a target JID

rayo answer a12dg45-123ffg-2314f@rayo.example.com

rayo status​

Show current status of all XMPP entities. This lists all active clients/calls/mixers/servers/components.

rayo status

rayo cmd <jid> <XMPP request>​

Send an XMPP <iq> request to an XMPP entity.

The IQ request is automatically filled with the proper from and to JIDs (Jabber IDs).

rayo cmd 10.50.0.10 <iq type="get"><ping xmlns="urn:xmpp:ping"/></iq>

rayo presence <jid> online|offline​

Send admin console <presence> to mod_rayo server.

By default, the admin console is offline and will not be offered calls. If you wish to test a call over via the console, you must send online presence to the mod_rayo server.

rayo presence 10.50.0.10 online

Now calls will be offered to the console client. "rayo answer <jid>" will take control of the call.

rayo msg <jid> <text message>​

Send a <message> to an XMPP entity

rayo msg c888@rayo.example.com How are you today?