Call Us Today! 877.742.2583




Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Code Block
languagexml
themeEmacs
title./freeswitch/conf/autoload_configs/xml_curl.conf.xml
 
<configuration name="xml_curl.conf" description="cURL XML Gateway">
  <bindings> 
    <!-- Ask example1.com for a dialplan config, if we get a valid response then don't continue onto example2.com. However if we don't get a valid response, then continue onto example2.com --> 
    <binding name="dialplan">
      <param name="gateway-url" value="http://example1.com:80/fsapi" bindings="dialplan"/> 
    </binding>

    <!-- This will only get called if example1.com returns an invalid or not found response. If this gateway also fails to return a valid configuration, then FreeSWITCH will look for the static configuration file on disk -->
    <binding name="dialplan backup"> 
      <param name="gateway-url" value="http://example2.com:80/fsapi" bindings="dialplan"/>
    </binding> 
 
    <!-- Ask example1.com for a directory config, if not found then revert to disk --> 
    <binding name="directory"> 
      <param name="gateway-url" value="http://example1:80/fsapi" bindings="directory"/> 
    </binding> 
 
    <!-- Ask example1.com for a configuration config, if not found then revert to disk --> 
    <binding name="configuration"> 
      <param name="gateway-url" value="http://example1:80/fsapi" bindings="configuration"/> 
    </binding> 
 
    <!-- Ask example1.com for a phrases config, if not found then revert to disk --> 
    <binding name="phrases">
      <param name="gateway-url" value="http://example1:80/fsapi" bindings="phrases"/> 
    </binding> 
  </bindings> 
</configuration>
 

 


If you wanted to keep things compact/tidy, you can also use the following approach:

Code Block
languagexml
themeEmacs
title./freeswitch/conf/autoload_configs/xml_curl.conf.xml
<configuration name="xml_curl.conf" description="cURL XML Gateway">
  <bindings>
    <!-- Attempt to load dialplan/configuration/directory/phrases config from
         this gateway. If invalid or not found, then continue onto the next gateway -->
    <binding name="all configs">
      <param name="gateway-url" value="http://example1.com:80/fsapi" bindings="dialplan|configuration|directory|phrases"/>
    </binding>

    <!-- Attempt to load dialplan/configuration/directory/phrases only if example1.com
         sends back an invalid or not found response. If this also returns an invalid or
         not found then revert to disk
     -->
    <binding name="all configs backup">
      <param name="gateway-url" value="http://example2.com:80/fsapi" bindings="dialplan|configuration|directory|phrases"/>
    </binding>
  </bindings>
</configuration>

 


You may also provide some extra parameters, such as authentication scheme and login credentials. Here is an example;

...

Having said all of this, we can distill the information down to the simple caveat that, while it is safe and good to reference static variables in your dynamic configuration, it is probably not safe to try to overwrite them. Treat them with the respect you'd treat any global variable and you should be fine.

 


API Request Fields

This gives an explanation of what individual request fields means.

...

Code Block
collapsetrue
variable_sip_via_rport :::: 2048
variable_sip_from_uri :::: 800@192.168.0.9
variable_user_context :::: default
Caller-Network-Addr :::: 192.168.0.19
variable_mailbox :::: 800
variable_sip_contact_port :::: 2048
Caller-Screen-Bit :::: yes
variable_sip_via_port :::: 2048
Caller-Caller-ID-Name :::: Work
Call-Direction :::: inbound
variable_accountcode :::: 800
variable_sip_to_uri :::: 9999@192.168.0.9
variable_user_name :::: 800
variable_sip_auth_username :::: 800
variable_sip_mailbox :::: 800
variable_sip_req_host :::: 192.168.0.9
variable_sip_to_params :::: user=phone
variable_sofia_profile_name :::: internal
variable_effective_caller_id_number :::: 800
variable_sip_authorized :::: true
Channel-State-Number :::: 2
variable_sip_contact_uri :::: 800@192.168.0.19:2048
variable_domain_name :::: 192.168.0.9
key_name :::: 
Caller-Dialplan :::: XML
variable_presence_id :::: 800@192.168.0.9
variable_sip_contact_params :::: line=05edf9r6
variable_record_stereo :::: true
Unique-ID :::: 388b125c-58ff-11dd-9892-8f5d58364073
Caller-Caller-ID-Number :::: 800
Caller-Source :::: mod_sofia
Caller-Channel-Name :::: sofia/internal/800@192.168.0.9
variable_sip_via_host :::: 192.168.0.19
variable_sip_auth_realm :::: 192.168.0.9
variable_sip_h_P-Key-Flags :::: resolution="31x13", keys="4"
Caller-Username :::: 800
variable_channel_name :::: sofia/internal/800@192.168.0.9
Caller-Privacy-Hide-Number :::: no
variable_sip_from_host :::: 192.168.0.9
Channel-Write-Codec-Rate :::: 8000
variable_sip_to_user :::: 9999
variable_remote_media_port :::: 59788
Channel-Write-Codec-Name :::: PCMU
variable_sip_received_port :::: 2048
variable_sip_req_user :::: 9999
Channel-Name :::: sofia/internal/800@192.168.0.9
Caller-Destination-Number :::: 9999
variable_sip_crypto_mandatory :::: true
Channel-Read-Codec-Rate :::: 8000
Caller-Unique-ID :::: 388b125c-58ff-11dd-9892-8f5d58364073
variable_sip_user_agent :::: snom360/7.1.33
Caller-Profile-Index :::: 1
Channel-State :::: CS_ROUTING
variable_sip_from_user_stripped :::: 800
variable_sip_to_host :::: 192.168.0.9
section :::: dialplan
hostname :::: frog
Channel-Read-Codec-Name :::: PCMU
variable_sip_call_id :::: 3c2a39c538e1-f6k7b52a7dnm
variable_write_rate :::: 8000
variable_sip_contact_user :::: 800
variable_sofia_profile_domain_name :::: 192.168.0.9
Caller-Channel-Answered-Time :::: 0
variable_sip_secure_media :::: true
Answer-State :::: ringing
Caller-Privacy-Hide-Name :::: no
key_value :::: 
variable_remote_media_ip :::: 192.168.0.19
Caller-Channel-Hangup-Time :::: 0
variable_write_codec :::: PCMU
Caller-Context :::: default
variable_max_forwards :::: 70
variable_read_codec :::: PCMU
variable_sip_has_crypto :::: AES_CM_128_HMAC_SHA1_32
variable_read_rate :::: 8000
variable_sip_received_ip :::: 192.168.0.19
Caller-Channel-Transfer-Time :::: 0
variable_sip_req_params :::: user=phone
variable_sip_req_uri :::: 9999@192.168.0.9
variable_sip_from_user :::: 800
Caller-Channel-Created-Time :::: 1216848907951512
variable_endpoint_disposition :::: RECEIVED
variable_switch_r_sdp :::: v=0
o=root 1097507980 1097507980 IN IP4 192.168.0.19
s=call
c=IN IP4 192.168.0.19
t=0 0
m=audio 59788 RTP/SAVP 0 8 9 2 3 18 4 101
a=rtpmap:0 pcmu/8000
a=rtpmap:8 pcma/8000
a=rtpmap:9 g722/8000
a=rtpmap:2 g726-32/8000
a=rtpmap:3 gsm/8000
a=rtpmap:18 g729/8000
a=rtpmap:4 g723/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-16
a=crypto:1 AES_CM_128_HMAC_SHA1_32 inline:tcj5d1Iw3KFcIIKiwWRtlz7uI7JUwLWbcT9u6FDx
a=ptime:20
m=audio 59788 RTP/AVP 0 8 9 2 3 18 4 101
a=rtpmap:0 pcmu/8000
a=rtpmap:8 pcma/8000
a=rtpmap:9 g722/8000
a=rtpmap:2 g726-32/8000
a=rtpmap:3 gsm/8000
a=rtpmap:18 g729/8000
a=rtpmap:4 g723/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-16
a=ptime:20

tag_name :::: 
variable_sip_contact_host :::: 192.168.0.19
variable_sip_nat_detected :::: true
variable_sip_from_tag :::: zah0wfkmg9
variable_effective_caller_id_name :::: hads

 


XML Usage

Section: dialplan

...

Code Block
section=dialplan&tag_name=&key_name=&key_value=&context=default&destination_number=556
&caller_id_name=FreeSwitch&caller_id_number=5555551212&network_addr=&ani=&aniii=&rdnis=
&source=mod_portaudio&chan_name=PortAudio/556&uuid=b7f0b117-351f-9448-b60a-18ff91cbe183
&endpoint_disposition=ANSWER

 


RESPONSE:

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<document type="freeswitch/xml">
  <section name="dialplan" description="RE Dial Plan For FreeSwitch">
    <context name="default">
      <extension name="test9">
        <condition field="destination_number" expression="^83789$">
          <action application="bridge" data="iax/guest@conference.freeswitch.org/888"/>
        </condition>
      </extension>
    </context>
  </section>
</document>

 


Section: configuration

This is used to send back configuration files such as sofia.conf.

...

Code Block
key_value=sofia.conf&key_name=name&section=configuration&tag_name=configuration

 


The response should look identical to what the file would have looked like on disk, with the exception that you need to wrap it in a <document>, as shown in the following example;

Code Block
languagexml
<document type="freeswitch/xml">
  <section name="configuration">

    <!--The content of the tag SECTION is identical to what you find in the default config files.-->

    <configuration name="SECTIONNAME.conf" description="SECTIONDESCRIPTION">
      <settings>
         <!--ADD your parameters here-->
      </settings>
    </configuration>

  </section>
</document>

 


Section: directory

You must ensure that the "accept-blind-reg" parameter is set to "false" in sofia.conf.xml, otherwise your web application will not get called.

...

Code Block
languagexml
<document type="freeswitch/xml">
  <section name="directory">
    <domain name="domain1.awesomevoipdomain.faketld">
      <params>
        <param name="dial-string" value="{presence_id=${dialed_user}@${dialed_domain}}${sofia_contact(${dialed_user}@${dialed_domain})}"/>
      </params>
      <groups>
        <group name="default">
         <users>
          <user id="1004">
            <params>
              <param name="password" value="some_password"/>
            </params>
          </user>
         </users>
        </group>
      </groups>
    </domain>
  </section>
</document>

 


If you don't want to communicate passwords in plain text over your network, you can use the `a1-hash` param instead. Its value should be an md5sum containing `user:domain:password`.

...

<param name="a1-hash" value="50046ba744759aa83e045ba0b996e7a9"/>

 


Example: purpose=gateways

...

Code Block
languagexml
<document type="freeswitch/xml">
  <section name="directory">	
    <domain name="domain1.awesomevoipdomain.faketld">
      <params>
        <param name="dial-string" value="{presence_id=${dialed_user}@${dialed_domain}}${sofia_contact(${dialed_user}@${dialed_domain})}"/>
      </params>
      <variables>
        <variable name="example_var" value="example_value_1"/>
      </variables>
      <user id="default" />
    </domain>
    <domain name="domain2.awesomevoipdomain.faketld">
      <params>
        <param name="dial-string" value="{presence_id=${dialed_user}@${dialed_domain}}${sofia_contact(${dialed_user}@${dialed_domain})}"/>
      </params>
      <variables>
        <variable name="example_var" value="example_value_2"/>
      </variables>
      <user id="default" />
    </domain>
  </section>
</document>

 


Example: purpose=network-list

...

RESPONSE:

TODO: Example needed

 


Example: action=message-count

...

Code Block
languagexml
<document type="freeswitch/xml">
  <section name="directory">
    <domain name="domain-name">
      <user id="walker">
        <params>
           <param name="reverse-auth-user" value="walker" />
           <param name="reverse-auth-pass" value="321foo123" />
        </params>
      </user>
    </domain>
  </section>
</document>

 


This tells FreeSWITCH™ what credentials to use for the challenge.

 


Section: not found

If your web application receives a request and you don't wish to serve a config, then you should respond with 200 status code and the following "not found" result.

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<document type="freeswitch/xml">
  <section name="result">
    <result status="not found" />
  </section>
</document>

 


If you return an empty response instead of the not found, you may see the following error;

[ERR] switch_xml.c:1534 switch_xml_locate() Error[[error near line 1]: root tag missing]

 


post_load configuration

Due to the way FreeSWITCH loads modules and configuration, there are occasions where it will request a configuration in the format of 'post_load'

...

Code Block
languagexml
<document type="freeswitch/xml">
  <section name="configuration">
    <configuration name="switch.conf" description="Core Configuration">
      <param name="sessions-per-second" value="3000"/>
    </configuration>
  </section>
</document>

 


And a request for post_load_switch.conf would look like this;

Code Block
languagexml
<document type="freeswitch/xml">
  <section name="configuration">
    <configuration name="post_load_switch.conf" description="Core Configuration">
      <param name="sessions-per-second" value="3000"/>
    </configuration>
  </section>
</document>

 


The other example of this is post_load_modules.conf, because modules.conf has to be initially loaded from disk for the module to be available in the first place.

...

Code Block
languagexml
<?xml version="1.0"?>
<document type="freeswitch/xml">
  <section name="directory">
    <domain name="domain-name">
      <user id="1002" cacheable="true">
        <params>
          <param name="dial-string" value="{sip_invite_domain=${domain_name},presence_id=${dialed_user}@${dialed_domain}}${sofia_contact(${dialed_user}@${dialed_domain})}"/>
          <param name="a1-hash" value="50046ba744759aa83e045ba0b996e7a9"/>
        </params>
        <variables>
          <variable name="domain" value="domain-name"/>
          <variable name="user_id" value="1002"/>
        </variables>
      </user>
    </domain>
  </section>
</document>

 


If you then make a change to the directory you should run the xml_flush_cache command to clear, some examples:

...

Client implementations

PHP

Other languages

...

Lua can be called directly without a web server. See: Mod_lua/Serving_Configuration