☎️ SipCLI System Requirements

  • A Windows system with at least 2048 MBytes of RAM.
  • Microsoft.NET Framework v4.8 (Min.)

Installing and Uninstalling

To install sipcli, create a directory, extract sipcli.zip to that directory. To uninstall sipcli, simply remove the installation directory.

Running

Open a command line prompt and locate sipcli's installation directory:
SipCLI Command Line Parameters

  1. Create sipcli.ini in the installation directory. You can place sipcli.ini to a directory which is in search path of your environment. If you do not create sipcli.ini sipcli initialized with following default values:

     - Available first interface with IPv4 address with a default gateway will be
   selected as source IP address (ListenIP)
 - SIP port: 5070
 - Logging: Informative (0)
 - Timeout 30 seconds
 - SIP Domain: ListenIP:5060
 - Username: 5550000
 - Password: 'Blank'
 - Text to read: This is a test call made by SIP c l i

  2. Run sipcli from command line with the destination number (C:\sipcli 5551010).
  3. A message indicating result of the test call will be displayed to the console.

SipCLI.ini

You can find sipcli.ini parameters below:

    [CLI]
    ' You can specify an external IP address or alphanumeric address manually to be resolved
    ' to an IP address. This especially useful if your SIP destination is an external network
    ' and SipCLI is run behind a NAT gateway
    'EAddress='External IP address or alphanumeric address'
    ' ListenPort, you can set source UDP port, default: 5070
    ListenPort=5070
    ' You can specify SIP transport to be used, default is UDP. You can also set it to TCP or TLS.
    Transport=UDP
    ' Validate server certificate when TLS transport is used.
    ValidateServerCertificate=1
    ' You can set logging level
    ' 0: Informative, 1: Sessions, 2: Errors, 3: Debug
    ' Default: Informative (0)
    Logging=0
    ' You can set user codec, options: g711a, g711u, gsm and g729. Default: g711a.
    Codec=g711a
    ' Use SRTP
    UseSRTP=0
    ' You can specify a wave file for playout. You must use command line switch -w to play
    ' specified file to remote SIP endpoint. 
    WavFile=C:\Test.wav
    ' Specify scenario file's absolute path. File must be in clear text format.
    ScenarioFile=C:\scenario.txt
    ' Specify a SIP endpoint Id or a SIP URI to transfer a successful call.
    ' Sample SIP URI sip:1234@192.168.10.1:5060
    Referto=7751010
    ' You can specify call establishment timeout. Default 30 seconds, maximum 180 seconds.
    Timeout=25
    ' You can specify text message to read when -t switch used at command line.
    ' You can also specify a text file with full path.
    TexttoRead=This is my test message.
    ' You can specify TTS voice profile (Gender). Run Sipcli with -v parameter to list
    ' available profiles and you can specify voice profile with -v <Voice Profile #> in
    ' the command line.
    VoiceProfile=0
    ' The Volume property sets the base volume (loudness) level of the TTS synthesized voice.
    ' Values for the Volume property range from 0 to 100, representing the minimum and
    ' maximum volume levels, respectively.
    TTSVolume=100
    ' You can specify text message to send when -m switch used at command line.
    TexttoSend=This is my test message.
    ' You can enable or disable ENUM lookup, disable by default.
    ENUM=0
    ' How many digits will be collected maximum
    ' (Used when you set WavFile/TexttoSend parameter or use -w/-t command line switch)
    DigitLength=0
    ' How many seconds will be waited after last digit entered if user does not dial #
    ' (Used when you set WavFile/TexttoSend parameter or use -w/-t command line switch)
    DigitTimeout=2
    ' How many times welcome message will be played if no user input (DTMF digits) detected
    ' (Used when you set WavFile/TexttoSend parameter or use -w/-t command line switch)
    LoopCount=1
    ' DTMF can be received and detected inband (1) or send and received using SIP INFO method (2) in the commercial edition.
    ' RFC 2833 (0) method is used by default.
    DTMFTransport=0
    ' Force SipCLI to wait human response prior to execute a scenario. Default DetectHuman=0
    DetectHuman=1
    ' You can set Windows firewall rules for incoming SIP signaling and RTP media if necessary.
    SetFirewall=0
    ' Setting SlowStart=1 will force SipCLI to slow down to prevent CPU usage peaks on start up while encoding audio which
    ' can be observed in old PC systems.
    SlowStart=0
    ' Delays execution of a scenario in seconds.
    ExecutionDelay=1

    [Proxy]
    ' Specify SIP Proxy and optionaly UDP port. Default ListenIP:5060
    SIPProxy=192.168.10.10:5080
    ' Specify a SIP domain
    SIPDomain=kaplansoft.com
    ' Specify SIP username. Default: 5550000
    Username=5550000
    ' Specify SIP Authorization name if this is different than SIP username. Default: 5550000
    AUsername=5550000
    ' Specify password. Default is blank.
    Password=
    ' If remote system supports displaying alternative display name in From: header
    ' you can specify it here.
    DisplayName=02125550000
    ' You can force SipCLI to register itself prior to make a call, Default Register=0
    Register=1

You can overwrite ini file parameters using command line switches:

 C:\sipcli>sipcli 02135551122 -u 02135551010 -d 192.168.20.1:5090

SIP username will be set as 02135551010 and call request will be sent to SIP proxy 192.168.20.1 UDP port 5090. Command line switches;

 -u : Username
 -p : Password
-au : Specify SIP Authorization name if this is different than SIP username
 -n : Display Name (Called ID)
      Use double quotes if display name contains space ("Test User" e.g.)
 -d : SIP_Domain:Port
-op : SIP_Proxy:Port (Outbound SIP proxy)
 -l : Logging [0|1|2|3]
 -c : Codec [g711a|g711u|g729]
 -o : Timeout
 -t : Text or text file to read. Use full path for text files.
      Sample : C:\Program Files\sipcli 02135551122 -u 5551010 -t "This is a test message"
      Sample : C:\Program Files\sipcli 02135551122 -u 5551010 -t "C:\Textfile.txt"
      Sample : C:\Program Files\SipCLI 02135551122 -u 5551010 -t "http://example.com/text.txt"
 -k : SIP transport, UDP, TCP or TLS
 -y : Validate server certificate when TLS transport is used.
 -m : Text to send
      Sample : C:\Program Files\sipcli 02135551122 -u 5551010 -m "This is a test message"
 -w : URL (http/https) or absolute path of playout file
      Sample : C:\Program Files\sipcli 02135551122 -u 5551010 -w "C:\Program Files\sipcli\test.wav"
      Sample : C:\Program Files\SipCLI 02135551122 -u 5551010 -w "http://example.com/test.wav"
 -s : URL (http/https) or absolute path of scenario file (See "Custom Scenarios")
      Sample : C:\Program Files\sipcli 02135551122 -u 5551010 -s "C:\Program Files\sipcli\scenario.txt"
      Sample : C:\Program Files\SipCLI 02135551122 -u 5551010 -s "http://example.com/scenario.txt"
 -r : SIP Endpoint Id or a SIP URI to transfer a successful call
 -f : Length of the digit string to be collected (Used with -w/-t)
 -g : Inter digit time out (Used with -w/-t)
 -c : Pre-encodes audio prompts in a scenario file for faster startup. It must be used with -s
      parameters.
 -z : This will force SipCLI to wait a human response prior to execute a scenario.
 -h : Playout count (Used with -w/-t)
 -x : Use SRTP
 -j : Force SipCLI to register itself prior to make a call.
-ed : Delays scenario execution in seconds.
 -v : Lists available TTS voice profiles in the system when no value specified. Specify voice profile
      id listed when making a call (-v n where n is the voice profile id).

If you use -w switch without a wave file or no WavFile entry in sipcli.ini, built-in audio record will be played out.

You can make a call to an E.164 number using ENUM if the E.164 has an ENUM entry;

 C:\sipcli>sipcli 02135551122 -enum

If you run sipcli without any parameters you'll get quick help with Listen IP, SIP Port (UDP) and RTP Port (UDP) as shown below:

 IP Adr.: 192.168.10.1
 UDP P. : 5073
 RTP P. : 5074

You can specify your own command line parameters and use them as variables in your scenarios. User defined parameter keys must start with ud prefix. Variables must be surrounded by quotes. Example:

 sipcli -ud1 "My variable 1" -ud2 "My other variable"

You can use your command line variables in your scenarios by surrounding them with % sign:

 9=Synt-%ud1% %ud2%|3|1|1

Custom Scenarios

SipCli supports automated tasks defined in scenario scripts. You can execute scenarios defined in scenario files. Scenario files are text files consists of following sections and parameters. There are two sections in scenario files; [Prompts] and [Actions]. [Prompts] sections defines prompts can be used by Play action. A prompts can be a recorded audio file in wave format or a text can be synthesized by TTS engine. Every prompt must have a numeric Id associated with it. You must specify full path of the wave file. If wave file cannot be found or cannot be encoded by SipCli, the wave file will not be imported to the scenario.

 [Prompts]
 1=C:\sipcli\Welcome.wav
 2=C:\sipcli\Info-1.wav
 'TTS Text
 3="This is a test call"

Prompt id 0 is used internally to map "Silence". You cannot use 0 as prompt id in you scenarios.

[Actions] section contains actions to be executed. Every action has also a numeric Id and action identifier and parameters. Defined actions are Play, Exit, Send, Exec, Eval and Wait. Actions and their parameters are listed below with samples. Sipcli always starts scenario with action id = 0. Every actions' last parameter is the next actions' id except Exit which terminates the scenario. If you define an no-existent action as a next action SipCli will break the execution of the script. Script execution will also be terminated if the action step is not properly defined.

 [Actions]
 'Play Format
 'Step=Play-<Prompt>|<Count>|<DigitLength>|<DigitTimeout>|<Go to step>
 0=Play-1|3|1|1

 'Synthesise Format
 'Dynamically create audio prompt using Microsoft TTS
 'engine based on user text input. You can use internal variables
 '%called_number%, %calling_number%,  %received_digits%, %date%,  %sipdomain%,
 '%execout%  in prompt  text. You can not use pipe | character in prompt text.
 'Step=Synt-<Prompt>|<Count>|<DigitLength>|<DigitTimeout>|<Go to step>
 9=Play-Just a test made at %date%|3|1|1

 'Evaluate Format
 'Select next step bast on DTMF input
 'Step=Evaluate-<Default Case>|<Go to Step>;<Case 1>|<Go to Step>;..;<Case n>|<Go to Step>
 1=Evaluate-Default|7;23|2;24|3;25|7

 2=Play-1|3|7|3|3
 3=Play-2|3|7|3|4

 'Send Format
 'Step=Send-<Digit(s) to send>|<Inter digit delay in msec>|<Go to step>
 4=Send-124124|5

 'Wait Format
 'Step=Wait-<Prompt>|<Wait for seconds>|<Go to step>
 5=Wait-0|30|6

 'Record Format
 'Step=Save-<Prompt>|<Duration>|<Save to Directory>|<Go to step>
 6=Save-0|30|C:\SipCli\Messages|7

 'Exec Format
 'Step=Exec-<Full path to executable>|<Command line parameters>|<Wait for completion: True(1)/False(0)>|<Go to step>
 'Execute action executes the executable defined in ExecutablePath parameter. 
 'You must enter executable with full path. Valid predefined options for the
 'command   line   parameters  (ExecutableParameters)  are  %called_number%,
 '%calling_number%, %received_digits%, %execout%, %saved_audio_file%, %date%
 'and   %sipdomain%.  Predefined   parameters   are  case  sensitive.  Leave
 'ExecutableParameters   blank   if   no   parameter   will   be  used.  Set
 'WaitforCompletion > 0  in seconds if  you wish  SipCLI to  wait completion
 'of the execution of the executable and SipCLI will use  return value  (DOS
 'Errorlevel)  of the  executable as the  next action  be executed. You must
 'also define next step after the  action completed (NextAction). If you set
 'WaitforCompletion > 0 SipCLI will store  executable's  console  output (if
 'exists)  to  %execout%   variable  and  will  ignore  return   value  (DOS
 'Errorlevel) of executable.
 7=Exec-"C:\sipcli\test.bat"|"-u %called_number"|1|8

 'Exit Format 
 'Step=Exit-|
 'You can specify a prompt  to  be  played  out while exiting. You can also
 'specify a value which is returned as DOS  errorlevel. Return value can be 
 'an integer constant or %received_digits% variable.
 8=Exit-0|0

You can pre-encode audio prompt in a scenario file for faster startup. Run SipCLI with -c and -s parameters to pre-encode audo prompts in a scenario. SipCLI will create a binary file for pre-encoded audio file with the same name of scenario file added .sea (SipCLI Encoded Audio) extension. SipCLI will look for this file when you run SipCLI to execute this scenario file and it will skip encoding phase by directly read it into memomory if such a file is found. Please note that you need to pre-encode audio file each time you update the audio prompts in a scenario file otherwise you may experience unexpected results.


DOS Exit Codes

SipCLI exit codes which can be used by invoked application:

  0 Successful execution without calling
  1 Settings could not be loaded
  2 Scenario file parameter is missing
  3 Required parameter is missing
  4 Scenario file cannot be found
  5 Cannot download scenario file
  6 No valid action found in scenario file
  7 Free version allows running only a single instance of SipCLI
  8 Invalid SIP Proxy address

SipCLI returns SIP response after performing calling. SipCLI returns 200 for a successful call. Please see https://en.wikipedia.org/wiki/List_of_SIP_response_codes for possible SIP response codes to be returned.

Scenario Editor

You can create your own scenario using SipCli Scenario Editor (SEditor.exe). Before creating your scenario you must define audio prompts to be used in your scenario. Prompt and Action definitions for the scenario are stored in text files.

SipCLI Scenario Editor  SipCLI Scenario Editor

Scenario Editor reads SipCLI.ini under SipCLI application directory and allows you edit configuration parameters. Changes are auto saved when you exit Scenario Editor. SIP account password saved in encrypted form in SipCLI.ini when you edit SipCLI.ini using Scenario Editor.
SipCLI Configuration Editor

Follow us