Search icon CANCEL
Cart icon
Close icon
You have no products in your basket yet
Save more on your purchases!
Savings automatically calculated. No voucher code required
Arrow left icon
All Products
Best Sellers
New Releases
Learning Hub
Free Learning
Arrow right icon
Mastering FreeSWITCH
Mastering FreeSWITCH

Mastering FreeSWITCH: Advanced tips and tricks for advanced multimedia communication

By Russell Treleaven , Seven Du , Darren Schreiber , Ken Rice , Mike Jerris , Kalyani Kulkarni , Florent Krieg , Charles Bujold
€28.99 €19.99
Full star icon Full star icon Full star icon Full star icon Empty star icon 4 (1 Ratings)
Book Jul 2016 300 pages 1st Edition
€28.99 €19.99
€14.99 Monthly
€28.99 €19.99
€14.99 Monthly

What do you get with eBook?

Product feature icon Instant access to your Digital eBook purchase
Product feature icon Download this book in EPUB and PDF formats
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want
Buy Now
Table of content icon View table of contents Preview book icon Preview Book

Mastering FreeSWITCH

Chapter 1. Typical Voice Uses for FreeSWITCH

FreeSWITCH (FS) is one of the world's most robust Real Time Communication (RTC) switching tools. It packs a rich feature set, and its modular approach allows it to stay ahead of the curve as new technologies emerge in the marketplace.

With this strong foundation, FreeSWITCH has matured into a product which is in use in a multitude of environments. However, FreeSWITCH can also be complex and overwhelming because of its rich feature set.

This book unravels some of the ways FreeSWITCH can be utilized.

In this chapter, we will cover "traditional" Voice over IP usage. See other chapters for video, conferences, RTC, and so on. We will also cover the following:

  • Routing calls

  • Products and services

  • Development

  • Billing

Understanding routing calls in FreeSWITCH

Routing calls is the very essence of FreeSWITCH. Moving calls around can assume very different meanings and use very different techniques, depending on the scenario and with which aims it is done. You don't use the same tools and interaction level for an enterprise PBX, a telemarketing dialer, and a provider-to-providers minutes exchange.

FreeSWITCH's remote console at startup

Wholesale (provider to providers)

FreeSWITCH supports a multitude of useful features for call routing services. When we describe call routing, we are referring to connecting Party A with Party B. These routing scenarios are generally heavy on logic regarding cost analysis, interconnections with other carriers, and user permissions. These routing scenarios also typically exclude features the user directly interacts with (such as voicemail or auto attendants).

FreeSWITCH can be utilized as a powerful wholesale routing engine. Several built-in modules exist to assist in this, such as mod_lcr or mod_nibblebill, but the real beauty of FreeSWITCH's handling of calls in a wholesale scenario is due to four core building blocks:

  • The ability to remain in the audio path or get out of the audio path, as needed

  • The ability to transcode, which helps correct problems between pieces of VoIP equipment which aren't compatible

  • The ability to maintain information about caller and callee in variables, and to manipulate those values as the call is progressing (such as tracking how much money someone has left in their account, or what the per-minute rate of the call is)

  • The ability to bridge calls and handle failures and retries when calls don't connect, using a variety of call progress monitoring and failure handling routines which are built-in to FreeSWITCH

FreeSWITCH's flexible design aids in providing a tremendous amount of customization and capabilities as well. Examples include the ability to add transcoding support for codecs at any moment during the call in a way that will automatically and inherently work with any other codecs which are installed, and the ability to add custom handling for failures in a way that suits your environment.

Wholesale services typically represent high-volume customers who want to:

  • Configure a client for making calls and associate monetary value with each individual client ("current balance" or "amount spent" are examples)

  • Allow a client to attach phones, PBXs, other switches, or ancillary equipment

  • Track a client's usage of said service based on what they connected, where they called, and how long they talked, and potentially apply discounts or premium fees based on time-of-day, destination, or other variables

  • Detect fraud, abuse, or lack of funds automatically, both at call start and mid-call

  • Allow for prompts and menus to automatically add funds or "top-up" services

  • Allow for reporting

FreeSWITCH is capable, out of the box, of providing all of these services with simple dial plan configuration. Additionally, FreeSWITCH can be attached to a web, mobile, or legacy user interface to allow for users to manage their account, services, and monetary assets.

Residential uses of FreeSWITCH

FreeSWITCH stands as one of the best open source class 4 (and class 5) switch options, and is often the undisputed champ in many different roles because of the number of features offered by the many ready-made modules. It is definitely an excellent choice for the Internet Telephony Service Provider (ITSP), but let's not forget one of its simplest use cases: Residential service.

Some residential options include things like Network Address Translation (NAT) when configuring end-user devices like Analog Telephone Adapters (ATA). This can be challenging when working with disparate networks and client devices residing on LANs behind residential gateways and firewalls.

FreeSWITCH has configurable options for its Session Initiation Protocol (SIP) stack (called Sofia) especially designed to overcome these hurdles and provide a viable solution for residential service.

Some reasons why FreeSWITCH makes a good choice for residential service are:

  • It is easily embeddable in low power devices

  • It has easy configuration of end-user devices for home networks

  • It had standard voicemail services via mod_voicemail

  • It has advanced voicemail options using an Interactive Voice Response (IVR) enabled audio navigation system

  • It has custom scripting options for things like Unified Communications

Routing with federated VoIP

Federated VoIP is a distributed Voice over IP network composed of autonomous systems.

Federated VoIP is to telephony what internet e-mail is to messaging. Particularly, it allows for the free flow of traffic without depending on a central exchange (or exchanges), just like e-mail does not depend on a central post office. It works by exchanging mail messages directly between organizations' (or even personal) Mail Servers that have the authority and capability of managing their own traffic.

Let's continue with the example of e-mail (of note, SIP was based on SMTP and HTTP protocols, that is, the protocols that orchestrate mail and the Web). So, here's the trick: no central authority is involved, it's all peer-to-peer exchange of messages in a worldwide network that works with extreme overall reliability day in and day out for billions of people and trillions of communication exchanges.

Exactly the same criteria can be applied to Voice over IP (SIP) and Instant Messaging (SIMPLE or XMPP), basing all communication exchanges around the concept of a personal address like an e-mail address, which is used both by SIP and IM, and often exactly the same for both clients. The example address could be used for all unified communications with Joe.

Initially, VoIP had been popularized as a better and cheaper way to manage traditional telephony traffic and to connect to traditional voice carriers. Then it was adopted by the carriers themselves because of its better suitability to modern digital networks and compatibility between hardware providers. So, today's approach to VoIP often brings an unnecessary prejudice about dependency from carriers.

Federated VoIP gets rid of this, having autonomous servers exchanging their communications, finding each other via DNS (queries about destination address) without the need for central authority and/or carriers, just like the e-mail system. Around this core concept has grown an ecosystem of encryption, mapping, and resolving traditional telephone numbers via DNS (ENUM) and other additional services. It should be noted that there is no technical requirement for encryption in Federated VoIP.

FreeSWITCH has all the features needed by Federated VoIP:

  • Full encryption support: TLS and STCP for signaling, SRTP and ZRTP for media

  • DNS SRV query support

  • ENUM mapping support

  • NAT traversal support

  • Full codec support and transcoding

  • IM support via SIP's SIMPLE (can be gatewayed by an XMPP server like Jabberd)

  • Presence support via SIMPLE (can be gatewayed by an XMPP server like Jabberd)

  • FreeSWITCH can act as an inbound and outbound gateway with PSTN and cellular networks (for example, GSM, etc), offering ENUM termination service to calling parties

FreeSWITCH is able to work as a complete, self-sufficient autonomous system or as a part of a bigger composite system with one or more SIP proxies, like Kamailio or OpenSIPS, taking care of routing, proxying, load balancing, and so on.


The subject of dialers and telemarketing often makes system administrators and telephony switch operators queasy with anxiety when they are considering the limitations of their networks, hardware capability, and other system resource implications with the onslaught of marketing campaigns directed to their customers. This certainly does not stop FreeSWITCH from being a great choice when writing dialer and telemarketing applications, and not all dialer and telemarketing systems should have negative connotations.

FreeSWITCH is a natural front-runner when choosing a softswitch for writing dialer and telemarketing applications because of the small learning curve needed to develop applications in a variety of programming languages, and the excellent community support.

A developer can create a custom dialer application in FreeSWITCH utilizing a core switch database data in real-time to drive the logic. They can utilize modules like mod_event_socket to connect to the switch and perform API functions like initiating calls and managing IVRs for things like credit card payment, billing and collection, or opt-in and opt-out campaign functionality.

Not all telemarketing and dialer applications are used for marketing. Some ways FreeSWITCH is currently being utilized for dialers and telemarketing are:

  • Delivering inclement weather school-closing notification recordings to telephone lists

  • Auto-dialing church congregation members to connect them to IVR applications for surveys and volunteering

  • Notifying political constituents of party meetings and gatherings

  • Live agent outbound calling for fundraising or event coordination

    Some rows from FreeSWITCH's remote console help

FreeSWITCH Products and Services

Another way to see what FreeSWITCH can do is to think in terms of what services it will give its users. Here, too, different technologies and techniques are deployed to cater to different kinds of users, looking for a different set of features.

Business PBX services (hosted and on-premises)

FreeSWITCH's scalability and feature set lends itself naturally to being used as the basis of an extremely powerful business PBX phone system. Successfully deployed in both on-premises environments for small SOHO businesses while scalable to hundreds of users, or utilized as the foundation for hosted PBX services hosting hundreds of thousands of users, the system lends itself naturally to powering these types of solutions.

Out of the box, FreeSWITCH includes basic PBX modules which provide powerful functionalities. These modules include features such as:

  • Ring groups (simultaneous and sequential)

  • Call forwarding

  • Presence

  • Text to speech

  • Call queues

  • Caller ID blacklists

  • Caller ID name delivery

  • Privacy features / anonymous calling

  • CDRs / Call logs

  • Eavesdrop / whisper

  • Voicemail

  • Music on hold (w/ streaming sources)

  • Usage limiting

  • Call pickup / group pickup / call intercept

We could go on further, but this is a good general idea of the building blocks that are provided. Most of these modules can be activated by adding four to six lines of XML to a dial plan configuration file. The power of dial plan combined with modules should not be underestimated - this is powerful stuff with very little work to get it going!

Additional components exist for expanding into:

  • Chat

  • Messaging / SMS

  • HTTP services

Customer demands will sometimes lead to more complex requirements that might not be handled by default modules. However, ready-made building blocks combined with the ability to run your own custom scripts within FreeSWITCH allows for providing quick time to market services even for the most demanding customer base.

Call centers

Any company doing substantial business in any market segment will attest that support is a cornerstone of a business's success. A robust and comprehensive telephony platform is crucial, and FreeSWITCH allows for a configurable, scalable and maintainable solution suitable for call centers of any size.

There is no shortage of flexibility with FreeSWITCH. If your solution requires a custom application, FreeSWITCH provides a host of development options for your call control and routing. Although you are free to use any supported language to "roll your own" solution, FreeSWITCH comes complete with robust call center modules that are being utilized in production environments in literally thousands of deployments all over the world.

Mod call center includes features like:

  • Multi-tenant capability

  • Multiple agent call-distribution strategies, such as :

    • Longest idle agent

    • Round robin agents

    • Agent with least talk time

    • Agent with fewest calls

    • Top-down tier position escalation

  • Time-based scoring escalation strategies like:

    • Total time in system

    • Time in current queue

  • Caller configuration options:

    • Maximum wait time

    • Maximum wait time with no agent

  • Tier rule configuration options:

    • Wait time

    • Skip tiers with no agents

    • Discarded abandoned callers

    • Resumed abandoned callers

  • Recurring announcements with time frequency interval settings

With IVR trees easily integrated into your call center solution and full access to databases for CRM and Knowledge Basis, your ability to create call center applications is almost limitless.

If your requirements do not dictate the granularity of complex configuration options, then there are other options available with an alternative FreeSWITCH module called Mod FIFO. As the name implies, it serves as a first in, first out call-queuing mechanism, with many features and strategies, music on hold, and announcements, that's easy to integrate in custom or third-party applications.

Value added services and games, prizes, and polls

Value Added Services (VAS) are services that offer something on top of pure voice transport.

Some examples include:

  • Real time translations (for example, three-way calls with an interpreter)

  • Party lines (for example, multiple-way calls)

  • Virtual meetings (for example, conferences with or without moderator)

  • Cooperative Environments (for example, audio-video-screensharing-whiteboarding)

  • Fax-on-demand

  • Call screening-whitelisting-blacklisting

  • SMS feed subscriptions (news, traffic, special interests, and so on)

Interactive entertainment and polling is a business that fits perfectly with the ease of programming and integrated messaging capability of FreeSWITCH.

Here are some examples of what has been realized in this field:

  • Radio and TV live talk shows that allow for the public to ask questions and vote on issues, both through voice calls and via SMSs

  • Voice menu trees that ask questions to customers, giving them prizes after a number of correct answers (for example, product awareness and loyalty)

  • Redeem-the-code types of campaigns, where customers or the public can enter a code they found on your documentation or advertising to be awarded a bonus, both via SMSs and voice calls with DTMF

  • Incoming calls statistics (comparative ROI analysis on multiple channel advertising campaigns, for example, what they call the most, the number advertised on radio, TV, Internet, or the one in the press?)

"Class 4" vs "Class 5" operations (and SBCs)

FreeSWITCH is a softswitch. That is, it is a software that handles and interconnects calls, like the manual switchboards where operators answered and distributed calls by moving jacks and cables in old black and white movies.

Softswitches in telco jargon are often categorized as pertaining to a "class," and "Class 4" and "Class 5" are the only two classes you will hear about.

Because those are fuzzy terms, almost marketing terms, you will never find the exact demarcation between Class 4 and Class 5 features and capabilities; a lot of them overlap (anyway, it's mostly the same technology).

An arbitrary rule of thumb can be to use Class 4 when talking about large volume, wholesale switching of call minutes between different carriers, ITSPs, CLECs, with minimal meddling in the audio streams (apart from transcoding, if needed). The term "Class 5" applies to audio or text-based services where end user interaction is in focus and where sophisticated logic is required.

FreeSWITCH is widely used in both contexts.

A typical Class 4 usage would be to interconnect many providers of international voice routes and sell voice minutes based on algorithms about least cost route and/or route quality. Here, the sheer volume of signaling that can be managed per second and the availability of very efficient ways to lookup which route to connect to is of paramount importance. FreeSWITCH with "bypass media", mod_lcr, mod_easyroute, some Lua scripting or custom C code is a perfect platform, easy to use and modify on the fly, without service interruption.

Typical Class 5 usages would be an enterprise or SOHO PBX, a call center system, a fax server with mail2fax and fax2mail, an airport IVR to query flights' arrival times, and so on. Here, FreeSWITCH offers prized features like audio quality (that is, no glitches, distortions, and so on), programmability (how easy it is to implement complex services and business logic), capability of interfacing different media (PSTN to WebRTC, SIP to Skinny, TDM to Skype, SMS to XMPP, and so on) and different audio formats (alaw, ulaw, High Definition Audio, Silk, Siren, G729, Opus, mp3, wav, raw, and so on). Easy integration of Text To Speech and Automatic Speech Recognition, manipulation of audio prompt libraries, and easy ways to gather and interact with user pressed DTMFs are the highlights in FS Class 5 operation.

"SBC" is another very vague marketing buzzword. A Session Border Controller (SBC) is a softswitch that sits on the edge of your own telecommunication network and acts as a point of demarcation and interconnection with the external world. Let's say an SBC is a softswitch with an emphasis on security, NAT traversal, media proxying, network connectivity, manageability, audio transcoding, protocol gatewaying (connecting with different protocols), and protocol adaptation (being the compatibility layer between different "interpretations" of the same protocol). FreeSWITCH excels in those areas, as we have seen before in the two "Classes", while it sports specific SBC features like the most advanced NAT traversal, so smart that it can connect endpoint (that is, user phones) behind residential ADSLs and firewalls, or form a federation between the many international offices of a company, each SBC sitting on different NATed LANs. Also, as security goes, FreeSWITCH is one of the reference implementations for ZRTP media encryption, as well as TLS and SIPS.

WebRTC / web services / Internet-only services

FreeSWITCH's unique modular approach made it an easy choice for extending integration into WebRTC and other web-based services which need a bridge between different types of technologies. As an example, web-based communications are useful but are often hindered by their inability to connect to the rest of the established world, causing adoption to be slow. As an example, users will be reluctant to get rid of their desk phone when their browser-based replacement can't call phone numbers but only other browsers. Best of all, WebRTC support follows the same ease-of-installation and global compatibility standards that FreeSWITCH has become known for in the VoIP world. Users can make calls where one side of the conversation is WebRTC and the other is the PSTN, or WebRTC to SIP and so on. FreeSWITCH does all the hard work of normalizing the audio and signaling services between the two services and bridging any gaps that may exist when connecting from one type of service to another.

Mobile "over-the-top" SIP

As mobile services become more pervasive in the telecommunications industry, mobile network operators have responded by increasing data speeds. In this process, many service providers are now investigating "over-the-top" services which utilize data communication services to transmit and receive voice and video. These services often link to messaging or social applications and provide both real-time, semi real-time, and recorded communication services via data connections. In many cases, the user experience simulates phone technology even though it is not using traditional telephony services provided by the underlying communications service provider. In these cases, there is added complexity for handling such services.

Over-the-top services face a number of challenges, which include:

  • The ability to adapt to rapidly changing network performance characteristics

  • The ability to "hand off" calls as different networks which have better qualities come into range (that is, moving from 3G to 4G or 3G to WiFi)

  • Selecting appropriate codecs which match available capacity and bandwidth

  • Having sufficient buffering and audio stream management strategies to allow for quality communication while being resilient to issues in network consistency

  • Providing feedback to the user to allow her to understand what is happening during these complex shifts

  • The ability to track device configuration and usage information as customers roam to various locations, change devices, and so on.

  • The ability to adapt to networks which block or restrict some kind of traffic

  • Integrating with various types of physical hardware on the user's device

  • Being able to debug issues when it's unclear if they're caused by the device, the mobile network, or the softswitch

Despite the various unique challenges over-the-top apps pose, the attractive promise of cheaper phone calls integrated into social, e-mail, or other methods of communication remains a popular target for many companies.

With these goals and issues in mind, where does FreeSWITCH fit in? It should come as no surprise that FreeSWITCH is a great match for solving these challenges. While less discussed within the FreeSWITCH community, FreeSWITCH contains hidden gems for features such as:

  • Managing a jitter buffer manually, where you can account for non-standard network environments

  • Support for STUN, TURN, ICE, and alternate signaling ports and methods (such as UDP and/or TCP), and the ability to bridge between endpoints using different methods

  • The ability to select codecs on the fly on a per-call basis, which is useful in conjunction with a mechanism to detect current network conditions

  • The ability to handle unexpected events gracefully (such as dropped calls) where strategies can be taken to reconnect a caller automatically without dropping both sides

  • Rich statistics and RTCP feedback implementation providing real-time information to both caller and callee about the quality of the transmission

These are just some of the building blocks that make FreeSWITCH unique when attempting to solve these over-the-top problems. Make no mistake, over-the-top applications are still a challenge. But FreeSWITCH gives you a huge head start in tackling these problems.

Skype to SIP call, seen from FreeSWITCH's remote console


FreeSWITCH is often considered the perfect development tool, particularly in enterprise, startup, and telco environments.

Strict on output, broad on input

The philosophy underlying FS architecture lends itself perfectly to interface legacy, commercial, and proprietary hardware/software: FS output is very, very strict in its adherence to the letter of the standards (SIP and related RFCs), so it's able to make itself understood by whatever it's trying to communicate with, but it is also very, very flexible for what it accepts as an input, for example, core developers embedded into FS, all the quirks, and the workarounds, to let it accept the often non-standard (or plain wrong) "interpretation" and "extensions" of SIP standards that have been pushed on the market by the various generations of VoIP software and hardware providers (often with the "unintended" side effect of locking in their customers).

Very structured, very reusable techniques

FS is built around mainstays of modern technology: XML, message queues, JSON, RPC, and standard libraries. Developers don't have to learn new ad hoc "languages" to fully exploit the power of FS: All of its configuration, dialplan, upstream and downstream endpoints and gateways — all of its features and behaviors are completely defined by XML standard documents that can also be created in real time dynamically by tried and true XML generating applications and languages. Given a basic knowledge of communication fundamentals, a wealth of pre-existing, in-house knowledge of structured information management can be reused.

Polyglot by vocation and destiny

All kinds of programming languages can be used to interact with FS. This is due to the fact that we're dealing with two main paradigms, XML and message queues (and also XML exchanged back and forth via message queues). All computer languages, both scripted and compiled ones, have very efficient, stable and performing ways to interact with XML structured information, from C to Basic, from Perl to PHP, Python to Lua, Erlang to C# to .NET, Java and all the others in between. Interacting with the message queues governing and reporting FS behavior is done through a simple API that is the same for all languages covered by SWIG: In each language you'll find the same "objects" with the same "methods" (or "functions") and "attributes" to interact with.

Extreme scalability, from embedded to big irons

Different tasks are best performed by different devices, with different price points, power consumption, sets of hardware interfaces: From WRTG routers to Raspberry PIs (for example, for residential CPE, or as WiFi VoIP, or as a portable communication gizmo), from desktop PCs (as a personal or callcenter softphone) to multisocket multicore massive servers (capable of delivering high call per second origination and termination) and powerful DSP blades (for high capacity call transcoding, Text To Speech generation, Automatic Speech Recognition and media management). For all of those roles we can use the same FreeSWITCH software, that behaves and is managed in the same way.

Born internationalist

Using the same foundation system library as the ubiquitous Apache Web Server, FS runs at full efficiency on Linux, Windows, FreeBSD and Solaris, on Xen, AWS, KVM, and VMWare. DevOps people often prefer to use their own deployed, stable, and known operating systems and managing tools.

Telcos internal integration ("FreeSWITCH is the Perl of VoIP")

Telcos, telecommunication companies, both the old Bells and the new CLECs or VMOs, are a fascinating patchwork of legacy, proprietary, in-house developed, partner-provided, stakeholder-imposed hardware and software. With all kinds of database engines (Oracle, DB2, SQL Server, SAP, MySQL, PostgreSQL, and so on), directory systems (LDAP, Active Directory), AAA mechanisms (Radius, Diameter, and so on), SIP and SS7 equipment (some of which nobody knows how to operate anymore, "so please don't touch it"), and many different functions and departments barely interacting with each other, there can be huge return time for even the smallest feature request or bug turnaround.

In a complex environment like this, FS can be introduced as universal filter and glue, allowing incompatible systems to communicate (as protocol translator and adapter), transcoding to and from all audio formats (ulaw to mp3 to High Definition Opus, Siren, Silk, etc), manipulating signaling and log generation for billing, accounting, tracking, charting, debugging purposes (additional and optional SIP packet headers injection and parsing, CDR generation, mediation, reconciliation, and so on), and database interfacing (native, odbc, REST, SQL, NoSQL, and so on).

FreeSWITCH is accepted into telco environments because of its known stability and "industrial grade" structure, and because it does not carry any "hobbyist" or "hackerish" fame.

Starting from resolving specific problems with "ad hoc", Swiss army knife solutions, FreeSWITCH can then expand its internal reach to prototype new features and services, substitute unwieldy legacy systems (for example, IVRs, fax servers, and so on), and quickly become the poster boy of Sales and Marketing departments for quick implementation and flexibility, while gaining the Operations respect and love for its stability, performances, and manageability.

Rapid new services prototyping

Standard, real programming languages give FreeSWITCH a fast pace of implementation for any kind of features and services: What is simple stays simple, and what is complex becomes possible, without crashes, instabilities, or performance bottlenecks.

Programming languages bring with them all their wealth of libraries, both standard, open source, commercial, and in-house developed. So, all kinds of objects, systems, procedures are within reach, both bleeding edge external services and internal, legacy, proprietary, prehistoric leftovers.

Real business logic can be crafted without compromises, accessing each call in real time, at the desired abstraction level, from the most abstracted down to the detail of the single SIP packet.

WebRTC will allow entire new classes of applications and services, using the ubiquitous web browser as a communication endpoint, while FS modules exist for managing any kind of content, from real-time broadcast to video, from conferencing to queuing calls and managing call center operators.

Click-to-Call, database interaction, SMS sending and receiving, website complementing and synergy, full CMR integration, marketing campaigns, media redemption analysis, dynamic real-time events, horizontal scalability via tried and true load-balancing, cloud leveraging—all that and much more is what FreeSWITCH can be used for to speed up the time to market and implement convergent media multi-pronged strategies.

A debugging session, seen from FreeSWITCH's remote console

Accounting and billing

In telecommunications (and probably everywhere), accounting and billing are two separate logical entities, although there are cases (for example, real-time prepaid accounts) where they happen together and are strictly intertwined.

Accounting is keeping a tab on who gets what, for example, what metered services a user accessed, when the user accessed them, for how much time, and so on. Particularly, in telephony, which calls were made to what numbers, for how long, for each customer. This process involves generating and managing Call Detail Records (CDRs) for each and every call, where all the above details and much more are stored and can be retrieved. CDRs are also a precious source of debugging and troubleshooting information, allowing for the identification of which problems affected failed or low quality calls.

On the other hand, billing involves operating on the customer account, adding or subtracting "credits" related to the cost of the services accessed, with costs calculated based on unitary prices that can depend on multiple variables (from which prefix to which prefix a call was made, how long it lasted, at which time of day it was made, which route was chosen to connect it to the remote party, and so on). Also, in the case of prepaid credits and calling cards, there is often a requirement to not allow customers to access services after their credits expire, for example, if they have 10USD on account and the call costs 2USD/min, then after 5 mins the call has to be interrupted (perhaps with a message about how to top up the account). Cost calculation is often referred to as "rating," while the gathering of CDRs and their conversion into a uniform format ready to be rated is called "mediation."

Call Detail Records (CDRs)

FreeSWITCH has plenty of flexibility for CDR generation, in subtle and varied ways so as to accommodate all kind of operations, and provide this foundation layer for every business model.

Default CDRs are generated by FS's mod_cdr_csv as rows in files containing Comma Separated Values (CSVs). We can choose to keep track of the caller side (A leg), the callee side (B leg), or both (AB). For each leg we can have a row in the Master.csv, one in the specific caller CSV file, and/or one row in the specific callee CSV file.

The format and contents of those rows are defined by templates that allow us to record whatever mix of variables is suitable for our operation and business model, from any kind of timers (total duration, duration after answer, billable duration, and so on), to origination and destination numbers, time of day / day of week, individual account ID, company account ID, and so on.

There are various templates ready made in the FS distribution, among them one that generates CDRs in the same format generated by Asterisk (so to leverage legacy billing systems), and another one that generates files containing rows of SQL inserts, ready to be piped to a database client for further usage.

Another possibility for CDR generation (instead of or in addition to CSV files) is implementing mod_cdr_xml. Using XML allows for much more structured information to be put in the records, and can be sent real live via POST or GET to an HTTP server (which may itself enter rows into various database tables).

Mod_nibblebill / CGrateS

FreeSWITCH contains built-in modules to assist in real-time rating and credit management. Unique to FreeSWITCH is the ability to provide these services real time in a lightweight manner. With its multi-threaded design, billing and rating can be done on each leg of a call easily with different rates for each party, in addition to rates which might vary based on the selected carrier, time of day, number of calls currently active, or other such data.

One such module within FreeSWITCH that assists in this process is mod_nibblebill. A simple module at its core, nibblebill hooks into the heartbeat features FreeSWITCH provides for every leg of a call. On each heartbeat, nibblebill provides quick mathematical calculations about whether there are enough funds remaining to continue the call and logs to a database that the call has continued and to immediately deduct additional credit. This module is fairly lightweight for small to medium system capacity and can be expanded in larger systems by using basic database technologies already available. In addition, anyone who can program a database can program an interface to manage adding, subtracting, and tracking monetary value from a customer's account in conjunction with mod_nibblebill. This makes implementing the basics of a billing system easy. You can find many more details about mod_nibblebill in another Packt Publishing book, FreeSWITCH 1.2.

When combined with CDRs, you can also pair accounting and historical data with each call. This allows for a complete picture of billed services to a customer.

Other real-time tools exist such as Carrier-Grade Rating System, CGRateS, which links to FreeSWITCH and watches calls real time as they progress. Using FreeSWITCH's powerful event system, CGRateS monitors and manages calls as they happen and records data about the calls for reconciliation. CGRateS is an independent, open-source project, but is linked closely to the FreeSWITCH system for real-time handling of events happening on the switch, both as billing, anti-fraud, LCR, and thousands other features. CGRateS project developers are available for custom installation and implementation of complete solutions. On top of CGRateS engine, VoIPtology has developed CGRBilling, a commercial packaged solution with Web interface.

Other billing options (open source - commercial)

Many rating and billing systems exist out there, designed for the whole telecommunication market, or specifically for FreeSWITCH. That's because the entire telecom industry, since inception, has been the buyer and the research sponsor on billing systems. You can say that many computer advancements as a whole where targeted to advance telecom's billing systems.

Most of the industry relies on offline management of CDR files that are normalized, inserted into a database, and then massaged following business rules to obtain the single customer's bill for the period. With the advent of web interfaces that allow the customer to verify their own account in almost real time, the management flow cycle for CDRs has been shortened to be almost instantaneous, albeit still file-based. An open source, mature, and industrial grade example of this approach is JBilling.

On the other side, real-time billing open source applications are, in addition to the aforementioned CGRateS, ASTPP (complete solution, billing, rating, crm, lcr, and so on), Vbilling (complete solution, integrated with switch management), Viking (expanded from wholesale to cover retail too).

All of these open- source solutions are available with commercial support and backing, and by the time you're reading this book, a billing solution will probably be available for FusionPBX, the open source GUI for the management of FreeSWITCH.

Many pure commercial solutions and services are available, both as software install and as cloud services. Please check FreeSWITCH online documentation for an updated list.


In this chapter we have covered some of the many different use cases for FreeSWITCH, and we have seen how the different technologies that compose FS can be deployed using various techniques.

The key here has been the concept of toolset: FreeSWITCH is a focal point of real-time communication technologies that span the entire field, from billing to transcoding, from interactive voice attendant to least cost route management.

Also, we've seen how there are many ways to harness this power, to make FreeSWITCH cater to our own kind of users and business goals, using different tools for different aims, from XML to scripting languages, from databases to external services.

In the next chapters we will go deep into the rabbit hole, beginning with Chapter 2, Deploying FreeSWITCH, about production deployment best practices, that will show how to end up with a system that is reliable, manageable, robust, and performing.

Left arrow icon Right arrow icon
Download code icon Download Code

Key benefits

  • Forget the hassle - make FreeSWITCH work for you
  • Discover how FreeSWITCH integrates with a range of tools and APIs
  • From high availability to IVR development use this book to become more confident with this useful communication software


FreeSWITCH is one of the best tools around if you’re looking for a modern method of managing communication protocols through a range of different media. From real-time browser communication with the WebRTC API to implementing VoIP (voice over internet protocol), with FreeSWITCH you’re in full control of your projects. This book shows you how to unlock its full potential – more than just a tutorial, it’s packed with plenty of tips and tricks to make it work for you. Written by members of the team who actually helped build FreeSWITCH, it will guide you through some of the newest features of version 1.6 including video transcoding and conferencing. Find out how FreeSWITCH interacts with other tools and APIs, learn how to tackle common (and not so common) challenges ranging from high availability to IVR development and programming advanced PBXs. Great communication functionality begins with FreeSWITCH – find out how and get your project up and running today.

What you will learn

[*] Get to grips with the core concepts of FreeSWITCH [*] Learn FreeSWITCH high availability [*] Work with SIP profiles, gateways, ITSPs, and Codecs optimization [*] Implement effective security on your projects [*] Master audio manipulation and recording [*] Discover how FreeSWITCH works alongside WebRTC [*] Build your own complex IVR and PBX applications [*] Connect directly to PSTN/TDM [*] Create your own FreeSWITCH module [*] Trace SIP packets with the help of best open source tools [*]Implement Homer Sipcapture to troubleshoot and debug all your platform traffic

Product Details

Country selected

Publication date : Jul 29, 2016
Length 300 pages
Edition : 1st Edition
Language : English
ISBN-13 : 9781784398880
Languages :
Concepts :

What do you get with eBook?

Product feature icon Instant access to your Digital eBook purchase
Product feature icon Download this book in EPUB and PDF formats
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want
Buy Now

Product Details

Publication date : Jul 29, 2016
Length 300 pages
Edition : 1st Edition
Language : English
ISBN-13 : 9781784398880
Languages :
Concepts :

Table of Contents

21 Chapters
Mastering FreeSWITCH Chevron down icon Chevron up icon
Credits Chevron down icon Chevron up icon
About the Authors Chevron down icon Chevron up icon
About the Reviewers Chevron down icon Chevron up icon
Contributors Chevron down icon Chevron up icon Chevron down icon Chevron up icon
Preface Chevron down icon Chevron up icon
1. Typical Voice Uses for FreeSWITCH Chevron down icon Chevron up icon
2. Deploying FreeSWITCH Chevron down icon Chevron up icon
3. ITSP and Voice Codecs Optimization Chevron down icon Chevron up icon
4. VoIP Security Chevron down icon Chevron up icon
5. Audio File and Streaming Formats, Music on Hold, Recording Calls Chevron down icon Chevron up icon
6. PSTN and TDM Chevron down icon Chevron up icon
7. WebRTC and Mod_Verto Chevron down icon Chevron up icon
8. Audio and Video Conferencing Chevron down icon Chevron up icon
9. Faxing and T38 Chevron down icon Chevron up icon
10. Advanced IVR with Lua Chevron down icon Chevron up icon
11. Write Your FreeSWITCH Module in C Chevron down icon Chevron up icon
12. Tracing and Debugging VoIP Chevron down icon Chevron up icon
13. Homer, Monitoring and Troubleshooting Your Communication Platform Chevron down icon Chevron up icon
Index Chevron down icon Chevron up icon

Customer reviews

Top Reviews
Rating distribution
Full star icon Full star icon Full star icon Full star icon Empty star icon 4
(1 Ratings)
5 star 0%
4 star 100%
3 star 0%
2 star 0%
1 star 0%
Filter icon Filter
Top Reviews

Filter reviews by

James Ungar Mar 13, 2024
Full star icon Full star icon Full star icon Full star icon Empty star icon 4
Feefo Verified review Feefo image
Get free access to Packt library with over 7500+ books and video courses for 7 days!
Start Free Trial


How do I buy and download an eBook? Chevron down icon Chevron up icon

Where there is an eBook version of a title available, you can buy it from the book details for that title. Add either the standalone eBook or the eBook and print book bundle to your shopping cart. Your eBook will show in your cart as a product on its own. After completing checkout and payment in the normal way, you will receive your receipt on the screen containing a link to a personalised PDF download file. This link will remain active for 30 days. You can download backup copies of the file by logging in to your account at any time.

If you already have Adobe reader installed, then clicking on the link will download and open the PDF file directly. If you don't, then save the PDF file on your machine and download the Reader to view it.

Please Note: Packt eBooks are non-returnable and non-refundable.

Packt eBook and Licensing When you buy an eBook from Packt Publishing, completing your purchase means you accept the terms of our licence agreement. Please read the full text of the agreement. In it we have tried to balance the need for the ebook to be usable for you the reader with our needs to protect the rights of us as Publishers and of our authors. In summary, the agreement says:

  • You may make copies of your eBook for your own use onto any machine
  • You may not pass copies of the eBook on to anyone else
How can I make a purchase on your website? Chevron down icon Chevron up icon

If you want to purchase a video course, eBook or Bundle (Print+eBook) please follow below steps:

  1. Register on our website using your email address and the password.
  2. Search for the title by name or ISBN using the search option.
  3. Select the title you want to purchase.
  4. Choose the format you wish to purchase the title in; if you order the Print Book, you get a free eBook copy of the same title. 
  5. Proceed with the checkout process (payment to be made using Credit Card, Debit Cart, or PayPal)
Where can I access support around an eBook? Chevron down icon Chevron up icon
  • If you experience a problem with using or installing Adobe Reader, the contact Adobe directly.
  • To view the errata for the book, see and view the pages for the title you have.
  • To view your account details or to download a new copy of the book go to
  • To contact us directly if a problem is not resolved, use
What eBook formats do Packt support? Chevron down icon Chevron up icon

Our eBooks are currently available in a variety of formats such as PDF and ePubs. In the future, this may well change with trends and development in technology, but please note that our PDFs are not Adobe eBook Reader format, which has greater restrictions on security.

You will need to use Adobe Reader v9 or later in order to read Packt's PDF eBooks.

What are the benefits of eBooks? Chevron down icon Chevron up icon
  • You can get the information you need immediately
  • You can easily take them with you on a laptop
  • You can download them an unlimited number of times
  • You can print them out
  • They are copy-paste enabled
  • They are searchable
  • There is no password protection
  • They are lower price than print
  • They save resources and space
What is an eBook? Chevron down icon Chevron up icon

Packt eBooks are a complete electronic version of the print edition, available in PDF and ePub formats. Every piece of content down to the page numbering is the same. Because we save the costs of printing and shipping the book to you, we are able to offer eBooks at a lower cost than print editions.

When you have purchased an eBook, simply login to your account and click on the link in Your Download Area. We recommend you saving the file to your hard drive before opening it.

For optimal viewing of our eBooks, we recommend you download and install the free Adobe Reader version 9.