Event channel

1. Description

miniSIPServer event channel is a message channel built on web socket. miniSIPServer sends inner call status or warning to outsides applications through this interface.

Event channel between miniSIPServer and applications

As illustrated in above figure, we can get following key points about miniSIPServer event channel:

  • Event channel is over websocket, so applications must establish websocket to miniSIPServer firstly.
  • Event messages are JSON format text.

At this time, miniSIPServer will check IP address of applications for authorization. If the IP address isn't configured in miniSIPServer, miniSIPServer will reject websocket connection from such IP address.

2. Configuration
2.1 System

By default, miniSIPServer opens TCP port 5080 to accept websocket connection. Of course, you can change it according to your own requirement. Please click menu "Data / System / Basic" and update "event channel port" illustrated in below figure.

websocket port configuration
2.2 IP address authorization

If application wants to connect to miniSIPServer event channel, we must add its address into miniSIPServer for authorization. Please click menu "Maintain / Event channel authorization" to add IP addresses to be trusted.

Add IP address for authorization
3. Events

This section describes all details about event messages sent from miniSIPServer. As we said, all messages are JSON format text strings.

Here is a demo event message from miniSIPServer. It is used to report status of local user '600'.

{"command": "userStatus", "userName": "600", "status": "online"}

Every event message MUST include 'command' paramter. This parameter indicates what this message is. At this time, it can be following values.

  • userStatus - report local users' status
  • sipStatus - report states of SIP calls
  • sipTrunkWarning - report warning information if SIP trunk has problem
3.1 userStatus

'userStatus' event includes following items.

Item Type Description
userName string Local user's name or number.
status string Current status of the local user. It can be these values:
  • online - the user has registered to miniSIPServer.
  • offline - the user is offline, it has unregistered from miniSIPServer.
3.2 sipStatus

miniSIPServer will report every SIP calls state via these event messages. Since each call party could be in different call side, these messages will have different parameters. That means following paramters are optional according to different calls.

Item Type Description
sipID string This is miniSIPServer inner ID. It is unique resource ID in miniSIPServer for each call.
callID string This is retrieved from 'Call-ID' parameter of SIP messages. 'callID' is unique in a SIP dialog.
Please pay attention that it could inclue several different 'sipID' in the same SIP dialog.
stage string Stage of current call. It can be following values.
  • dial - the call is just invoked now.
  • alert - the call is ringing back tone or playing alert tone.
  • talk - called part answers the call.
  • idle - the call is released.
type integer It indicates what kinds of call type current call is.
  • 1 - this call is outgoing call, that means the user is making call out.
  • 2 - this call is incoming call, that means the user is receiving call.
address string The user's IP address.
from string Caller party number.
to string Called party number, or destination number.
setupTime string The timestamp when the call is initiating.
alertTime string The timestamp when the call is ringing or playing ring back tone.
talkTime string The timestamp when the call is picked up.
idleTime string The timestamp when the call is released.

Here are some sample messages.

(1) The call is invoking.

{"command": "sipStatus", "sipID": 823853058, "callID": "24F94C6671233752773D3106MSS311B0002", "stage": "dial", "type": 2, "address": "", "from": "600", "to": "601", "setupTime": "2018-09-03 16:45:09"}

(2) The call is released.

{"command": "sipStatus", "sipID": 823853058, "callID": "24F94C6671233752773D3106MSS311B0002", "stage": "idle", "idleTime": "2018-09-03 16:45:17"}

3.3 sipTrunkWarning

If miniSIPServer receives a call from SIP trunk but the port is different with configuration, miniSIPServer will reject such call and report this warning information.

'sipTrunkWarning' event includes following items.

Item Type Description
ipAddr string The IP address where the call is from.
port integer The real port where the call is from.

Here is a sample message.

{"command": "sipTrunkWarning", "ipAddr": "", "port": 6666}