---
title: "JSON-RPC Module"
description: "This module is an implementation of an JSON-RPC v2.0 client [http://www.jsonrpc.org/specification](http://www.jsonrpc.org/specification). that can send a call to a JSON-RPC server over a TCP connection."
---

## Admin Guide


### Overview


This module is an implementation of an JSON-RPC v2.0
client [http://www.jsonrpc.org/specification](http://www.jsonrpc.org/specification).
that can send a call to a JSON-RPC server over a TCP connection.


> [!NOTE]
> That the current version of this module does not support TCP
> connection reusage, nor asynchronous commands.


### Dependencies


#### OpenSIPS Modules


The following modules must be loaded before this module:


- *none*.


#### External Libraries or Applications


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


- *none*


### Exported Parameters


#### connect_timeout (integer)


The amount of milliseconds OpenSIPS waits to connect to the the
JSON-RPC server, until it times out.


*Default value is "500 milliseconds".*


```opensips title="Set connect_timeout parameter"
...
modparam("jsonrpc", "connect_timeout", 200)
...
```


#### write_timeout (integer)


The amount of milliseconds OpenSIPS waits to send a RPC command to
the JSON-RPC server, until it times out.


*Default value is "500 milliseconds".*


```opensips title="Set write_timeout parameter"
...
modparam("jsonrpc", "write_timeout", 300)
...
```


#### read_timeout (integer)


The amount of milliseconds OpenSIPS waits for the JSON-RPC server
to respond to a JSON-RPC request, until it times out. Note that
these parameter only affects the *jsonrpc_request*
command.


*Default value is "500 milliseconds".*


```opensips title="Set read_timeout parameter"
...
modparam("jsonrpc", "read_timeout", 300)
...
```


### Exported Functions


#### jsonrpc_request(destination, method, params, ret_var)


Does a JSON-RPC request to the JSON-RPC server
indicated in the *destination*
parameter, and waits for a reply from it.


This function can be used from any route.


The function has the following parameters:


- *destination* (string) - address of the
JSON-RPC server. The format needs to be
*IP:port*.
- *method* (string) - the method used in
the RPC request.
- *params* (string) - these are the parameters
sent to the RPC method. This parameter needs to be
a properly formated JSON array, or JSON object,
according the the JSON-RPC specifications.
- *ret_var* a writeable variable
used to store the result of the JSON-RPC command. If
the command returns an error, the variable will be
populated with the error JSON, otherwise, with the
body of the JSON-RPC result.


The function has the following return codes:


- *1* - JSON-RPC command executed
successfully, and the server returned success. You can
check the *ret_pvar* variable for
the result.
- *-1* - There was an internal error
during processing.
- *-2* - There was a connection
(timeout or connect) error with the destination.
- *-3* - The JSON-RPC was
successfully run, but the server returned an error.
Check the *ret_pvar* value to find
out more information.


```opensips title="jsonrpc_request() function usage"
	...
	if (!jsonrpc_request("127.0.0.1", "add", "[1,2]", $var(ret))) {
		xlog("JSON-RPC command failed with $var(ret)\n");
		exit;
	}
	xlog(JSON-RPC command returned $var(ret)\n");
	# parse $var(ret) as JSON, or whatever the function returns
	...
	
```


#### jsonrpc_notification(destination, method, params)


Does a JSON-RPC notification to the JSON-RPC server
indicated in the *destination*
parameter, but unlike [jsonrpc request](#jsonrpc_requestdestination-method-params-ret_var),
it does not wait for a reply from the JSON-RPC server.


This function can be used from any route.


The function receives the same parameters as 
[jsonrpc request](#jsonrpc_requestdestination-method-params-ret_var), except for the *ret_pvar*. Also, the same values are returned.


```opensips title="jsonrpc_notification() function usage"
	...
	if (!jsonrpc_notification("127.0.0.1", "block_ip", "{ \"ip": \"$si\" }")) {
		xlog("JSON-RPC notification failed with $rc!\n");
		exit;
	}
	...
	
```
<!-- CONTRIBUTORS -->

### License

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