---
title: "MI script Module"
description: "This module provides multiple hooks to run Management Interface commands directly from OpenSIPS script."
---

## Admin Guide


### Overview


This module provides multiple hooks to run Management Interface
commands directly from OpenSIPS script. It supports running
both synchronous and asynchronous commands. Depending on the
nature of the command (asynchronous or not), and on the way
the *mi* command is run from script,
the returned result is different.


### Values Returned


In case of success, the MI command returns with success.
If a return variable is provided as parameter,
a JSON is also stored in the variable provided.


In case of failure of the MI command, JSON-RPC reply error code
is stored in the *$rc* variable, as a negative
number. Lower values, such as *-1,-2,-3* can also
be returned to indicate an internal error. If a return variable is
provided, it is stored to the error description.


### Dependencies


#### OpenSIPS Modules


The following modules must be loaded before this module:


- *proto_hep module*, in case MI
tracing is used.


#### External Libraries or Applications


The following libraries or applications must be installed before
running OpenSIPS with this module loaded:


- *none*


### Exported Parameters


#### pretty_printing (int)


Indicates whether the JSON responses stored in the return
variable should be pretty-printed or not.


*Default value is "0 - no pretty-printing".*


```opensips title="Set pretty_printing parameter"
...
modparam("mi_script", "pretty_printing", 1)
...
```


#### trace_destination (string)


Trace destination as defined in the tracing module. Currently
the only tracing module is **proto_hep**.
This is where traced mi messages will go.


> [!WARNING]
> A tracing module must be
> loaded in order for this parameter to work. (for example
> **proto_hep**).


*Default value is none(not defined).*


```opensips title="Set trace_destination parameter"
...
modparam("proto_hep", "trace_id", "[hep_dest]10.0.0.2;transport=tcp;version=3")

modparam("mi_script", "trace_destination", "hep_dest")
...
```


#### trace_bwlist (string)


Filter traced mi commands based on a blacklist or a whitelist.
**trace_destination** must be defined for
this parameter to have any purpose. Whitelists can be defined using
'w' or 'W', blacklists using 'b' or 'B'. The type is separate by the
actual blacklist by ':'. The mi commands in the list must be separated
by ','.


Defining a blacklists means all the commands that are not blacklisted
will be traced. Defining a whitelist means all the commands that are
not whitelisted will not be traced.
> [!WARNING]
> One can't define both
> a whitelist and a blacklist. Only one of them is allowed. Defining
> the parameter a second time will just overwrite the first one.


> [!WARNING]
> A tracing module must be
> loaded in order for this parameter to work. (for example
> **proto_hep)**.


*Default value is none(not defined).*


```opensips title="Set trace_destination parameter"
...
## blacklist ps and which mi commands
## all the other commands shall be traced
modparam("mi_script", "trace_bwlist", "b: ps, which")
...
## allow only sip_trace mi command
## all the other commands will not be traced
modparam("mi_script", "trace_bwlist", "w: sip_trace")
...
```


### Exported Functions


#### mi(command, [ret_var [,params_avp[, vals_avp]]])


Runs an MI command in synchronous mode, blocking
until a response is available.


> [!IMPORTANT]
> It is highly recommended
> to prevent using this function for tasks that take long
> time, such as reloads, as the function would block until
> the command ends. Moreover, if the running MI
> *command* is configured to run in
> asynchronous mode (such as *t_uac_dlg*
> the command blocks in a busy waiting manner until
> the response is received.


This function can be used in any route.


The function can receive the following parameters:


- *command(string)* - the MI command
to be run. This can be a single token, representing
the MI command to run (without parameters), or
can be followed by several space separated
parameters (no escaping is handled). Each space
separated parameter will be passed to the MI
command as an indexed parameter.
*NOTE:* named parameters can
not be specified using this parameter, and you
will have to use the *params_avp*
and/or the *vals_avp* parameters
to specify named commands, in which case this
parameter will only consist of the MI command.
- *ret_var(var, optional)* - a
variable used to store the return of the
MI command execution. In case of success,
a JSON is stored, otherwise an erorr message.
- *params_avp(avp, optional)* - an
AVP consisting of all the parameters names that
will be sent to the MI command. If this parameter
is used without the *vals_avp*,
all the values inside the AVP will be passed to the
MI command as indexed parameters, otherwise as
named parameters.
*NOTE:* if this parameter
is used, the parameters specified in the
*command* parameter are ignored.
*NOTE:* the order the
parameters are passed to the command is the
same as the one you populate the AVPs (thus
somehow reversed compared to the way AVPs are
stored in memory - the first AVP added is the
first parameter)
- *vals_avp(avp, optional)* - an
AVP consisting of all the parameters values that
will be sent to the MI command. This parameter
only makes sense if the *params_avp*
is set, and has to contain the same number
of values as there are parameters.
To specify *array values*, enclose your
space-separated array elements in the *__array()*
pseudo-function call.  For example:
*"__array(HEARTBEAT BACKGROUND_JOB)"*


```opensips title="mi without params"
...
mi("shm_check");
...
```


```opensips title="mi with params in command"
...
# this command is similar to the above
mi("cache_remove local password_user1");
...
```


```opensips title="mi with return"
...
mi("ds_list", $var(ret));
...
```


```opensips title="mi without return but with indexed params"
...
$avp(params) = "local";
$avp(params) = "password_user1";
mi("cache_remove",,$avp(params));

# the following command is similar to the above
mi("cache_remove local password_user1");
...
```


```opensips title="mi with return and named parameters"
...
$avp(params) = "callid";
$avp(vals) = "SEARCH_FOR_THIS_CALLID";
$avp(params) = "from_tag";
$avp(vals) = "SEARCH_FOR_THIS_FROM_TAG";
mi("dlg_list", $var(dlg), $avp(params), $avp(vals));
...
```


```opensips title="mi without return, with an array parameter value"
...
$avp(params) = "freeswitch_url";
$avp(vals) = "fs://:ClueCon@192.168.20.8:8021";
$avp(params) = "events";
$avp(vals) = "__array(HEARTBEAT BACKGROUND_JOB)";
mi("fs_subscribe", , $avp(params), $avp(vals));
...
```


### Exported Asynchronous Functions


#### mi(command, [ret_var [,params_avp[, vals_avp]]])


The function works is more or less the same as its
synchronous corespondent, except that the MI command
is run in an asynchronous manner - the process does
not block to wait for the response, but it continues
its execution and the MI command is run in an
asynchronous context.


> [!NOTE]
> Currently MI commands run
> asynchronously cannot be traced through hep.


```opensips title="async mi call usage"
...
xlog("reload starting\n");
async(mi("dr_reload"), after_reload);
...

route[after_reload] {
	xlog("reload completed\n");
}
```
<!-- CONTRIBUTORS -->

### License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0
