FreeSWITCH Application Modules: Dialplan Tools and Features

Application modules extend the FreeSWITCH dialplan with actions that can be performed on a call. When a call matches an extension in the XML dialplan, the <action> elements that follow invoke application modules — answering the call, playing audio, bridging to another party, placing the caller in a conference room, routing to voicemail, and much more. Almost everything that happens to a call after it is matched by the dialplan is the responsibility of one application module or another.

Core Dialplan Tools (mod_dptools)

mod_dptools (“dialplan tools”) is the most important application module in FreeSWITCH. It registers the fundamental set of dialplan applications that nearly every deployment relies upon. The module is defined in src/mod/applications/mod_dptools/mod_dptools.c and loads dozens of individual applications.

Essential Applications

Application	Purpose
`answer`	Answer an inbound call (sends 200 OK / off-hook)
`pre_answer`	Send a 183 Session Progress (early media) before answering
`hangup`	Terminate the call with a specified hangup cause
`bridge`	Connect the current leg to one or more outbound destinations
`transfer`	Move the call to a new dialplan extension
`set`	Set a channel variable on the current leg
`export`	Set a channel variable that is inherited by the B-leg
`playback`	Stream an audio file or tone to the caller
`record`	Record the call audio to a file
`play_and_get_digits`	Play a prompt and collect DTMF input
`say`	Speak text using a language module (numbers, dates, etc.)
`sleep`	Pause dialplan execution for a specified number of milliseconds
`hold`	Place the call on hold
`park`	Park the call until it is retrieved
`wait_for_silence`	Wait until the audio stream falls below a silence threshold
`log`	Write a message to the FreeSWITCH log
`info`	Dump all channel variables to the log (debugging)
`deflect`	Send a SIP 302 redirect to the caller
`intercept`	Intercept a ringing or parked call by UUID

Dialplan XML Examples

Answer and play an audio file:

<extension name="welcome">
  <condition field="destination_number" expression="^5000$">
    <action application="answer"/>
    <action application="playback" data="ivr/ivr-welcome_to_freeswitch.wav"/>
    <action application="hangup"/>
  </condition>
</extension>

Bridge to a SIP endpoint:

<extension name="local_extension">
  <condition field="destination_number" expression="^(10[01][0-9])$">
    <action application="set" data="dialed_extension=$1"/>
    <action application="bridge" data="user/${dialed_extension}@${domain_name}"/>
    <!-- Fall through to voicemail if bridge fails -->
    <action application="answer"/>
    <action application="bridge"
      data="loopback/app=voicemail:default ${domain_name} ${dialed_extension}"/>
  </condition>
</extension>

Collect digits and transfer:

<extension name="auto_attendant">
  <condition field="destination_number" expression="^9000$">
    <action application="answer"/>
    <action application="play_and_get_digits"
      data="1 1 3 5000 # ivr/ivr-please_enter_ext.wav
            ivr/ivr-that_was_an_invalid_entry.wav
            destination_number \d+"/>
    <action application="transfer" data="${destination_number} XML default"/>
  </condition>
</extension>

Set channel variables:

<extension name="set_vars_example">
  <condition field="destination_number" expression="^1234$">
    <!-- set only affects this leg -->
    <action application="set" data="effective_caller_id_name=Support Line"/>
    <!-- export copies the variable to the B-leg as well -->
    <action application="export" data="sip_h_X-Custom-Header=myvalue"/>
    <action application="bridge" data="sofia/internal/1001@${domain_name}"/>
  </condition>
</extension>

Conference (mod_conference)

mod_conference provides full-featured multi-party audio and video conferencing. Each conference room is identified by a name and a profile. Multiple callers can join the same room and talk simultaneously. The source is split across several focused files: conference_member.c, conference_loop.c, conference_api.c, conference_event.c, conference_record.c, and conference_video.c.

Conference Profiles

Profiles define the audio quality and behavior of a conference room. The default vanilla configuration defines several profiles by sample rate:

<!-- conf/autoload_configs/conference.conf.xml (excerpt) -->
<profile name="default">
  <param name="rate" value="8000"/>
  <param name="interval" value="20"/>
  <param name="energy-level" value="100"/>
  <param name="muted-sound" value="conference/conf-muted.wav"/>
  <param name="unmuted-sound" value="conference/conf-unmuted.wav"/>
  <param name="enter-sound" value="tone_stream://%(200,0,500,600,700)"/>
  <param name="exit-sound" value="tone_stream://%(500,0,300,200,100,50,25)"/>
  <param name="alone-sound" value="conference/conf-alone.wav"/>
  <param name="moh-sound" value="$${hold_music}"/>
  <param name="comfort-noise" value="true"/>
</profile>

<profile name="wideband">
  <param name="rate" value="16000"/>
  <param name="interval" value="20"/>
  <!-- ... -->
</profile>

Joining a Conference from the Dialplan

The conference application takes the form <room_name>@<profile_name>. Optional flags can be appended with +flags{...}:

<!-- Standard narrowband conference room -->
<extension name="conference_3000">
  <condition field="destination_number" expression="^(3\d{3})$">
    <action application="answer"/>
    <action application="conference" data="$1-${domain_name}@default"/>
  </condition>
</extension>

<!-- Wideband conference -->
<extension name="conference_wideband">
  <condition field="destination_number" expression="^(35\d{2})$">
    <action application="answer"/>
    <action application="conference" data="$1-${domain_name}@wideband"/>
  </condition>
</extension>

<!-- Moderator enters in deaf mode (listen only for an intercom use case) -->
<extension name="intercom_announce">
  <condition field="destination_number" expression="^9001$">
    <action application="answer"/>
    <action application="conference"
      data="announce_room@default+flags{endconf|deaf}"/>
  </condition>
</extension>

Caller Controls

Callers in a conference can press DTMF digits to control their experience. The default key bindings are:

Key	Action
`0`	Toggle mute
`*`	Toggle deaf-mute
`9`	Energy level up
`8`	Energy level reset to zero
`7`	Energy level down
`3`	Talk volume up
`2`	Talk volume reset to zero
`1`	Talk volume down
`6`	Listen volume up
`5`	Listen volume reset to zero
`4`	Listen volume down
`#`	Hang up and leave

Conference API

Conference rooms can be managed at runtime via mod_conference’s API commands:

# List all active conferences
conference list

# Kick member 2 from the room "3001-example.com"
conference 3001-example.com kick 2

# Record a conference to a file
conference 3001-example.com record /tmp/conference.wav

# Play a file to the entire conference
conference 3001-example.com play /sounds/announce.wav

Voicemail (mod_voicemail)

mod_voicemail is a full voicemail system built into FreeSWITCH. Callers can leave messages, and users can retrieve, save, delete, and forward messages via a DTMF-driven menu. Optional email-to-voicemail notification forwards new messages as audio attachments.

Configuration

mod_voicemail is configured via conf/autoload_configs/voicemail.conf.xml. Key parameters in the default profile include:

<profile name="default">
  <param name="file-extension" value="wav"/>
  <param name="terminator-key" value="#"/>
  <param name="max-login-attempts" value="3"/>
  <param name="min-record-len" value="3"/>
  <param name="max-record-len" value="300"/>
  <param name="digit-timeout" value="10000"/>
  <!-- Playback keys -->
  <param name="play-new-messages-key" value="1"/>
  <param name="play-saved-messages-key" value="2"/>
  <!-- Navigation keys -->
  <param name="previous-message-key" value="1"/>
  <param name="next-message-key" value="3"/>
  <param name="delete-file-key" value="7"/>
  <param name="email-key" value="4"/>
  <!-- Operator / main menu routing -->
  <param name="operator-extension" value="operator XML default"/>
  <param name="vmain-extension" value="vmain XML default"/>
</profile>

Leaving a Voicemail Message

Route unanswered calls to voicemail by transferring to the voicemail application:

<extension name="local_extension">
  <condition field="destination_number" expression="^(10[01][0-9])$">
    <action application="bridge" data="user/$1@${domain_name}"/>
    <!-- bridge failed or no answer — go to voicemail -->
    <action application="answer"/>
    <action application="voicemail" data="default ${domain_name} $1"/>
  </condition>
</extension>

Checking Voicemail

Route authenticated users to the voicemail retrieval interface:

<extension name="check_voicemail">
  <condition field="destination_number" expression="^(vmain|4000)$">
    <action application="answer"/>
    <action application="voicemail" data="check default ${domain_name}"/>
  </condition>
</extension>

Email Notification

Email notification is configured in the <email> block of the voicemail profile. FreeSWITCH can send an email with the audio file attached when a new message arrives:

<email>
  <param name="email-from" value="${voicemail_account}@${voicemail_domain}"/>
  <param name="email-headers"
    value="X-Mailer: FreeSWITCH&#13;&#10;X-Priority: 2 (High)"/>
  <param name="email-body"
    value="You have a new voicemail from ${caller_id_name}.&#13;&#10;"/>
  <param name="email-audio-file" value="attach"/>
  <param name="notify-template" value="voicemail.notify.tpl"/>
</email>

IVR (ivr application in mod_dptools)

FreeSWITCH includes a declarative XML-based IVR (Interactive Voice Response) engine. The ivr dialplan application is registered by mod_dptools (in src/mod/applications/mod_dptools/) and uses menu definitions from conf/ivr_menus/. Each menu specifies greetings, digit bindings, and exit actions. The ivr application handles the entire play-collect-route loop without requiring any scripting.

<!-- conf/ivr_menus/demo_ivr.xml -->
<menu name="demo_ivr"
    greet-long="phrase:demo_ivr_main_menu"
    greet-short="phrase:demo_ivr_main_menu_short"
    invalid-sound="ivr/ivr-that_was_an_invalid_entry.wav"
    exit-sound="voicemail/vm-goodbye.wav"
    timeout="10000"
    inter-digit-timeout="2000"
    max-failures="3"
    max-timeouts="3"
    digit-len="4">

  <!-- Digit 1: join FreeSWITCH public conference -->
  <entry action="menu-exec-app" digits="1"
    param="bridge sofia/$${domain}/888@conference.freeswitch.org"/>

  <!-- Digit 2: transfer to echo test -->
  <entry action="menu-exec-app" digits="2"
    param="transfer 9196 XML default"/>

  <!-- Digit 6: enter a sub-menu -->
  <entry action="menu-sub" digits="6" param="demo_ivr_submenu"/>

  <!-- Regex: match any 4-digit extension in 10xx range -->
  <entry action="menu-exec-app" digits="/^(10[01][0-9])$/"
    param="transfer $1 XML features"/>

  <!-- Digit 9: repeat the menu -->
  <entry action="menu-top" digits="9"/>
</menu>

Entering the IVR from the Dialplan

<extension name="ivr_demo">
  <condition field="destination_number" expression="^5000$">
    <action application="answer"/>
    <action application="ivr" data="demo_ivr"/>
  </condition>
</extension>

Action	Behavior
`menu-exec-app`	Execute a FreeSWITCH application with `param` as arguments
`menu-sub`	Enter a named sub-menu
`menu-top`	Return to the top of the current menu
`menu-exit`	Exit the IVR menu
`menu-play-sound`	Play a sound file without leaving the menu

Call Center (mod_callcenter)

mod_callcenter provides queue-based automatic call distribution (ACD). Inbound calls are placed in a named queue and distributed to available agents using configurable strategies (round-robin, longest-idle, top-down). Agents can log in and out of queues dynamically.

Dialplan: Place a Call in a Queue

<extension name="support_queue">
  <condition field="destination_number" expression="^(8000)$">
    <action application="answer"/>
    <action application="callcenter" data="support@default"/>
  </condition>
</extension>

Agent Management via API

# Add an agent
callcenter_config agent add 1001@example.com callback

# Set agent availability
callcenter_config agent set status 1001@example.com Available

# Log an agent into a queue tier
callcenter_config tier add support@default 1001@example.com 1 1

# Show queue statistics
callcenter_config queue list

Other Notable Modules

mod_commands

Registers the core FreeSWITCH API commands (status, version, reloadxml, uuid_kill, etc.) used from the CLI and ESL.

mod_fifo

A lightweight FIFO queue for basic call parking and retrieval without the overhead of a full ACD system.

mod_hash

In-memory key-value store shared across all channels. Useful for inter-call data sharing like call parking slots and ring groups.

mod_curl

Makes HTTP GET/POST requests from the dialplan using curl and curl_getresponsecode applications. Ideal for simple webhook callbacks.

mod_httapi

Implements the HTTAPI (HTTP API) protocol — FreeSWITCH fetches an XML document from a remote URL at each dialplan step, enabling fully HTTP-driven IVR logic.

mod_signalwire

Connects FreeSWITCH to the SignalWire cloud platform, enabling SIP trunking, phone number management, and cloud features through the SignalWire API.

Getting Started

Core Concepts

Configuration

Modules

Event Socket Layer

Operations

FreeSWITCH Application Modules: Dialplan Tools and Features

Core Dialplan Tools (mod_dptools)

Essential Applications

Dialplan XML Examples

Conference (mod_conference)

Conference Profiles

Joining a Conference from the Dialplan

Caller Controls

Conference API

Voicemail (mod_voicemail)

Configuration

Leaving a Voicemail Message

Checking Voicemail

Email Notification

IVR (ivr application in mod_dptools)

Defining an IVR Menu

Entering the IVR from the Dialplan

Menu Entry Actions

Call Center (mod_callcenter)

Dialplan: Place a Call in a Queue

Agent Management via API

Other Notable Modules

mod_commands

mod_fifo

mod_hash

mod_curl

mod_httapi

mod_signalwire

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Configuration

Modules

Event Socket Layer

Operations

Documentation Index

​Core Dialplan Tools (mod_dptools)

​Essential Applications

​Dialplan XML Examples

​Conference (mod_conference)

​Conference Profiles

​Joining a Conference from the Dialplan

​Caller Controls

​Conference API

​Voicemail (mod_voicemail)

​Configuration

​Leaving a Voicemail Message

​Checking Voicemail

​Email Notification

​IVR (ivr application in mod_dptools)

​Defining an IVR Menu

​Entering the IVR from the Dialplan

​Menu Entry Actions

​Call Center (mod_callcenter)

​Dialplan: Place a Call in a Queue

​Agent Management via API

​Other Notable Modules

mod_commands

mod_fifo

mod_hash

mod_curl

mod_httapi

mod_signalwire

Build docs developers (and LLMs) love

Core Dialplan Tools (mod_dptools)

Essential Applications

Dialplan XML Examples

Conference (mod_conference)

Conference Profiles

Joining a Conference from the Dialplan

Caller Controls

Conference API

Voicemail (mod_voicemail)

Configuration

Leaving a Voicemail Message

Checking Voicemail

Email Notification

IVR (ivr application in mod_dptools)

Defining an IVR Menu

Entering the IVR from the Dialplan

Menu Entry Actions

Call Center (mod_callcenter)

Dialplan: Place a Call in a Queue

Agent Management via API

Other Notable Modules