Skip to main content

FreeSWITCH Configuration

This section offers comprehensive instructions for configuring the Event Socket Library (ESL) in FreeSWITCH. It covers:

  • Enabling ESL: Steps to activate and set up ESL.
  • Securing ESL: Guidelines to ensure secure communication.
  • Routing Calls to Custom Applications: Configuring WebSocket integration for custom application interactions.

The configuration involves setting up ESL, adjusting the dialplan for effective call routing, and integrating with a WebSocket server to facilitate interactions with custom applications.

The mod_event_socket module is used to enable client communication via WebSocket.

This document section will detail the following:

ESL Operation Mode​

disclaimer

This information is derived from official FreeSWITCH documentation and further enhanced with insights from ChatGPT.

ESL (mod_event_socket) allows you to interact with the FreeSWITCH™ server in two primary modes:

  • Inbound mode
  • Outbound mode

Both modes enable you to control and monitor FreeSWITCH™, but they do so in different ways.

Inbound Mode​

Inbound Mode allows your application to act as a client that connects directly to FreeSWITCH™. In this mode, you write your application in any programming language and connect it to FreeSWITCH™ via a specified port. This setup enables your application to send commands to FreeSWITCH™, such as checking the status, making outbound calls, and more.

    ********************************************
    *                    |                     *
    *   FreeSWITCH™      |  mod_event_socket   *
    *                    |   127.0.0.1:8021    *
    *                    |                     *
    ********************************************
              /\                 /\
              /                   \
    ******************       ******************
    *    Client A    *       *    Client B    *
    * 127.0.0.1:9988 *       * 127.0.0.1:9999 *
    ******************       ******************
  • Client A and Client B are applications (e.g., written in Python, Perl, etc.) that connect to FreeSWITCH™ on the 127.0.0.1:8021 port.
  • Inbound Mode is particularly useful for interacting with FreeSWITCH™ to perform actions like checking the status of calls or managing call routing.

Handling Incoming Calls:​

If you want to handle incoming calls through inbound mode, you should configure the dialplan to use the uuid_park command (more details can be found in the mod_commands documentation). This ensures that the dialplan remains active and can interact with your application before it completes execution.

Outbound mode​

Outbound Mode allows FreeSWITCH™ to act as a client that connects to your external application. In this mode, you set up FreeSWITCH™ to initiate a connection to your application, which listens on a specified IP address and port. You configure this in the dialplan using the <action application="socket" data="ip:port sync full"/> syntax.

    *********************************************
    *                    |                     *
    *    FreeSWITCH™     |  Your Application   *
    *                    | 192.168.1.100:9090  *
    *                    |                     *
    *********************************************
                        /\
                        /
         *************************************
         *           Your Script             *
         *      (Answer, Playback, etc.)     *
         *************************************
  • In this setup, FreeSWITCH™ connects to Your Script/Application at 192.168.1.100:9090.
  • Outbound Mode allows FreeSWITCH™ to trigger actions or respond to events by connecting to your custom scripts or daemons. This is useful for scenarios where you want FreeSWITCH™ to call out to your application based on specific events or conditions.

IPv6 Support​

Since revision git-8c794ac on 14/03/2012, FreeSWITCH™ supports IPv6 addresses. You can use IPv6 in your configuration, e.g., <action application="socket" data="::1:8021"/> to connect to an IPv6 address.

Summary​

  • Inbound Mode: Your application connects to FreeSWITCH™ to issue commands and retrieve information.
  • Outbound Mode: FreeSWITCH™ connects to your application to trigger actions or respond to events.

Both modes offer powerful ways to integrate and control FreeSWITCH™, and choosing the right mode depends on whether you need FreeSWITCH™ to reach out to your application or vice versa.

Configuring ESL​

Edit the event_socket.conf.xml File

  1. Locate the Configuration File: The ESL configuration file is typically found at:

    /usr/local/freeswitch/conf/autoload_configs/event_socket.conf.xml

  2. Modify the File: Open event_socket.conf.xml and adjust the settings as follows:

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

    Parameters Breakdown:

    • nat-map: value="false" setting disables NAT mapping for ESL connections. NAT mapping helps handle network address translation issues, but setting it to false means that ESL will not attempt to map NAT addresses. This is suitable if your FreeSWITCH server is not behind NAT or if NAT issues are not a concern.
    • listen-ip: value="::" configures ESL to listen on all available IP addresses, including both IPv4 and IPv6 addresses. Using :: ensures that ESL can accept connections on any network interface.
    • listen-port: value="8021" specifies the port on which ESL listens for incoming connections. The default port is 8021, which is standard for FreeSWITCH’s ESL. This port must be open and accessible for external applications that need to connect via ESL.
    • password: value="ClueCon" sets the password used to authenticate connections to ESL. It’s crucial to use a strong, secure password in production environments to prevent unauthorized access.
    • apply-inbound-acl: value="loopback.auto" when enabled, it applies an inbound Access Control List (ACL) to restrict which IP addresses can connect to ESL. loopback.auto typically restricts access to local connections. Uncommenting this line and setting an appropriate value can enhance security by limiting access to specific IP addresses.
    • stop-on-bind-error: value="true" when enabled, FreeSWITCH will stop starting if it encounters a bind error (e.g., if the port is already in use). Uncommenting this can help identify issues during the startup phase by ensuring that FreeSWITCH does not run with an incorrect configuration.

  3. Restart FreeSWITCH: Apply the configuration changes by reloading FreeSWITCH configuration:

    fs_cli -x "reloadxml"

    Or restart the FreeSWITCH service:

    sudo systemctl restart freeswitch

Dialplan Configuration​

  1. Locate the Dialplan File:

    Dialplan configurations are typically found in:

    /usr/local/freeswitch/conf/dialplan/

    or

    /etc/freeswitch/dialplan/

  2. Create or Modify a Dialplan File:

    Create a new XML file (e.g., esl_dialplan.xml) or modify an existing one to route calls to your custom application. Here’s an example configuration:

    <extension name="RouteToCustomApp">
       <condition field="destination_number" expression="^1234$">
          <!-- Answer the call -->
          <action application="answer"/>

          <!-- Route the call to a WebSocket server (replace with your WebSocket URL) -->
          <action application="socket" data="ws://localhost:8080/myapp"/>

          <!-- Hangup the call -->
          <action application="hangup"/>
       </condition>
    </extension>
    • destination_number: Modify ^1234$ to match the dialed number you want to route to your custom application.
    • action application="answer": Answers the call.
    • action application="socket": Routes the call to a WebSocket server. Replace ws://localhost:8080/myapp with the URL of your WebSocket server.
    • action application="hangup": Ends the call when WS disconnects.

    Once a call reaches this dialplan, FreeSWITCH will direct all incoming calls to your WebSocket connection application, allowing you to manage call behavior and settings fully.

  3. Reload Dialplan:

    After making changes to the dialplan, reload it:

    fs_cli -x "reload dialplan"