mirror of
https://github.com/signalwire/freeswitch.git
synced 2026-07-05 20:01:55 +00:00
Anthony Minessale
349 lines
14 KiB
Plaintext
349 lines
14 KiB
Plaintext
HT-TAPI Hyper-Text Telephony API and http file format plugin
|
|
|
|
This module provides an HTTP based Telephony API using a standard FreeSWITCH application interface as well as a cached http file format interface.
|
|
|
|
The file format plugin can be used like this:
|
|
<action application="playback" data="http://some.com/sounds/foo.wav"/>
|
|
|
|
This syntax is valid anywhere a filename parameter is requested in FreeSWITCH.
|
|
|
|
|
|
The application is called like this:
|
|
|
|
<action application="httapi" data="{url=http://some.host.com/app.cgi}"/>
|
|
|
|
The target url is expected to be a CGI returning text/xml using the documentation below.
|
|
|
|
The format is roughly as described below (We could use a DTD maybe).
|
|
|
|
<document type="xml/freeswitch-httapi">
|
|
<params>
|
|
<someparam>someval</someparam>
|
|
</params>
|
|
<variables>
|
|
<somevar>someval</somevar>
|
|
</variables>
|
|
<work>
|
|
<...>
|
|
</work>
|
|
</document>
|
|
|
|
|
|
The profile name must be chosen to bind to a preset series of settings and permissions to use as a basis for the client session.
|
|
It's chosen from the specified params or from the channel variable using the keyname 'httapi_profile' and if not specified will default to 'default'
|
|
Any params specified in the initial data of the application encased in brackets {} will be parsed into the initial params similar to originate.
|
|
These params remain set until the call ends and are supplied as form elements on each hit to the HTTP server.
|
|
If the permissions allow, a <params> tag is parsed from the resulting document and set into this data set and will be mirrored back on subsequqent http posts.
|
|
Also if the permissions allow a <variables> tag is parsed the same way setting channel variables.
|
|
The <work> tag is required and contains one or more of the supported command tags that generally manipulate the call behaviour.
|
|
The application will continue to do the task in the work section until an error is encoutered or when an action from the work tag warrants it.
|
|
If the session exits the httapi app without hanging up it can do other tasks and make another call to httapi and the session data will remain preserved.
|
|
|
|
|
|
EXAMPLE:
|
|
|
|
<document type="xml/freeswitch-httapi">
|
|
<params></params>
|
|
<work>
|
|
<playback name="exten" file="http://my.com/sounds/exten.wav" error-file="http://my.com/sounds/invalid.wav" input-timeout="5000">
|
|
<bind strip="#">~\d+#</bind>
|
|
</playback>
|
|
</work>
|
|
</document>
|
|
|
|
BINDINGS
|
|
Several of the work tags that indicate they support bindings can contain one of more bind tags that function with similar fashion to bind_digit_action
|
|
|
|
<bind action strip>*EXPR*</bind>
|
|
|
|
ATTRS:
|
|
action : a specific url to go to next if the binding is dialed
|
|
strip : a character to strip from in the result such as #
|
|
|
|
WORK TAGS:
|
|
<work>*ACTIONS*</work>
|
|
|
|
|
|
<playback file name error-file action digit-timeout input-timeout loops asr-engine asr-grammar><bind action strip>*EXPR*</bind></playback>
|
|
: Plays a file and optionally collects input.
|
|
|
|
ATTRS:
|
|
file : The file
|
|
name : Param name to save result.
|
|
error-file : Error file to play on invalid input.
|
|
action : Change the new target url.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
digit-timeout : Timeout waiting for digits after file plays (when input bindings are present)
|
|
input-timeout : Timeout waiting for more digits in a multi-digit input.
|
|
loops : max times to play the file when input bindings are present.
|
|
asr-engine : ASR engine to use
|
|
asr-grammar : ASR grammar to use
|
|
|
|
|
|
<vmname file name action digit-timeout input-timeout loops><bind action strip>*EXPR*</bind></playback>
|
|
: Plays a vm name and optionally collects input.
|
|
|
|
ATTRS:
|
|
file : The file
|
|
name : Param name to save result.
|
|
error-file : Error file to play on invalid input.
|
|
action : Change the new target url.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
digit-timeout : Timeout waiting for digits after file plays (when input bindings are present)
|
|
input-timeout : Timeout waiting for more digits in a multi-digit input.
|
|
loops : max times to play the file when input bindings are present.
|
|
|
|
|
|
|
|
|
|
|
|
<record file name error-file action digit-timeout input-timeout><bind action strip>*EXPR*</bind></record>
|
|
: Records a file, optionally collects input and posts the file back to the target url.
|
|
|
|
ATTRS:
|
|
file : The file
|
|
name : Param name to save result.
|
|
error-file : Error file to play on invalid input.
|
|
action : Change the new target url.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
digit-timeout : Timeout waiting for digits after file plays (when input bindings are present)
|
|
input-timeout : Timeout waiting for more digits in a multi-digit input.
|
|
|
|
|
|
|
|
|
|
|
|
<pause name error-file action digit-timeout input-timeout loops milliseconds><bind action strip>*EXPR*</bind></pause>
|
|
: Waits for input for a specific amount of time.
|
|
|
|
ATTRS:
|
|
milliseconds : Number of milliseconds to pause
|
|
name : Param name to save result.
|
|
error-file : Error file to play on invalid input.
|
|
action : Change the new target url.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
digit-timeout : Timeout waiting for digits after file plays (when input bindings are present)
|
|
input-timeout : Timeout waiting for more digits in a multi-digit input.
|
|
loops : max times to play the file when input bindings are present.
|
|
|
|
|
|
|
|
|
|
|
|
<speak file name error-file action digit-timeout input-timeout loops engine voice><bind action strip>*EXPR*</bind></speak>
|
|
: Read Text to Speech with optional input.
|
|
|
|
ATTRS:
|
|
file : The file
|
|
name : Param name to save result.
|
|
error-file : Error file to play on invalid input.
|
|
action : Change the new target url.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
digit-timeout : Timeout waiting for digits after file plays (when input bindings are present)
|
|
input-timeout : Timeout waiting for more digits in a multi-digit input.
|
|
loops : max times to play the file when input bindings are present.
|
|
engine : tts engine to use.
|
|
voice : tts voice to use.
|
|
|
|
|
|
|
|
|
|
|
|
<say file name error-file action digit-timeout input-timeout loops language type method gender><bind action strip>*EXPR*</bind></say>
|
|
: Use the FS say engine to iterate sounds to similate a human speaker.
|
|
|
|
ATTRS:
|
|
file : The file
|
|
name : Param name to save result.
|
|
error-file : Error file to play on invalid input.
|
|
action : Change the new target url.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
digit-timeout : Timeout waiting for digits after file plays (when input bindings are present)
|
|
input-timeout : Timeout waiting for more digits in a multi-digit input.
|
|
loops : max times to play the file when input bindings are present.
|
|
language : language
|
|
type : type (fs param)
|
|
method : method (fs param)
|
|
gender : gender (fs param)
|
|
|
|
|
|
|
|
|
|
|
|
<execute application data action>*DATA*</execute>
|
|
: Execute a FreeSWITCH app.
|
|
ATTRS:
|
|
application : The app to run
|
|
action : Change url to submit to.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
data : Alternate source for app data
|
|
*DATA* : The app data
|
|
|
|
|
|
|
|
<sms to action>DATA</sms>
|
|
: Send a SMS message.
|
|
ATTRS:
|
|
to : The dest number
|
|
action : Change url to submit to.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
*DATA* : The message data
|
|
|
|
|
|
|
|
|
|
|
|
<dial context dialplan caller-id-name caller-id-number action>*DATA*</dial>
|
|
: Place an outbound call or transfer.
|
|
|
|
ATTRS:
|
|
context : Dialplan context.
|
|
dialplan : Dialplan dialplan.
|
|
caller-id-name : Caller ID Name.
|
|
caller-id-number : Caller ID Number.
|
|
action : Change url to submit to.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
*DATA* : Number to dial or originate string
|
|
|
|
|
|
|
|
|
|
|
|
<recordCall limit name action>
|
|
: begin recording the call. The file will be posted when the call ends.
|
|
|
|
ATTRS:
|
|
limit : Timeout in seconds.
|
|
name : Name to use for input values.
|
|
action : URL action to use.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
|
|
|
|
|
|
|
|
<conference profile action>
|
|
: Start a conference call.
|
|
|
|
ATTRS:
|
|
profile : Conference profile to use.
|
|
action : Change url to submit to.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
|
|
|
|
<answer is-conference>
|
|
: Answer the call
|
|
|
|
ATTRS:
|
|
is-conference : true|false (set the conference flag for RFC4579 stuff.
|
|
|
|
|
|
<hangup cause action>
|
|
: Hangup the call
|
|
|
|
ATTRS:
|
|
cause : Hangup cause
|
|
action : Change url to submit to.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
|
|
|
|
|
|
<break>
|
|
: Exit the httapi application and continue in the dialplan.
|
|
|
|
|
|
|
|
|
|
|
|
<log level clean action>
|
|
: Write a log line to fs_cli, console, logs, etc.
|
|
ATTRS:
|
|
level : The log level to use.
|
|
clean : If true do not print log prefix.
|
|
action : Change url to submit to.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
|
|
<continue action>
|
|
: Just continue (no-op)
|
|
|
|
ATTRS:
|
|
action : Change url to submit to.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
|
|
|
|
<getVar action temp-action permanent/>
|
|
: Get a Channel variable (depends on permissions)
|
|
|
|
ATTRS:
|
|
action : Change url to submit to.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
permanent : Add as a permanent param or just once.
|
|
|
|
|
|
<voicemail action temp-action check auth-only profile domain id/>
|
|
: Call the voicemail app without requiring "execute" permissions
|
|
|
|
ATTRS:
|
|
action : Change url to submit to.
|
|
temp-action : Change url to submit to. just for the next loop.
|
|
check : true to check (omit to leave)
|
|
auth-only : authenticate only and move on
|
|
profile : profile name to use (omit for "default")
|
|
domain : domain to use (omit for global domain variable)
|
|
id : id to use (omit to prompt for id)
|
|
|
|
|
|
|
|
|
|
|
|
CONFIGURATION:
|
|
|
|
<settings>:
|
|
<param name="" value="">
|
|
debug : <true|false> false Print debug data
|
|
file-cache-ttl : <number of sec> 300 How long to wait before checking the server to see if audio file has changed.
|
|
Whichever is smaller that or the max-age returned by the server (if present).
|
|
abs-file-cache-ttl : <number of sec> 0 Force the cache time no matter what anything else says.
|
|
file-not-found-expires : <number of sec> 300 How long to still preserve cached audio files that are not found by the server.
|
|
|
|
<profile name="<name>"> : CREATE NEW PROFILE TO REFERENCE BY NAME
|
|
gateway-url : <string> "" Initial URL to connect to.
|
|
gateway-credentials : <string> "" HTTP credentials.
|
|
auth-scheme : <string > basic auth scheme to use. [basic|digest|NTLM|GSS-NEGOTIATE|any]
|
|
disable-100-continue : <true|false> true Disable the 100 continue feature.
|
|
method : <string> "" METHOD name to send.
|
|
timeout : <number> 0 Timeout waiting for response.
|
|
enable-cacert-check : <true|false> false Check CA/CERT.
|
|
ssl-cert-path : <string> "" path to file.
|
|
ssl-key-path : <string> "" path to file.
|
|
ssl-key-password : <string> "" password to use.
|
|
ssl-version : <string> "" ssl version
|
|
ssl-cacert-file : <string> "" CA/CERT file.
|
|
enable-ssl-verifyhost : <true|false> "" Verify ssl host.
|
|
cookie-file : <string> "" Path to file to use for cookie.
|
|
enable-post-var : <param_name> "" Specify specifc param names ok to send.
|
|
bind-local : <string> "" Interface to bind to.
|
|
default-profile : <string> default Profile to use when not specified.
|
|
user-agent : <string> mod_httapi/1.0 User Agent header value.
|
|
|
|
|
|
<permissions>: * = default
|
|
<permission name="" value="true">
|
|
|
|
*set-params : <params> tag can be parsed for session params.
|
|
set-vars : <variables> tag can be parsed to set channel vars.
|
|
extended-data : Extended data is sent like full channel event data.
|
|
execute-apps : <execute> tag is enabled to execute apps.
|
|
expand-vars : Allow expansion of FS ${variables}. (this opens up all FSAPI calls)
|
|
*dial : <dial> tag is enabled allowing outbound dialing.
|
|
dial-set-context : <dial context=""> context attribute is permitted.
|
|
dial-set-dialplan : <dial dialplan=""> dialplan attribute is permitted.
|
|
dial-set-cid-name : <dial cid_name=""> cid_name attribute is permitted.
|
|
dial-set-cid-number : <dial cid_number=""> cid_number attribute is permitted.
|
|
dial-full-originate : <dial> full originate syntax is permitted instead of just a number.
|
|
*conference : <conference> tag is enabled allowing creation of conferences.
|
|
conference-set-profile : <conference profile=""> attribure is permitted.
|
|
all : all permissions are set
|
|
none : no permissions are set
|
|
|
|
|