Developing applications for FreeSWITCH
Have you ever wondered how VoIP calls work in Tuenti? Let’s find out a bit more about it.
At Tuenti we use FreeSWITCH, an open-source softswitch, for both VozDigital and App2App calls. If you don’t know what a softswitch is, you can think of it as the core of a telecommunications network. It basically connects the two legs (caller and callee) of a VoIP call.
FreeSWITCH is a scalable open source cross-platform telephony platform designed to route and interconnect popular communication protocols using audio, video, text or any other form of media. (https://www.freeswitch.org)
FreeSWITCH provides an API that exposes primitives for call control and IVR (Interactive Voice Response) functionality. Applications can access the API using Event Socket, an Internet socket-based communications interface.
Event Socket Library (ESL) is available for several different programming languages, including Java, JavaScript, Perl, PHP, Python and Ruby.
In this post, I'll talk about how to use the Event Socket Library to create a simple FreeSWITCH-based application that listens to a series of VoIP call events and eventually executes commands.
For this demo application I decided to use Node.js.
The first step is to create an empty Node.js application and add the Event Socket Library dependency in the package.json. For this demo I'll use modesl, which is one of the various ESL implementations available.
Now, you need to establish an Event Socket connection with FreeSWITCH. This can be done using the Connection(…) constructor of modesl.
Where FreeswitchConfig contains the FreeSWITCH IP, port and password.
For example:
Once you get a successful Event Socket connection, you need to subscribe to the FreeSWITCH events you're interested in. You can use the subscribe(…) method of Connection for this. Afterwards, you should start receiving events.
In the example above, you're subscribing to all FreeSWITCH events. However, you can also subscribe to only a particular kind of event.
For example, if you're only interested in DTMF (Dual-Tone Multi-Frequency) events, you can subscribe just to those (see code example below).
The received events have several fields (or headers). Some fields are included in all events, such as the Event-Name or the Event-Date-Timestamp, while others depend on the event type. For example, most call-related CHANNEL events include the Answer-State (e.g. ringing, answered, hangup, …) and the Call-Direction (e.g. outbound or inbound).
A complete list of events with their fields can be found at https://freeswitch.org/confluence/display/FREESWITCH/Event+List
You can get an event field using the getHeader(…) method of Event.
You can now connect to FreeSWITCH, receive events and read the fields.
However, you still don't have a way to execute commands in FreeSWITCH. Connection has two methods for executing commands: api and bgapi. The main difference is that api executes commands synchronously whilst bgapi executes them asynchronously.
For this demo, all commands should be executed asynchronously using bgapi to avoid making the service unresponsive.
You can now easily create simple use cases.
For example, you can use the uuid_getvar FreeSWITCH command to get channel variables.
There is a list of basic FreeSWITCH commands at https://freeswitch.org/confluence/display/FREESWITCH/mod_commands
The commands you have available may depend on the modules loaded in your FreeSWITCH.
So, now you have a working demo application that listens to FreeSWITCH events and executes commands. But if you're wondering, you can do a lot more with the Event Socket Library. It can also be used for executing applications over a channel, generating events from the ESL-side and a lot more! ;)
