Freeswitch Modules

This section describes some of the popular and useful freeswitch module. Although there are many more modules, I have picked a few of commonly used one and divided them into categories

modules supported on freeswitch
FreeSwitch SIP and Media Server

Logger modules in Freeswitch

mod_console
mod_graylog2
mod_logfile
mod_syslog

mod_yaml

Multi-Faceted
mod_enum is a dialplan interface, an application interface and an api command interface
mod_enum

XML Interfaces in Freeswitch

mod_xml_rpc
mod_xml_curl
mod_xml_cdr
mod_xml_radius
mod_xml_scgi

Event system and Event Handlers in Freeswitch

Event Driven Archietctural (EDA) systems Design forms the basis for horizontly scalable, distributed and modular design. Such system primarily use event consumers, processing, producers and an effificient messaging system.

The core engine of freeswitch too manages and coordinates events with the help of messaging bus and handlers between itself and modules. 

Event-Name: HEARTBEAT
Core-UUID: 16ba2a54-a955-11ec-9087-b79e790df649
FreeSWITCH-Hostname: altanai-Inspiron-15-5578
FreeSWITCH-Switchname: altanai-Inspiron-15-5578
FreeSWITCH-IPv4: 192.168.0.121
FreeSWITCH-IPv6: %3A%3A1
Event-Date-Local: 2022-03-21%2013%3A32%3A26
Event-Date-GMT: Mon,%2021%20Mar%202022%2020%3A32%3A26%20GMT
Event-Date-Timestamp: 1647894746220214
Event-Calling-File: switch_core.c
Event-Calling-Function: send_heartbeat
Event-Calling-Line-Number: 81
Event-Sequence: 539
Event-Info: System%20Ready
Up-Time: 0%20years,%200%20days,%200%20hours,%206%20minutes,%2040%20seconds,%20195%20milliseconds,%2031%20microseconds
FreeSWITCH-Version: 1.10.4-dev%2Bgit~20200518T172205Z~91f54340ed~64bit
Uptime-msec: 400195
Session-Count: 0
Max-Sessions: 1000
Session-Per-Sec: 30
Session-Per-Sec-Last: 0
Session-Per-Sec-Max: 0
Session-Per-Sec-FiveMin: 0
Session-Since-Startup: 0
Session-Peak-Max: 0
Session-Peak-FiveMin: 0
Idle-CPU: 86.633333

Among other events some of the call and system events can be

Channel events

  • CHANNEL_CALLSTATE event, CHANNEL_CREATE event, CHANNEL_APPLICATION event
  • CHANNEL_DESTROY event, CHANNEL_STATE event, CHANNEL_ANSWER event
  • CHANNEL_HANGUP event, CHANNEL_HANGUP_COMPLETE event
  • CHANNEL_EXECUTE event, CHANNEL_EXECUTE_COMPLETE event
  • CHANNEL_BRIDGE event, CHANNEL_UNBRIDGE event
  • CHANNEL_PROGRESS event, CHANNEL_PROGRESS_MEDIA event
  • CHANNEL_PARK event, CHANNEL_UNPARK event
  • CHANNEL_HOLD event, CHANNEL_UNHOLD event
  • CHANNEL_ORIGINATE event, CHANNEL_OUTGOING event
  • CHANNEL_UUID event

System events

  • SHUTDOWN,
  • MODULE_LOAD, MODULE_UNLOAD, RELOADXML
  • NOTIFY,
  • SEND_MESSAGE, RECV_MESSAGE
  • REQUEST_PARAMS, CHANNEL_DATA
  • GENERAL, COMMAND
  • SESSION_HEARTBEAT, CLIENT_DISCONNECTED, SERVER_DISCONNECTED
  • SEND_INFO, RECV_INFO
  • CALL_SECURE, CALL_UPDATE
  • NAT
  • RECORD_START, RECORD_STOP
  • PLAYBACK_START, PLAYBACK_STOP

Events can be listened to using ngrep

> sudo ngrep -d lo -q -W single port 8021

interface: lo (127.0.0.0/255.0.0.0)
filter: ( port 8021 ) and ((ip || ip6) || (vlan && (ip || ip6)))

or also using telnet 

> telnet 127.0.0.1 8021

Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.
Content-Type: auth/request

auth ClueCon

Content-Type: command/reply
Reply-Text: +OK accepted

Event handling modules

mod_amqp

This module provides a connection amqp server like RabbitMQ. It can process API commands and can also filter for which events to send.

mod_cdr_csv

log call detail records (CDRs) to a text file using text generation templates as in /conf/autoload_configs/cdr_csv.conf.xml

<configuration name="cdr_csv.conf" description="CDR CSV Format">
<settings>
<param name="default-template" value="example"/>
<param name="rotate-on-hup" value="true"/>
<!-- may be a b or ab -->
<param name="legs" value="a"/>
</settings>
<templates>
<template name="sql">INSERT INTO cdr VALUES    ("${caller_id_name}","${caller_id_number}","${destination_number}","${context}","${start_stamp}","${answer_stamp}","${end_stamp}","${duration}","${billsec}","${hangup_cause}","${uuid}","${bleg_uuid}", "${accountcode}");</template>
</templates>
</configuration>

mod_event_socket

This modules opens a TCP socket and estbalishes bidirectional communication with the Core in clear text.

<configuration name="event_socket.conf" description="Socket Client">
  <settings>
    <param name="nat-map" value="false"/>
    <param name="listen-ip" value="::"/>
    <param name="listen-port" value="8021"/>
    <param name="password" value="ClueCon"/>
    <!--<param name="apply-inbound-acl" value="loopback.auto"/>-->
    <!--<param name="stop-on-bind-error" value="true"/>-->
  </settings>
</configuration>

Send Events over event socket

sendevent SEND_INFO
profile: external
content-type: text/plain
to-uri: sip:altanai@192.168.0.121:7060
from-uri: sip:test@192.168.0.121
content-length: 15
 
test

event received by freeswitch core 

nua_stack.c:529 nua_signal() nua(0x7f259c02c4b0): sent signal r_info
nua_stack.c:569 nua_stack_signal() nua(0x7f259c02c4b0): recv signal r_info
nta.c:2671 nta_tpn_by_url() nta: selecting scheme sip
tport.c:3282 tport_tsend() tport_tsend(0x7f25b8004e80) tpn = */192.168.0.121:7060
tport.c:4705 tport_by_addrinfo() tport_by_addrinfo(0x7f25b8004e80): not found by name */192.168.0.121:7060
tport.c:3619 tport_vsend() tport_vsend(0x7f25b8004e80): 605 bytes of 605 to udp/192.168.0.121:7060
tport.c:2766 tport_wakeup_pri() tport_wakeup_pri(0x7f25b4004e80): events IN
tport.c:2889 tport_recv_event() tport_recv_event(0x7f25b4004e80)
send 605 bytes to udp/[192.168.0.121]:7060 at 14:33:45.718269:
------------------------------------------------------------------------
INFO sip:altanai@192.168.0.121:7060 SIP/2.0
Via: SIP/2.0/UDP 192.168.0.121:7080;rport;branch=z9hG4bK823r928e970jF
Max-Forwards: 70
From: <sip:test@192.168.0.121>;tag=97py7UB0m8yjr
To: <sip:altanai@192.168.0.121:7060>
Call-ID: 6dc81996-2401-123b-109e-7c67a2ebffa5
CSeq: 49395333 INFO
Contact: <sip:mod_sofia@192.168.0.121:7080>
User-Agent: FreeSWITCH-mod_sofia/1.10.4-dev+git~20200518T172205Z~91f54340ed~64bit
Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REGISTER, REFER, NOTIFY
Supported: timer, path, replaces
Content-Type: text/plain
Content-Length: 15


��������

Other event handler modules

  • mod_cdr_sqlite
  • mod_zeroconf
  • mod_erlang_event
  • mod_smpp
  • mod_snmp
  • mod_event_multicast
  • mod_event_zmq

Directory Interfaces
mod_ldap

Endpoints

When any of the endpoints are loaded , they start listening for connection using configuration file . Dialstring identifies the recipient of the channel such as sofia/external/098099999 where sofia is the dial string prefix for SIP.

mod_portaudio

mod_alsa

mod_sofia – SIP protocol support

mod_gsmopen –  Supports voice & SMS over a GSM network

mod_h323 – H.323 , ITU rich media communication protocol.

mod_opal – IAX2

mod_skypopen – Skype (discontinued )

mod_dingaling – Jingle , Google Talk, XMPP integration ( discontinued )

mod_verto

mod_rtc

mod_loopback

mod_woomera

mod_freetdm – Provides support for telephony cards from manufacturers such as Digium, Sangoma and Zaptel. Can communicate in most legacy telephony protocols such as ISDN, SS7 & analog

mod_unicall

mod_skinny

mod_khomp

mod_rtmp

RTMP protocol is primarily used by Flash for streaming audio, video, and data over the Internet.

Applications

mod_commands

mod_conference

inbound and outbound conference bridge, loaded from file  conf/autoload_configs/conference.conf.xml
mod_curl

mod_db

-tbd

mod_dptools

Dialplan tools provide the apps (commands) to process call sessions in XML dialplans.

answer

Answer the call for a channel.

<!-- a sample IVR( Interactive Voice Response ) -->
<extension name="ivr">
<condition field="destination_number" expression="^9000$">
    <action application="answer"/>
    <action application="sleep" data="1000"/>
    <action application="ivr" data="demo_ivr"/>
</condition>
</extension>

att_xfer

Attended Transfer.

bgsystem

Execute an operating system command in the background.

bind_digit_action – Bind a key sequence or regex to an action.

bind_meta_app

Respond to certain DTMF sequences on specified call leg(s) during a bridge and execute another dialplan application.

block_dtmf

Block DTMFs from being sent or received on the channel.

break

Cancel an application currently running on the channel.

bridge

Bridge a new channel to the existing one.

bridge_export

Export a channel variable across any bridge.

capture

Capture data into a channel variable.

chat

Send a text message to an IM client

check_acl

Block originating address unless it matches an ACL.Test the i.p. address that originates the call against an Access Control List or CIDR mask

  • clear_digit_action – Clear all digit bindings
  • clear_speech_cache – Clear speech handle cache.
  • cluechoo – Console-only “ConCon” choo-choo train
  • cng_plc – Packet Loss Concealment on lost packets + comfort noise generation
  • conference – Establish an inbound or outbound conference call
  • deflect – Send a call deflect/refer.
  • delay_echo – Echo audio at a specified delay.
  • detect_speech – Implements speech recognition.
  • digit_action_set_realm – Change binding realm.
  • displace_session – Displace audio on a channel.
  • early_hangup – Enable early hangup on a channel.

Info, Intercept and eavesdrop

info – Display Call Info
intercept – Lets you pickup a call and take it over if you know the uuid.

eavesdrop -Spy on a channel.

<extension name="eavesdrop">
<condition field="destination_number" expression="^88(\d{4})$|^\*0(.*)$">
    <action application="answer"/>
    <action application="eavesdrop" data="${hash(select/${domain_name}-spymap/$1$2)}"/>
</condition>
</extension>
  • echo– Echo audio and video back to the originator.
  • delay_echo – Echo audio at a specified delay.
<action application="delay_echo" data="1000"/>

enable_heartbeat

Enable Media Heartbeat.

endless_playback

Continuously play file to caller.

enum – Perform E.164 lookup.
erlang – Handle a call using Erlang.
eval – Evaluates a string.
event – Fire an event.

execute_extension

Execute an extension from within another extension and return.

export

Export a channel variable across a bridge <varname>=<value>

fax_detect – Detect FAX CNG – may be deprecated.
fifo – Send caller to a FIFO queue.
fifo_track_call – Count a call as a FIFO call in the manual_calls queue.

gentones – Generate TGML tones.
group – Insert or delete members in a group.

Channel operations

set_name – Name the channel.

set – Set a channel variable for the channel calling the application.

global_getvar will list all globals such as 

freeswitch@altanai-Inspiron-15-5578> global_getvar

hostname=altanai-Inspiron-15-5578
local_ip_v4=192.168.0.121
local_mask_v4=255.255.255.0
local_ip_v6=::1
base_dir=/usr/local/freeswitch
recordings_dir=/usr/local/freeswitch/recordings
sounds_dir=/usr/local/freeswitch/sounds
conf_dir=/usr/local/freeswitch/conf
log_dir=/usr/local/freeswitch/log
run_dir=/usr/local/freeswitch/run
db_dir=/usr/local/freeswitch/db
mod_dir=/usr/local/freeswitch/mod
htdocs_dir=/usr/local/freeswitch/htdocs
script_dir=/usr/local/freeswitch/scripts
...

Dialplan Tools ( DPTools)

mod_dptool provides the commands to manage the call sessions

pre_answer – Answer a channel in early media mode.

hangup

Hang up the current channel.

<extension name="show_info">
<condition field="destination_number" expression="^9192$">
<action application="answer"/>
<action application="info"/>
<action application="sleep" data="250"/>
<action application="hangup"/>
</condition>
</extension>

ring_ready – Indicate Ring_Ready on a channel.
sleep – Pause a channel.
set_zombie_exec – Sets the zombie execution flag on the current channel.
session_loglevel – Override the system’s loglevel for this channel.

set_audio_level – Adjust the read or write audio levels for a channel.
verbose_events – Make ALL Events verbose (Make all variables appear in every single event for this channel).
transfer – Immediately transfer the calling channel to a new extension.[old wiki]
soft_hold – Put a bridged channel on hold.

  • hold – Send a hold message.

stop_displace_session – Stop displacement audio on a channel.
multiset – Set multiple channel variables with a single action.
log – Logs a channel variable for the channel calling the application
loop_playback – Playback a file to the channel looply for limted times

Preprocess

preprocess – description needed
presence – Send Presence
privacy – Set caller privacy on calls.
queue_dtmf – Send DTMF digits after a successful bridge.
read – Read Digits.

Wait

  • wait_for_silence – Pause processing while waiting for silence on the channel.
  • wait_for_answer – Pause processing while waiting for the call to be answered.

DTMF

  • send_dtmf – Send inband DTMF, 2833, or SIP Info digits from a session.
  • start_dtmf – Start inband DTMF detection.
  • stop_dtmf – Stop inband DTMF detection.
  • start_dtmf_generate – Start inband DTMF generation
  • stop_dtmf_generate – Stop inband DTMF generation.
  • send_dtmf – Send inband DTMF, 2833, or SIP Info digits from a session.
  • flush_dtmf – Flush any queued DTMF.
  • phrase – Say a Phrase.
  • Say time/date/ip_address/digits/etc. With pre-recorded prompts.
  • speak – Speaks a string or file of text to the channel using the defined TTS engine.[old wiki]

Limit

limit – Set a limit on number of calls to/from a resource
limit_execute – Set the limit on a specific application
limit_hash – Set a limit on number of calls to/from a resource
limit_hash_execute – Set the limit on a specific application

media_reset – Reset all bypass/proxy media flags.

mkdir – Create a directory.
mutex – Block on a call flow, allowing only one at a time
page – Play an audio file as a page.
park – Park a call.
park_state – Park State.
pickup – Pickup a call.

Play

  • play_and_detect_speech – Play while doing speech recognition.
  • play_and_get_digits – Play and get Digits.
  • play_fsv – Play an FSV file. FSV – (FS Video File Format) additional description needed
  • playback – Play a sound file to the originator.

Record

record – Record a file from the channel’s input.
record_fsv – Record a FSV file. FSV – (FS Video File Format)
record_session – Record Session.

recovery_refresh – Send a recovery refresh.
redirect – Send a redirect message to a session.
regex – Perform a regex.
remove_bugs – Remove media bugs.
rename – Rename file.
respond – Send a respond message to a session.

rxfax – Receive a fax as a tif file.

Schedule

sched_broadcast – Enable Scheduled Broadcast.
sched_cancel – Cancel a scheduled future broadcast/transfer.
sched_hangup – Enable Scheduled Hangup.
sched_heartbeat – Enable Scheduled Heartbeat.
sched_transfer – Enable Scheduled Transfer.
send_display – Sends an info packet with a sipfrag.

send_info – Send info to the endpoint.

DataBase

  • db – insert information into the database.
  • hash – Add a hash to the db.

Modules for Database

  • mod_mongo
 <configuration name="mongo.conf">
  <settings> 
  <param name="connection-string" value="mongodb://127.0.0.1:27017/?connectTimeoutMS=5000"/>
    </settings>
</configuration>

httapi

Send call control to a Web server with the HTTAPI infrastructure

Script

lua – Run a Lua script from the dialplan

javascript – Run a JavaScript script from the dialplan

ivr

Run an IVR menu.

JitterBuffer

  • jitterbuffer – Send a jitter buffer message to a session

Socket

socket – Establish an outbound socket connection.

set_profile_var – Set a caller profile variable.
set_user – Set a user.


sound_test – Analyze Audio.
stop_record_session – Stop Record Session.
stop_tone_detect – Stop detecting tones.

system – Execute an operating system command.
three_way – Three way call with a UUID.
tone_detect – Detect the presence of a tone and execute a command if found.
translate – Number translation.
unbind_meta_app – Unbind a key from an application.
unset – Unset a variable.
unhold – Send a un-hold message.

API

chat – Send a text message to a IM client.
presence – Send Presence.

mod_expr
mod_fifo
mod_hash

mod_voicemail
mod_directory
mod_distributor
mod_lcr
mod_easyroute
mod_esf
mod_fsv
mod_cluechoo
mod_valet_parking
mod_fsk

mod_sms
mod_smpp
mod_random
mod_httapi
mod_translate

Time

  • strepoch – Returns the date/time as a UNIX epoch (seconds elapsed since midnight UTC, January 1, 1970).
  • strftime – Returns formatted date and time.
  • strftime_tz – Returns formatted date and time in the timezone specified.

SNOM Module
mod_snom

This one only works on Linux for now
mod_ladspa

Dialplan Interfaces

mod_dialplan_directory
mod_dialplan_xml
mod_dialplan_asterisk

Codec Interfaces

mod_spandsp
mod_g723_1
mod_g729
mod_amr
mod_ilbc
mod_h26x
mod_vpx
mod_b64
mod_siren
mod_isac
mod_opus

File Format Interfaces

mod_sndfile
mod_native_file
mod_png
mod_shell_stream
For icecast/mp3 streams/files
mod_shout
For local streams (play all the files in a directory)
mod_local_stream
mod_tone_stream

Timers
mod_timerfd
mod_posix_timer

Languages

These scripting languages allow programming the call routing logic

mod_v8

FreeSWITCH has support for the Google V8 JavaScript (ECMAScript) engine. It needs to be uncommented in the modules.conf file

Screen Shot 2018-09-27 at 6.34.04 PM

mod_perl

mod_python

mod_java

mod_lua

ASR /TTS

mod_flite

mod_pocketsphinx
mod_cepstral
mod_tts_commandline
mod_rss

say

  • mod_say_en
  • mod_say_ru
  • mod_say_zh
  • mod_say_sv

Third party modules
mod_nibblebill
mod_callcenter

References

Leave a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.