Skip to content

Freeswitch Binding

dougmeredith edited this page Jan 29, 2015 · 4 revisions


This is a Freeswitch binding for OpenHab.

It connects to a freeswitch instance and can report on current active calls as well as show unread voicemails and if a MWI is on.

You can also send any command to freeswitch , see Freeswitch Commands for more info.


Copy the binding (org.openhab.binding.freeswitch*.jar) to your addons directory.

Make sure you have the freeswitch ESL module listening on a public port, your event_socket.conf.xml in freeswitch should look something like:

<configuration name="event_socket.conf" description="Socket Client">
    <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="lan"/>-->

In your openhab.cfg put the following entry with your freeswitch ESL config,

########################## Freeswitch Action configuration #################################


this is a sample item entry for non filtered calls, any inbound call will be considered active, this is sufficient for most uses.

Switch Incoming_Call "Home Phone" (Phone) {freeswitch="active"}
Call Active_Call     "Connected [to %1$s from %2$s]" (Phone) {freeswitch="active"}
String Active_Call_ID "Caller ID [%s]" (Phone) {freeswitch="active"}

This item is for a filtered call, only calls with an inbound direction and a destination number of 5555551212 will be matched

Switch Incoming_Call "Home Phone" (Phone) {freeswitch="active:Call-Direction:inbound,Caller-Destination-Number:5555551212"}
Call Active_Call     "Connected [to %1$s from %2$s]" (Phone)  {freeswitch="active:Call-Direction:inbound,Caller-Destination-Number:5555551212"}
String Active_Call_ID "Caller ID [%s]" (Phone)  {freeswitch="active:Call-Direction:inbound,Caller-Destination-Number:5555551212"}

For messages and message waiting indicator (MWI) the voice mail account is specified

Number Voice_Messages "Unread Messages [%d]" (Phone) {freeswitch=""}

To send api commands to Freeswitch add a simple api item

String FS_API "FS API [%s]" (phone) {freeswitch="api"}

There are three supported protocol types, "active", "message_waiting" and "api"

  • Active types:
    • Filtered
      • calls can be filtered on freeswitch event headers, multiple headers can be used, all must match.
      • filters format is "Key:Value,Key:Value,...."
      • Ex: Switch Incoming_Call "Home Phone" (Phone) {freeswitch="active:Call-Direction:inbound,Caller-Destination-Number:5555551212"}
      • see Freesiwtch Events for more info on event headers
    • Non Filtered
      • if no filter is given any inbound call will be used
      • for multiple active calls the most recent active call's callerid will be displayed Ex: Incoming_Call "Home Phone" (Phone) {freeswitch="active}
    • Item Types
      • Switch will be on for an active call, off if no active calls
      • Call, this shows the destination and origination numbers
      • Text, this shows the Caller-ID fields (name : number) if sent by caller (regional specific I would imagine)
  • Message_Waiting types:
    • Number, this shows the number of unread voice mails
    • Switch, on if MWI (message indicator) is yes.
  • API types
    • String , sending a string to this will send a command to FS, the result will be sent back to this item as a comma seperated list
    • API types are really meant to be used in rules, an example might be:
      • sendCommand(FS_API,"conference test-conf dial sofia/gateway/myvoipprovider/5555551212 5551212 5551212")
      • This would tell freeswitch to dial 5555551212 into a conference named "test-conf"
      • the conference info would be returned as a update to the item.
    • see Freeswitch Commands for more info.

message_waiting takes an extra argument which is the mailbox we want to check against. This is usually the extention@domain

feature overview


Setup intro

Linux and OS X





User Interfaces



(link to openHAB forum)



Application Integration



A good source of inspiration and tips from users gathered over the years. Be aware that things may have changed since they were written and some examples might not work correctly.

Please update the wiki if you do come across any out of date information.

Binding configurations

Use case examples

Item definition examples

Sitemap definition examples

Collections of Rules on a single page

Single Rules


Syntax highlighting for external editors

Release Notes

Clone this wiki locally
You can’t perform that action at this time.