FREESWITCH_SCRIPTING module
Admin Guide
Section titled “Admin Guide”Overview
Section titled “Overview”freeswitch_scripting is a helper module that exposes full control over the FreeSWITCH ESL interface to the OpenSIPS script.
It allows the OpenSIPS script writer to subscribe to generic FreeSWITCH ESL events as well as to run arbitrary FreeSWITCH ESL commands and interpret their results. It makes use of the freeswitch module for the management of ESL connections and event subscriptions.
Credits for the initial idea and working code samples providing both ESL events and commands go to Giovanni Maruzzelli gmaruzz@opentelecom.it.
Dependencies
Section titled “Dependencies”OpenSIPS Modules
Section titled “OpenSIPS Modules”The following modules must be loaded together with this module:
- freeswitch
- (optional) an SQL DB module
External Libraries or Applications
Section titled “External Libraries or Applications”The following libraries or applications must be installed before running OpenSIPS with this module loaded:
- None
Exported Parameters
Section titled “Exported Parameters”db_url (string)
Section titled “db_url (string)”An SQL database URL which the module will use in order to load a set of FreeSWITCH ESL sockets and their event subscriptions.
Default value is “NULL” (DB support disabled).
...modparam("freeswitch_scripting", "db_url", "dbdriver://username:password@dbhost/dbname")...db_table (string)
Section titled “db_table (string)”The SQL table name for this module.
Default value is “freeswitch”.
...modparam("freeswitch_scripting", "db_table", "freeswitch_sockets")...db_col_username (string)
Section titled “db_col_username (string)”The SQL column name for the “username” ESL connect information.
Default value is “username”.
...modparam("freeswitch_scripting", "db_col_username", "user")...db_col_password (string)
Section titled “db_col_password (string)”The SQL column name for the “password” ESL connect information.
Default value is “password”.
...modparam("freeswitch_scripting", "db_col_password", "pass")...db_col_ip (string)
Section titled “db_col_ip (string)”The SQL column name for the “ip” ESL connect information.
Default value is “ip”.
...modparam("freeswitch_scripting", "db_col_ip", "ip_addr")...db_col_port (string)
Section titled “db_col_port (string)”The SQL column name for the “port” ESL connect information.
Default value is “port”.
...modparam("freeswitch_scripting", "db_col_port", "tcp_port")...db_col_events (string)
Section titled “db_col_events (string)”The SQL column name for the comma-separated, case-sensitive FreeSWITCH event names which OpenSIPS will subscribe to.
Default value is “events_csv”.
...modparam("freeswitch_scripting", "db_col_events", "fs_events")...fs_subscribe (string)
Section titled “fs_subscribe (string)”Add a FreeSWITCH ESL URL to which OpenSIPS will connect at startup. The URL syntax includes support for specifying a list of events to subscribe to and follows this pattern: [fs://][[username]:password@]host[:port][?event1[,event2]…]
This parameter can be set multiple times.
...modparam("freeswitch_scripting", "fs_subscribe", ":ClueCon@10.0.0.10?CHANNEL_STATE")modparam("freeswitch_scripting", "fs_subscribe", ":ClueCon@10.0.0.11:8021?DTMF,BACKGROUND_JOB")...Exported Functions
Section titled “Exported Functions”freeswitch_esl(command, freeswitch_url[, response_var])
Section titled “freeswitch_esl(command, freeswitch_url[, response_var])”Run an arbitrary command on an arbitrary FreeSWITCH ESL socket. The socket need not necessarily be defined in the database or through fs subscribe. However, if this is the case, then the “password” part of the URL becomes mandatory.
The current OpenSIPS worker will block until an answer from FreeSWITCH arrives. The timeout for this operation can be controlled via the esl_cmd_timeout parameter of the freeswitch connection manager module.
Meaning of the parameters is as follows:
- command (string) - the ESL command string to execute.
- freeswitch_url (string) - the ESL interface to connect to. The syntax is: [fs://][[username]:password@]host[:port][?event1[,event2]…]. The “?events” part of the URL will be silently discarded.
- response_var (var, optional) - a variable which will hold the text result of the ESL command.
Return value
- 1 (success) - the ESL command executed successfully and any output variables were successfully written to. Note that this does not say anything about the nature of the ESL answer (it may well be a “-ERR” type of response)
- -1 (failure) - internal error or the ESL command failed to execute
This function can be used from any route.
... # ESL socket 10.0.0.10 is defined in the database (password "ClueCon") $var(rc) = freeswitch_esl("bgapi originate {origination_uuid=123456789}user/1010 9386\njob-uuid: foobar", "10.0.0.10", "$var(response)"); if ($var(rc) < 0) { xlog("failed to execute ESL command ($var(rc))\n"); return -1; }... # ESL socket 10.0.0.10 is new, we must specify a password $var(rc) = freeswitch_esl("bgapi originate {origination_uuid=123456789}user/1010 9386\njob-uuid: foobar", ":ClueCon@10.0.0.10", $var(response)); if ($var(rc) < 0) { xlog("failed to execute ESL command ($var(rc))\n"); return -1; }...Exported MI Commands
Section titled “Exported MI Commands”fs_subscribe
Section titled “fs_subscribe”Ensures that the given FreeSWITCH ESL socket is subscribed to the given list of events. In case an event cannot be subscribed to, the freeswitch driver will periodically retry to subscribe to it until an fs_unsubscribe MI command for the respective event is issued.
Parameters:
- freeswitch_url - the ESL interface to connect to. The syntax is: [fs://][[username]:password@]host[:port][?event1[,event2]…]. The “?events” part of the URL will be silently discarded.
- event - the name of the event to subscribe to
- … - (other events)
fs_unsubscribe
Section titled “fs_unsubscribe”Ensures that the given FreeSWITCH ESL socket is unsubscribed from the given list of events.
Parameters:
- freeswitch_url - the ESL interface to search for. The syntax is: [fs://][[username]:password@]host[:port][?event1[,event2]…]. The “?events” part of the URL will be silently discarded.
- event - the name of the event to unsubscribe from
- … - (other events)
fs_list
Section titled “fs_list”Displays the current set of FreeSWITCH ESL sockets and the list of events that the module is subscribed to for each socket.
fs_reload
Section titled “fs_reload”Replaces the current set* of FreeSWITCH ESL sockets along with their respective events with the current data (ESL sockets and their events) found in the “freeswitch” table.
- this includes any sockets/events provisioned through fs subscribe, MI mi fs subscribe commands or previous DB data set.
Exported Events
Section titled “Exported Events”E_FREESWITCH
Section titled “E_FREESWITCH”This event is raised when OpenSIPS receives an ESL event notification from a socket that the “freeswitch_scripting” module is subscribed to.
Parameters:
- name - the name of the event
- sender - the FreeSWITCH sender IP address
- body - the full JSON-encoded body of the event, as sent by FreeSWITCH. Use the json module ($json variable) to easily interpret it.
Contributors
Section titled “Contributors”By Commit Statistics
Section titled “By Commit Statistics”Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
| # | Name | DevScore | Commits | Lines++ | Lines— |
|---|---|---|---|---|---|
| 1. | Liviu Chircu (@liviuchircu) | 49 | 27 | 1946 | 288 |
| 2. | Stefan Darius (@dariusstefan) | 9 | 4 | 395 | 58 |
| 3. | Vlad Patrascu (@rvlad-patrascu) | 8 | 3 | 137 | 124 |
| 4. | Razvan Crainea (@razvancrainea) | 6 | 4 | 4 | 2 |
| 5. | Bogdan-Andrei Iancu (@bogdan-iancu) | 4 | 2 | 4 | 2 |
| 6. | Maksym Sobolyev (@sobomax) | 3 | 1 | 4 | 4 |
| 7. | Peter Lemenkov (@lemenkov) | 3 | 1 | 1 | 1 |
(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding merge commits
(3) ignoring whitespace edits, renamed files and auto-generated files
By Commit Activity
Section titled “By Commit Activity”| # | Name | Commit Activity |
|---|---|---|
| 1. | Stefan Darius (@dariusstefan) | Jun 2026 - Jul 2026 |
| 2. | Razvan Crainea (@razvancrainea) | May 2019 - Jun 2026 |
| 3. | Liviu Chircu (@liviuchircu) | Dec 2017 - Feb 2024 |
| 4. | Maksym Sobolyev (@sobomax) | Feb 2023 - Feb 2023 |
| 5. | Bogdan-Andrei Iancu (@bogdan-iancu) | Apr 2019 - Mar 2020 |
| 6. | Vlad Patrascu (@rvlad-patrascu) | Jan 2019 - Apr 2019 |
| 7. | Peter Lemenkov (@lemenkov) | Jun 2018 - Jun 2018 |
(1) including any documentation-related commits, excluding merge commits
Documentation
Section titled “Documentation”Contributors
Section titled “Contributors”Last edited by: Razvan Crainea (@razvancrainea), Liviu Chircu (@liviuchircu), Vlad Patrascu (@rvlad-patrascu), Peter Lemenkov (@lemenkov).
License
Section titled “License”All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0