iSMS Send API

HTTP Send API Format

Each “HTTP Send API Request” consists of four parts:
• The first part is the destination; i.e., the MultiModem iSMS IP and HTTP port number.
• The second part is the API call which is the query; therefore, it has a ‘?’ post-fixed to the call.
• The third part is for authentication, which is in the form of a username and password.
• The fourth part is the message parameters.

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=puser1&cat=1&to="7637175845"&text=message

Where, portnumber is optional and

user1,puser1, 7637175845 and message are variable/configured parameters.

When HTTP Send API is enabled, it is also possible to send SMS from a non-browser with a TCP connection to the configured HTTP Port by following the steps below:
• Initiate a raw TCP connection to the MultiModem iSMS IP address over the “HTTP Send API” port
Example : telnet 192.168.2.1 81
• Issue GET command to send SMS.
• Issue GET command to query the status of send SMS.

Send API Format

GET /sendmsg?user=admin&passwd=admin&cat=1[&enc=0][&priority=1][&modem=2]&to=5645676543&ton=Graham&group=Engineering&text=This%20is%20a%20test%20m
essage.^M^J

Or

GET /sendmsg?user=admin&passwd=admin&cat=1[&enc=1][&priority=2][&modem=0]&to=%225678976543%22&ton=%22Bob%22&group=%22Engineering%22&text=This%20is%20a%20test%20message.^M^J

Query API Format

GET /querymsg?user=admin&passwd=admin&apimsgid=message id.^M^J

Note: All special characters must be given in URL encoded format with hex value; e.g., space should be given as %20; double quotes should be given as %22.
Example: If a name is Graham Bell, it should be given as Graham%20Bell

Authentication

The system needs to authenticate any API request. We achieve this by having the authentication credentials as part of the “Send SMS URL” or “Send SMS TCP” command.
user – The username of the account, which has a maximum of 50 bytes.
passwd – The password of the account, which has a maximum of 50 bytes.
This user should be Admin or the configured Send Users.
Every “Send SMS URL” should have the username and password, and every request is authenticated by the MultiModem iSMS.

Sending to a Number

HTTP API format is:

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=puser1&cat=1[
&enc=0][&priority=1][&modem=1]&to=”7657867765”&text=message

The parameters are:

• cat Category
1 – Send SMS
2 – Broadcast Trigger
3 – Action Trigger

• enc Encoding type to send SMS(Optional field)
Range: 0 to 3
0 – SMS text should be in ASCII form
1 – SMS text should be in Extended ASCII form
2 – SMS text should be in hexadecimal form (i.e. each hexadecimal value length
should be maximum 4 and each hexadecimal value should be separated by a semi-colon. Example: 0645;41;646)
3 – SMS text should be in decimal form (i.e. each decimal Value length should be maximum 5 and each decimal value should be separated by a semi-colon.
Example: 1605;65;65300) Note: Maximum decimal value allowed is 65535
If enc is not specified in the send API request, default enc will be the configured
settings in SMS settings page .
i.e. enc=2, if Unicode is enabled.
enc=1, if Extended ASCII is enabled.
enc=0, if both Extended ASCII and Unicode are disabled.

• priority Priority to send SMS (Optional field)
Range: 1 to 3
1 – Low Priority
2 – Normal Priority
3 – High Priority
If priority is not specified in the request, default priority is normal.

• modem Modem index to send SMS (this is only for the SF 400/800 models)
Range : 1 to 4 for SF 400
1 to 8 for SF 800

0 for any modem (Send API job will be distributed via all the available modems)
If modem is not specified in the request, send API job will be distributed via all the
available modems.
• to The mobile number where the SMS is to be delivered.
This number has to be given within double quotes. The maximum size of each
recipient’s number is 50 bytes.
• text The message text to be sent.
Enable Extended ASCII in the MultiModem iSMS to send both ASCII and extended ASCII characters. By default, Extended ASCII is disabled and the message could have only ASCII characters.
Notes: If Extended ASCII and Unicode are disabled and spanned SMS value is 1, a maximum of 160 characters can be sent.
If Extended ASCII is enabled and spanned SMS value is 1, a maximum of 140 characters can be sent.
If Unicode is enabled and spanned SMS value is 1, a maximum of 70 characters can be sent.
If the spanned SMS value is more than 1, the maximum number of characters allowed for each encoding scheme is defined as follows (where n represents the span value):
ASCII – n * 154 characters
Extended ASCII – n * 134 characters
Unicode – n * 64 characters
Any characters entered beyond the allowed limit will be chopped off.
In the HTTP API format example above: user1, puser1, 7657867765 and message are variables / configured parameters.

Sending to an Address Book Name

The API can be used to send the message to a name in the MultiModem iSMS address book. If the name does not exist in the address book, the message is dropped.

HTTP API format is:
http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&cat=1
[&enc=0][priority=3][&modem=2]&ton=”bob”&text=message

or

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&cat=1
[&enc=2][priority=3][&modem=2]&ton=”bob”&text=41;42;645;0645(hexadecimal form)

or

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&cat=1
[&enc=3][priority=3][&modem=2]&ton=”bob”&text=65;66;67(decimal form)

The parameters are:
• cat 1
• enc Encoding type to send SMS(Optional field)
Range: 0 to 3
0 – SMS text should be in ASCII form
1 – SMS text should be in Extended ASCII form
2 – SMS text should be in hexadecimal form (i.e. each hexadecimal value length
should be maximum 4, and each hexadecimal value should be separated by
a semi-colon. Example: 0645;41;646)
3 – SMS text should be entered in decimal form (i.e. each decimal Value length
should be maximum 5, and each decimal value should be separated by a
semi-colon. Example: 1605;65;65300)
Note: Maximum decimal value allowed is 65535.

If enc is not specified in the send API request, default enc will be the configured
settings in SMS settings page.
i.e. enc=2, if Unicode is enabled.
enc=1, if Extended ASCII is enabled.
enc=0, if both Extended ASCII and Unicode are disabled.

• Priority Priority to send SMS(Optional field)
Range: 1 to 3
1 – Low Priority
2 – Normal Priority
3 – High Priority
If priority is not specified in the request, the default priority is normal.

• modem Modem index to send SMS (this is only for the SF 400/800 models)
Range : 1 to 4 for SF 400
1 to 8 for SF 800
0 for any modem (Send API job will be distributed via all the available
modems)
If modem is not specified in the request, send API job will be distributed via all the
available modems
• ton The name in the address book where the SMS is to be delivered must be given within
double quotes. The maximum size of each recipient’s name is 50 bytes.
• text The message text to be sent.
Enable Extended ASCII in the MultiModem iSMS to send both ASCII and extended
ASCII characters. By default, Extended ASCII is disabled and the message can have only ASCII characters.
If Unicode is enabled(if enc is not specified in request), SMS text should be only in Hexadecimal form.
If Extended ASCII and Unicode are disabled and spanned SMS value is 1, a maximum of 160 characters can be sent.
If Extended ASCII is enabled and spanned SMS value is 1, a maximum of 140 characters can be sent.
If Unicode is enabled and spanned SMS value is 1, a maximum of 70 characters can be sent.
If the spanned SMS value is more than 1, the maximum number of characters allowed for each encoding scheme is defined as follows (where n represents the span value):
ASCII – n * 154 characters
Extended ASCII – n * 134 characters
Unicode – n * 64 characters
Any characters entered beyond the allowed limit will be chopped off.
Sending to a Group
The API can be used to send SMS to a pre-defined group. The group should exist in the MultiModem iSMS. If the group does not exist, the message is dropped.

HTTP API format is:

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&cat=1
[enc=1][priority=1][&modem=4]&group=”admin”&text=message


or

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&cat=1
[enc=2][priority=1][&modem=4]&group=”admin”&text=41;42;645;0645(hexadecimal form)

or

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&cat=1
[enc=3][priority=1][&modem=4]&group=”admin”&text=65;66;678(decimalform)

The parameters are:
• cat 1
• enc Encoding type to send SMS(Optional field)
Range: 0 to 3
0 – SMS text should be in ASCII form
1 – SMS text should be in Extended ASCII form
2 – SMS text should be in hexadecimal form (i.e. each hexadecimal value length
should be maximum 4, and each hexadecimal value should be separated by
a semi-colon. Example: 0645;41;646)
3 – SMS text should be in decimal form (i.e. each decimal Value length should
be maximum 5, and each decimal value should be separated by a semi-colon
Example: 1605;65;65300)
Note: Maximum decimal value allowed is 65535.
If enc is not specified in the send API request, default enc will be the configured settings from the SMS settings page.
i.e. enc=2, if Unicode is enabled.
enc=1, if Extended ASCII is enabled.
enc=0, if both Extended ASCII and Unicode are disabled.
• priority Priority to send SMS(Optional field)
Range: 1 to 3
1 – Low Priority
2 – Normal Priority
3 – High Priority

If priority is not specified in the request, the default priority is normal.

• modem Modem index to send SMS (this is only for the SF 400/800 models)
Range : 1 to 4 for SF 400
1 to 8 for SF 800
0 for any modem (Send API job will be distributed via all the available
modems)
If modem is not specified in the request, send API job will be distributed via all the
available modems.
• group The pre-defined group name(s) must be given within double quotes.
The maximum size of group name is 50 bytes.
• text The message text to be sent.
Enable Extended ASCII in the MultiModem iSMS to send both ASCII and extended ASCII characters. By default, Extended ASCII is disabled, and the message can have only ASCII characters.
If Unicode is enabled (and if enc is not specified in request), SMS text should only be in Hexadecimal form.
If Extended ASCII and Unicode are disabled and spanned SMS value is 1, a maximum of 160 characters can be sent.
If Extended ASCII is enabled and spanned SMS value is 1, a maximum of 140 characters can be sent.
If Unicode is enabled and spanned SMS value is 1, a maximum of 70 characters can be sent.
If the spanned SMS value is more than 1, the maximum number of characters allowed for each encoding scheme is defined as follows (where n represents the span value):
ASCII – n * 154 characters
Extended ASCII – n * 134 characters
Unicode – n * 64 characters
Any characters entered beyond the allowed limit will be chopped off.

Sending a Broadcast Trigger Message

We can use the API to send a broadcast trigger message to the MultiModem iSMS.

HTTP API format is:

http://192.168.2.1[:portnumber]/sendmsg?user=user2&passwd=user2&cat=2
[&enc=0][&modem=5]&text=message

or

http://192.168.2.1[:portnumber]/sendmsg?user=user2&passwd=user2&cat=2
[&enc=2][&modem=5]&text=message should be hexadecimal form

or

http://192.168.2.1[:portnumber]/sendmsg?user=user2&passwd=user2&cat=2
[&enc=3][&modem=5]&text=message should be decimal form

The parameters are:
• cat 2
• enc Encoding type to send SMS(Optional field)
Range: 0 to 3
0 – SMS text should be in ASCII form
1 – SMS text should be in Extended ASCII form
2 – SMS text should be in hexadecimal form (i.e. each hexadecimal value
length should be maximum 4, and each hexadecimal value should be
separated by a semi-colon. Example: 0645;41;646)
3 – SMS text should be in decimal form (i.e. each decimal Value length
should be maximum 5, and each decimal value should be separated by a
semi-colon. Example: 1605;65;65300)
Note: Maximum decimal value allowed is 65535.
If enc is not specified in the send API request, default enc will be configured to the settings of the SMS settings page.
i.e. enc=2, if Unicode is enabled.
enc=1, if Extended ASCII is enabled.
enc=0, if both Extended ASCII and Unicode are disabled.
• modem Modem index to send broadcast message
Range : 1 to 4 for SF400
1 to 8 for SF800
0 for any modem (Broadcast API job will be distributed via all the available modems)
If modem is not specified in the request, broadcast API job will be distributed via all the available modems
If modem is specified, broadcast job will be sent via the specified modem.

• text The trigger message text to be sent.
Enable Extended ASCII in the MultiModem iSMS to send both ASCII and extended ASCII characters.
By default, Extended ASCII is disabled, and the message can have only ASCII characters.
If Unicode is enabled (and if enc is not specified in request), SMS text should be only in Hexadecimal form.
If Extended ASCII is disabled, a maximum of 160 characters can be sent.
If Extended ASCII is enabled, a maximum of 140 characters can be sent.
If Unicode is enabled, a maximum of 70 characters can be sent.
Irrespective of the spanned SMS value set, the maximum number of characters allowed in the text field is:
160 for ASCII
140 for Extended ASCII
70 for Unicode
Any characters entered beyond the allowed limit will be chopped off.
The API can be used to send a trigger message to the MultiModem iSMS. If the MultiModem iSMS has a configured broadcast trigger, it will send the broadcast trigger message to the configured recipients.

Sending an Action Trigger Message

We could use this API to perform a predefined action.

HTTP API format is:

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&cat=3
[&enc=0]&text=message

or

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&cat=3
[&enc=2]&text=message should be hexadecimal form

Example: Configured action trigger for adding preconfigured SMS as 41;42;43 (with enc=2).
Preconfigured SMS to add is 645;646;647;648 (in hexadecimal form).
In an API request, the text field should be in the format:
Configured action trigger;Preconfigured SMS
text=41;42;43;;645;646;647;648 (not correct)
text=41;42;43;3a;645;646;647;648 (correct format)
Here 3a is equivalent hexadecimal value for a semi-colon. We should use equivalent
hexadecimal value for either semi-colon or colon.

or

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&
cat=3[&enc=3]&text=message should be decimal form.

Example: Configured action trigger for adding preconfigured SMS as 41;42;43(with enc=3).
Preconfigured SMS to add is 645;646;647;648 (in decimal form).
In an API request, the text field should be in the format:
Configured action trigger;Preconfigured SMS
text=41;42;43;;645;646;647;648 (not correct)
text=41;42;43;58;645;646;647;648 (correct format)
Here 58 is decimal equivalent value for a semi-colon. We should use equivalent decimal value for either semi-colon or colon.
Irrespective of the spanned SMS value set, the maximum number of characters allowed in the text field is:
160 for ASCII
140 for Extended ASCII
70 for Unicode

Any characters entered beyond the allowed limit will be chopped off.

Examples for action trigger with enc=2:
To Add an entry in the Address book:
Configured trigger: 41;42;43 (with enc=2)
Name: 61;62;63;64 (abcd)
Phone number: 39;38;38;36;30;39;38;38;36;30 (9886098860)

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&
cat=3[&enc=2]&text=41;42;43;3a;61;62;63;64;3a;39;38;38;36;30;39;38;38;36;30

Here 3a is the equivalent hexadecimal for semi-colon. Instead of 3a, we can use 3b (equivalent hexadecimal value for colon) also.

To Add a group name:

Configured trigger: 44;45;46 (with enc=2)
Group name: 65;66;67;68 (efgh)

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&
cat=3[&enc=2]&text=44;45;46;3b;65;66;67;68

To Add a group name with a member and phone number:
Configured trigger: 44;45;46 (with enc=2)
Group name: 65;66;67;68 (efgh)
Name: 61;62;63;64 (abcd)
Phone number: 39;38;38;36;30;39;38;38;36;30 (9886098860)

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&
cat=3[&enc=2]&text=44;45;46;3b;65;66;67;68;3b;61;62;63;64;3b;39;38;38;36;30;39;38;38;36;30

To Add a group name with a member (should exist in Address book):
Configured trigger: 44;45;46(with enc=2)
Group name: 65;66;67;68 (efgh)
Name: 61;62;63;64 (abcd)

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&
cat=3[&enc=2]&text=44;45;46;3b;65;66;67;68;3b;61;62;63;64

To delete an entry in the Address Book:
Configured trigger: 47;48;49(with enc=2)
Name: 61;62;63;64 (abcd)
Phone number: 39;38;38;36;30;39;38;38;36;30 (9886098860)
With Name and Number:

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&
cat=3[&enc=2]&text=47;48;49;3a;61;62;63;64;3a;39;38;38;36;30;39;38;38;36;30

With Name only:

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&
cat=3[&enc=2]&text=47;48;49;3a;61;62;63;64

With Number only:

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&
cat=3[&enc=2]&text=47;48;49;3a;3a;39;38;38;36;30;39;38;38;36;30

To Delete a Group:

Configured trigger: 4a;4b;4c (with enc=2)
Group name: 65;66;67;68 (efgh)

http://192.168.2.1[:portnumber]/sendmsg?user=user1&passwd=user1&
cat=3[&enc=2]&text=4a;4b;4c;3a;65;66;67;68

The parameters are:
• cat 3
• enc Encoding type to send SMS(Optional field)
Range: 0 to 3
0 – SMS text should be in ASCII form
1 – SMS text should be in Extended ASCII form
2 – SMS text should be in hexadecimal form (i.e. each hexadecimal value length
should be maximum 4, and each hexadecimal value should be separated by a
semi-colon. Example: 0645;41;646)
3 – SMS text should be in decimal form (i.e. each decimal Value length should be
maximum 5, and each decimal value should be separated by a semi-colon.
Example: 1605;65;65300). Note: Maximum decimal value allowed is 65535.
If enc is not specified in the send API request, default enc will be the configured settings in SMS settings page .
i.e. enc=2, if Unicode is enabled.
enc=1, if Extended ASCII is enabled.
enc=0, if both Extended ASCII and Unicode are disabled.

• Modem Modem index to send SMS
Range : 1 to 4 for SF400
1 to 8 for SF800
0 for any modem
Specifying modem for a cat=3 job is not applicable. Action trigger is executed even if modem is specified.
• text The trigger message text to be sent.
Enable Extended ASCII in the MultiModem iSMS to send both ASCII and extended ASCII chars.
By default, Extended ASCII is disabled, and the message can have only ASCII characters.
If Unicode is enabled(if enc is not specified in request), SMS text should be only in Hexadecimal form.
If Extended ASCII is disabled, a maximum of 160 characters can be sent.
If Extended ASCII is enabled, a maximum of 140 characters can be sent.
If Unicode is enabled, a maximum of 70 characters can be sent.
The API can be used to send an action trigger to the MultiModem iSMS. If the MultiModem iSMS has a configured action trigger, it will perform the configured action.
Sending to Multiple Numbers, Address Book Recipients or Groups
An SMS can be sent to multiple numbers, address book names and groups using a single API.

HTTP API format is:

http://192.168.2.1[:portnumber]/sendmsg?user=xxx&passwd=xxx&cat=1[&enc=0][&priority=1][&modem=8]&to=”xxx1”,”xxx2”,”xxx3”&ton=”name1”,”name
2”&group=”admin”,”rd”,”market”&text=message

xxx1, xxx2 and xxx3 are mobile numbers.
name1 and name2 are names in the Address Book.
admin, rd and market are groups present in the MultiModem iSMS.
Note: The to, ton and group parameters should be enclosed in quotes.
Response from the MultiModem iSMS after Submitting the Send SMS API
The MultiModem iSMS returns a unique identifier; i.e. an API message ID for each “Send API request”.
This ID can be used to track and monitor any given message.
ID: apimsgid
-or-
Err: error code
e.g.,
ID: 1
Err: 601