SUMMARY

Send Message

General
The Send Message utility is a simple command line application that allows submitting messages to Message Service without using Message Center.

Command Line Parameter

The format is

SendMsg.exe parameter_list

The following parameters (case sensitive !) can be used

In addition the the above, the following optional parameters can be used

For E-Mail messages (/Type "E-MAIL")

For SMS messages (/Type "SMSx")

For SMS picture messages (/Type "SMSP")

For SMS operator logo messages (/Type "SMSOL")

For FAX messages (/Type "FAX")

For Scenarios (/Type "SCENARIO")

Direct sending

Instead of specifying a contact you can send a message directly to a number. To do so, use the following syntax instead of the contact name:

[E-MAIL:info@mawnet.com]
[FAX:0123456789]
[VOICE:0123456789]
[SMS:0123456789]

When sending a SMS directly, the central used is the one specified as default central in the preferences.

Examples

SendMsg.exe /Time "20000101000000" /Type "VOICE" /Recipient "MAW" /Message "Happy New Year"

will send a message on January 1st, 2000 at 0:00:00 h by Voice to the contact MAW with the contents "Happy New Year".
 

Messages to Contact lists can be sent by adding a ">" in front of the list name. Please note that contact list names need to be in uppercase.

IE
SendMsg.exe /Time "19990916231000" /Type "DEFAULT" /Recipient ">EMLIST" /Message "Fire in CR"

will send a message on September 16th, 1999 at 23:10:00 to all contacts on list EMLIST with the contents "Fire in CR2".

To send a message immediately without indicating the date/time, use NOW as TimeToSend value:

IE
SendMsg.exe /Time "NOW" /Type "DEFAULT" /Recipient "MAW" /Message "Hello world"

Depending on the available communication channels configured for each contact, the messages will be adapted.

Text in files
You can send texts that are located in a file by specifying the filename as message.

IE
SendMsg.exe /Time "NOW" /Type "SMST" /Recipient "[SMS:0123456789]" /Message "ForJohn.txt"

In this example ForJohn.txt would be a text file containing the message to be sent. It is your responsibility to make sure, that the message is not longer than 160 characters, otherwise it will not be accepted by the SMS central.

SMS Ringtones

Ringtones can be sent directly as text

IE
SendMsg.exe /Time "NOW" /Type "SMSR" /Recipient "[SMS:0123456789]" /Message "StarTrek:d=4,o=5,b=80:8g,16c6,f6,16e6,16c6,16a,16d6,8g6"

or in a file

IE
SendMsg.exe /Time "NOW" /Type "SMSR" /Recipient "[SMS:0123456789]" /Message "StarTrek.txt"


In this example StarTrek.txt would be a file containing the ringtone codes.

SMS Logos

The SMSOL parameter is only used when sending a message as SMS Operator Logo (SMSOL), here you need to specify the name of the operator of which you want to change the logo.

Valid operator names (IE "Switzerland - Swisscom NATEL") can be found in MsgCenter, when sending a message using the SMS link.

IE
SendMsg.exe /Time "20010101000000" /Type "SMSOL" /Recipient "[SMS:0123456789]" /SMSOL "Switzerland - Swisscom NATEL" /Message "c:\logo.gif"

E-Mail subjects

The Subject parameter is only used when sending a message as E-Mail or SMS.

IE
SendMsg.exe /Time "20010101000000" /Type "E-MAIL" /Recipient "[E-MAIL:info@mawnet.com]" /Subject "My Subject" /Message "Hello world!"

Scenario

To launch a predefined scenario TestScenario from SendMsg.exe please use the following format:

SendMsg.exe /Time "20010101000000" /Type "Scenario" /Scenario "TestScenario"

Voice messages

You can send a pre-recorded voice file:

SendMsg.exe /Time "20010101000000" /Type "VOICE" /Recipient "MAW" /Message "C:\DATA\Hello.wav"

Or you can send a normal text like "Hello world":

SendMsg.exe /Time "20010101000000" /Type "VOICE" /Recipient "MAW" /Message "Hello world"

In this case the message is read back character -per-character or is adapted.

If you would like the string "Hello world" read-back by the TTS-engine, use the format

SendMsg.exe /Time "20010101000000" /Type "VOICE" /Recipient "MAW" /Message "<TTS>Hello world"

You may also send an entire Designer voice script which is executed once the called person answers the phone:

SendMsg.exe /Time "20010101000000" /Type "VOICE" /Recipient "MAW" /Message "C:\INS\SampleScripts\VoiceScripts\SendAScript\SendAScript.vsc"

Return Values
SendMsg.exe returns an integer with the last 9 characters of the sID attributed to this message. The sID is the 17 digit message ID for every message, composed of the day/time stamp and a 3 digit counter. Format yyyymmddhhnnssccc, EG 20071231235959000.
SendMsg.exe therefore returns hhnnssccc only. If you need to refer to the full sID, you need to add yyyymmdd to the returned value.
If the time the message was submitted starts with 00 or 0 (from 00 to 09), then the return value is nnsscc or hnnssccc only and you need to add yyyymmdd00 or yyyymmdd0 for the complete string. 
For messages to a contact list, the return value is 0.
In the case of a failure to submit the message (EG if the recipient does not exist) , the value is -1.

API (application programming interface)

The API allows you to send TCP/IP commands to MsgService in order to submit messages or to query the status of a submitted message. MsgService is acting as TCP/IP Server and is listening for request on port 50120. If necessary you can change the port on the advanced configuration panel of MsgCenter.
Every request must be terminated by \r\n (carrier return and new line character). Depending on your development environment the actual characters used may be different.

The following requests are accepted:

Send messages
You may use the TCP/IP link to submit a message (instead of using SendMsg.exe).
Just use the same format as for SendMsg.exe (see above), preceded by the keyword "SENDMSG:"

EG
SENDMSG: /Time "now" /Type "VOICE" /Recipient "MAW" /Message "Happy New Year"\r\n

MsgService will return the 17 digit message ID of the submitted message (EG 20071231235959000) or -1 in case of an error. For messages to a contact list, the return string has the format sID1,sID2, sID3 where sID is the 17 digit message ID for every message (EG 20080305130300000,20080305130300001,20080305130300002).

You may use this ID any time later to request the status of the submitted message using the keyword "GETSTATUS:"

Get the status of a message
To retrieve the status of a message use the keyword "GETSTATUS:"

EG
GETSTATUS: /ID "20071231235959000"\r\n
 

The meaning of the returned status will be
    0 = Message is submitted and waiting to be sent
    1 = Message is currently sending
    2 = Message has been sent successfully
    3 = Message has been cancelled because of an error
    -1= Message ID does not exist (anymore)

APIDemo
Under c:\INS\Utilities\APIDemo\APIdemo.exe you find an utility that allows you to test the TCP/IP API connection.

Submit a message

Get the status of a submitted message

API TCP/IP Demo

The following PHP script may be used to submit messages to INS from a web server, through the TCP/IP interface.

<?php
error_reporting (E_ALL);

// This sample shows how to connect from a web server to the INS Server in order to send a message
// The sample assumes that INS is running on the local computer (local host: IP= 127.0.0.1) and is listening on port 50120 (default)
// it will then send the API command SENDMSG: /Time "now" /Type "SMST" /Recipient "MAW" /Message "Happy New Year" to
// the server and then return the MsgID for the submitted message.
// If INS is running on a remote computer, just change the IP address accordingly
// For more information about the API to send messages through INS please refer to http://www.ivrsoftware.ch/manual_sendmsg.html#idh_API
// Copyright MAW 2008


/* Modify those values to match your installation */
$INSServerIP   = "127.0.0.1";
$INSServerPort = "50120";

echo "<h2>TCP/IP Sample for a connection to the INS Server</h2>\n";

/* create a TCP/IP Socket*/
$socket = socket_create (AF_INET, SOCK_STREAM, SOL_TCP);
if ($socket < 0) {
echo "<br>socket_create() failed, reason: " . socket_strerror ($socket) . "\n";
} else {
echo "<br>Create socket: OK.\n";
}

echo "<br>Try to connect to '$INSServerIP:$INSServerPort' ...";
$result = socket_connect ($socket, $INSServerIP, $INSServerPort);
if ($result < 0) {
echo "<br>socket_connect() failed, reason: ($result) " . socket_strerror($result) . "\n";
} else {
echo "<br>Connected: OK.\n";
}

// Please refer to http://www.ivrsoftware.ch/manual_sendmsg.html#idh_API for the structure of the API command
$in = 'SENDMSG: /Time "now" /Type "SMST" /Recipient "MAW" /Message "Happy New Year"'."\r\n";
$out = '';

echo "<br>Send command to INS server ...";
socket_write ($socket, $in, strlen ($in));
echo "<br>OK.\n";


// Retrieve response from the INS server
echo "<br>Get response (MsgID) from INS server ...\n\n";
$out = socket_read ($socket, 2048);
echo "<br>".$out;


echo "<br>Closing socket ...";
socket_close ($socket);
echo "<br>Close socket: OK.\n\n";
?>

The following VBS/ASP script may be used to submit messages to INS from a web server, through the TCP/IP interface. As VBS/ASP does not come with an inbuild socket, you will need to install a third party socket provider.

'--- Written by Howard Champion, KeyBond Ltd, +447917014831, howard@keybond.co.uk
'--- This is provided "as is" with no warranties or liabilities of any kind
'--- ASP code for sending an SMS message via INS server
'--- using BASP21 socket component available at: http://www.hi-ho.ne.jp/babaq/data/BASP21-2003-0211.exe

Dim bsocket, rc
Set bsocket = CreateObject("basp21.socket")
'--- Connector accepts 3 parameters: hostname/ip address, port number and optional timeout in seconds (default 120)
'--- rc = bsocket.connect("[hostname or ip address of INS server]",[INS default port:50120])
'--- Example:
rc = bsocket.connect("10.0.0.10",50120)

If rc=0 then '--- so socket connection OK
'---rc responses:
' 0 : Connection OK!
' >0 : Winsock Error
' Typical error is : 11001 Hostname not found
' -1 : Socket open error
' -2 : Timeout

'--- now send the message via the INS Message Server service using the SENDMSG syntax:
'--- only used one variable, strBody, here, but can replace all with parameters sent
'--- to the function when called. (note SENDMSG /Time parameter would need to be included
'--- for scheduled sending)
strBody = "Sample message text"
MyCommand = "SENDMSG: /Type " & chr(34) & "SMST" & chr(34) & " /Recipient " & chr(34) & "[SMS:+4412345678]" & chr(34) & " /Message " & chr(34) & strBody & chr(34)
rc=bsocket.Write(MyCommand & chr(13) & chr(10))    'Finish command with CR/LF
If rc=0 then '---so socket write OK
'---rc responses:
' 0 : Sending OK
' > 0: Winsock Error
' -1 : Socket close.
' -2 : Timeout
' -3 : No Data
End If

'--- now close the socket connection:
bsocket.close

End If