Javascript module

Latest revision as of 14:11, 9 September 2024

Embedded Javascript language support.

The Javascript module has support for programmatically routing a call step by step.
At each step a new decision can be made about where to route the call next.
You can also use it to build global scripts.

[edit] Configuration

[general]
; General settings for the Javascript module

; scripts_dir: string: The absolute or relative path used by default to load
;  scripts if no full path is specified
;scripts_dir=${sharedpath}/scripts

; include_dir: string: The absolute or relative path used when including other
;  files via #include or #require if no full path is specified
; If the file is not found in include_dir it will be searched in scripts_dir
;include_dir=${configpath}

; routing: string: Name of the file holding the routing instructions
; Example: routing=route.js
;routing=

; max_length: integer: Maximum length of a single file
; Valid range 32768 to 2097152 (32KB to 2MB)
;max_length=500000

; allow_abort: boolean: Allow messages on level DebugFail to cause an engine abort
; Never enable it in production!
;allow_abort=no

; allow_trace: boolean: Allow the scripts to specify a trace file
; Never enable it in production!
;allow_trace=no

; allow_link: boolean: Allow linking of Javascript code (jump resolving)
;allow_link=yes

; track_objects: boolean: Track objects separately in each global script
;track_objects=no

; track_obj_life: unsigned integer: Number of lists to create for Hash List used
; for tracking object creation and destruction. Setting it to 0 deactivates tracking.
;track_obj_life=0

; auto_extensions: boolean: Automatically load scripting extensions in new scripts
; This does not prevent script code from explicitly loading extensions
;auto_extensions=yes

; keep_old_on_fail: boolean: Keep old scripts when replaced and failed to parse the new one
;keep_old_on_fail=no


[instances]
; Build multiple instances of specified scripts.
; The number of script instances is applied on module reload
; Each line has to be of the form
; name=number of instances
; The name must correspond with a [scripts] section entry
; Default value is one instance
; Examples:
;  faxes=3
; NOTE: When instances are set to more than 1 commenting the instances parameter or
;  setting it to 0 has no effect.
;  The module will not change the number of instances.
;  If you want to set a single instance you need to explicitly set instances to 1


[scripts]
; Add one entry in this section for each script that is to be loaded on Yate startup
; Each line has to be on the form:
;   name=script_file_name
; The name must be unique and it will identify the running script instance.
; The file name should hold either the absolute path and name or the path
;  and name relative to the scripts_dir in section [general]
; Examples:
;  faxes=fax_handler.js
;  callback=js_lib/callback.js

; The Eliza chat bot, enabled by default for your enjoyment in rmanager
eliza=eliza.js


[late_scripts]
; Add one entry in this section for each script that is to be loaded after Yate startup
; These scripts are loaded only after the engine and modules have initialized, immediately
;  after the dispatching of the "engine.start" message.
; The names must be unique and different from any in the [scripts] section.


[handlers]
; Install singleton message handlers
; These handlers are running using a separate context for each handled message
;
; Description:
; name=filename,callback,priority,trackname,parameters_prefix,filter,context,script_name
;
; Parameters (optional, unless otherwise specified):
; name: Required. Name of the message to handle
;     Names starting with 'handlerparam:' are ignored
; filename: Required. Script to load
; callback: Required. Callback function. Function is required to be present in script code
; priority: Handler priority. Default: 100
; trackname: Track name to be put in handled message 'handlers' parameter
; parameters_prefix: Prefix for handler parameters specified in separate section parameters
; filter: Message handler filter.
;     Format: filter_param=filter_value. Ignored if 'filter_param' is empty.
;     filter_value starting with '^' char is handled as extended POSIX regular expression
;     filter_value with length greater than 1 and ending with ^ will be negated (match when regexp does not match)
; context: String to be passed to callback function
; script_name: Name of the script. Used internally for debug purposes. Use 'filename' if empty
;
; Notes:
; - The following parameters are used to identify a handler:
;   name,filename,callback,priority,trackname,filter,context,script_name
;   An existing handler whose identity changed (not found in config) is removed at reload
; - Multiple handlers for the same message may be installed

; handlerparam:<parameters_prefix>:<param_name>: string: Configure a parameters for a handler
; Some of these parameters may be set in message handler description also (ignored here if so)
; They may be configured here since they may contain ',' in their contents
; Parameters:
; debug: string: Script debug (e.g. 'level 10'). This parameter is applied on reload
; context: string: Context to be passed to callback function
; filter: string: Message handler filter. See handler description for format
; track_priority: boolean: Add priority to tracked name. Default: true
; load_extensions: boolean: Load extensions in script context when a message is handled
;   This parameter is applied on reload
;   Default: [general] 'auto_extensions'
;   NOTE: Extensions won't be loaded if handled message is script.init
; keep_old_on_fail: boolean: Keep old code if failed to parse the new one
;   This parameter is used when handler is re-loaded and script changed
;   Default: [general] 'keep_old_on_fail'

[posthooks]
; Install singleton message posthooks
; These posthooks are running using a separate context for each handled message
;
; Description:
; id=filename,callback,parameters_prefix,filter,context,msg_name_filter,script_name,handled
;
; Parameters (optional, unless otherwise specified):
; id: Ignored
; filename: Required. Script to load
; callback: Required. Callback function. Function is required to be present in script code
; parameters_prefix: Prefix for posthook parameters specified in separate section parameters
; filter: Message parameters filter. See [handler] filter for description
; msg_name_filter: Message name filter. Same as parameters filter
; context: String to be passed to callback function
; script_name: Name of the script. Used internally for debug purposes. Use 'filename' if empty
; handled: Optional, boolean. Call the callback function only if message was handled or not
;
; Notes:
; - The following parameters are used to identify a posthook:
;   id,filename,callback,filter,context,msg_name_filter,script_name,handled
;   An existing posthook whose identity changed (not found in config) is removed at reload

; handlerparam:<parameters_prefix>:<param_name>: string: Configure a parameters for a posthook
; Some of these parameters may be set in posthook description also (ignored here if so)
; They may be configured here since they may contain ',' in their contents
; Parameters:
; debug: string: Script debug (e.g. 'level 10'). This parameter is applied on reload
; context: string: Context to be passed to callback function
; filter: string: Message parameters filter. See posthook description for format
; msg_name_filter: string: Message name filter. See posthook description for format
; load_extensions: boolean: Load extensions in script context when a message is handled
;   This parameter is applied on reload
;   Default: [general] 'auto_extensions'
;   NOTE: Extensions won't be loaded if handled message is script.init and posthook message name
;         matches script.init
; keep_old_on_fail: boolean: Keep old code if failed to parse the new one
;   This parameter is used when posthook is re-loaded and script changed
;   Default: [general] 'keep_old_on_fail'
; engine.timer: boolean: Set it to true to force handling of engine.timer message
;   engine.timer is ignore by default if a message name filter was not set

[edit] Routing

The Javascript module has support for programmatically routing a call step by step.
At each step a new decision can be made about where to route the call next.

[edit] Configuration

To configure routing script you must list it in the javascript.conf file, in parameter: routing.

[general]
routing=route.js

[edit] Routing script

Note that you can have a single such routing script in [default] section. It is however possible to use #include to include other scripts and call functions.

The script file is loaded and parsed when the Javascript module is (re)loaded. In rmanager you can issue the reload javascript command.

You can find an example script here.

[edit] How it Works

When a call is coming, an inbound call leg is created.

The inbound call leg is associated with a new script instance.

[edit] Main code flow

The parameters in the call.route message are set in the message variable.

Then the main code flow(that is, outside any function) is executed.

The Javascript code can make decisions based on these parameters and can call methods of the Channel object to route the call to the desired destination.

See also

• Javascript
• How to do routing using javascript
• Routing