SOPRANO HTTP Interface Developer Guide 199 PDF

HTTP Interface Developer Guide
SOPRANO Mobile Enterprise Messaging Suite

HTTP Interface Developer Guide v199
© 2017 Soprano Design Limited

CONFIDENTIAL INFORMATION: Do not disclose

© 2017 Soprano Design Limited and Confidentiality Statement
All rights reserved Soprano Design Ltd. No parts of this work may be reproduced in any form or by any means -
graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval
systems - without the written permission of SOPRANO Design Ltd.
Products that are referred to in this document may be either trademarks and/or registered trademarks of the
respective owners.
While every precaution has been taken in the preparation of this document, the publisher and the author assume no
responsibility for errors or omissions, or for damages resulting from the use of information contained in this
document or from the use of programs and source code that may accompany it. In no event shall the publisher and
the author be liable for any loss of profit or any other commercial damage caused or alleged to have been caused
directly or indirectly by this document.
Printed: May 2017

Table of Contents
SOPRANO MEMS HTTP Interface Developers Guide 5
Interface Description 6
Getting Started with the HTTP Interface 7
Send SMS Messages 8
Request 8
Response 9
Commands 9
Send SMS Messages to Groups and Lists 22
Request 23
Response 23
Commands 23
Receive SMS Messages 29
Preferences 29
Request 30
Response 30
Commands 30
Receive SMS Delivery Reports Messages 32
Delivery Receipt Format 32
WAP Push 34
Request 34
Response 34
Commands 35
Query SMS Messages 38
Request 38
Response 38
Commands 39
Cancel SMS Messages 42
Request 42
Response 42
Commands 43
Appendices 45
Appendix A - API Capabilities 45
© 2017 Soprano Design Limited 3


Appendix B - Abbreviations 49
Appendix C - Response Details HTTP 49
Appendix D - DCS Parameter Details 53
Appendix E - Text & Data Parameter Restrictions 55
Appendix F - XML response DTD 56
Appendix G - Example Code 57
Appendix H - FAQ 59


Overview and Document Purpose

SOPRANO Mobile Enterprise Messaging Suite is an industry-leading mobile messaging application which facilitates
users in the sending and receiving of SMS, Premium SMS and WAP Push etc. mobile messages.
This document provides a technical overview of the HTTP for the SOPRANO Mobile Enterprise Messaging Suite
platform. For MMS information, please refer to or request a copy of separate HTTP MMS Interface Developers
Guide.
Intended Audience
This document is intended for SOPRANO MEMS customers interested in using SOPRANO MEMS’s HTTP interfaces
for sending SMS. A basic knowledge of the HTTP protocol is required as a minimum.

Interface Description
HTTP interface can be used to send or receive messages by sending HTTP POST requests or through URL (HTTP
GET). Only the GET method is used to deliver received messages.
It is recommended to use the 'POST' method when sending messages due to the URL length limitations and
restriction to the ASCII character-set if 'GET' method. However, examples throughout this document mainly use the
GET method for ease of understanding and demonstration.
A record of all messages sent via the HTTP POST interface is recorded in SOPRANO Mobile Enterprise Messaging
Suite and can be accessed via the web or other reporting interfaces.
We support both HTTP and HTTPS.

SOPRANO MEMS is HTTP version 1.1 compliant.
All requests are submitted through the HTTP POST or GET method using
UTF-8 encoding and URL encoded values.
The expected "Content-Type" for POST requests is "application/x-www-
form-urlencoded", however "multipart/form-data" if the message is MMS is
also supported.
All 'send' commands require authentication which is implemented via HTTP Basic Authentication – refer to
'References [6]') for any requests made. Since basic authentication is inherently insecure (e.g. username and
passwords sent as clear-text over the internet and therefore open to interception by a third party), an SSL secured
interface can be used.
Note: The default for all recipient and source numbers is valid international format (i.e. country code
followed by the number) without spaces and special characters such as '+'. For example: 61491234567.
Additional Information
HTTP URL depends upon the service that you will utilise.The following is a list of SOPRANO MEMS HTTP Interface
URLs :
Command URL
sendmsg https://apac.soprano.com.au/cgphttp/servlet/sendmsg
startbatch https://apac.soprano.com.au/cgphttp/servlet/startbatch
sendbatch https://apac.soprano.com.au/cgphttp/servlet/sendbatch
sendwappush https://apac.soprano.com.au/cgphttp/servlet/sendwappush
querymsg https://apac.soprano.com.au/cgphttp/servlet/querymsg
cancelmsg https://apac.soprano.com.au/cgphttp/servlet/cancelmsg

Interface Description

Getting Started with the HTTP Interface

The following is a quick guide to the simplest form of sending an SMS message with HTTP API Development.
Prerequisite
You must have requested the HTTP API to be provisioned when filling in the order form. If you wish to receive
messages in response to the messages you send through your API, then you need to explicitly request this on your
order form.
Step 1: Provision your HTTP API Access

Request HTTP API access to be provisioned for your account.
Please specify the 'Username' that will be used for HTTP API access.
If you wish to lock your HTTP API access down to originate from a particular host or set of hosts, please provide
this information when requesting HTTP API access.
Step 2: Test your Service Provisioning

Once your Service Support Team or Account Executive has confirmed that this has been provisioned for the
specified user, you can start using the service. The easiest way to test the service is with your browser.
Step 2.a: In your browser's address bar, type/paste the URL.
https://apac.soprano.com.au/cgphttp/servlet/sendmsg?destination=$mydestination&text=$text
Note:
$mydestination is the mobile number you want to send to in international format i.e. 61491234567
$text is the text that you wish to send.
Step 2.b: You will be prompted by your browser for your username and password. This should match the
username you provided at the time of provisioning.
Step 2.c: You should receive a confirmation in your browser window that the message was successfully sent,
and the message's Client Message ID, which can be used to interrogate the message status.
Step 3: Build your HTTP API Application

Various shell script examples include: Perl, wget, PHP. You may also refer to the code snippets: VB - Encoding
Authentication Strings.
Note: For receiving forwarded messages or responses from the source IP address, you need to white list the web-
server IP address. Below are the web-server IP addresses that may be added to the anti-spam filter white-list:
116.51.13.84, 116.51.13.85
58.65.27.52, 58.65.27.53

Getting Started with the HTTP Interface

Send SMS Messages

The HTTP interface can be used to send SMS messages. We support:
Delivery to one or more destination.

POST and GET methods - POST or GET requests are to be initiated by the customer, and a response is returned
from the SOPRANO MEMS to the customer.
Batch messaging - Allows the user to define a template containing elements common to the batch and send only
the parameters that change on a message-by-message basis.
Please note that all mobile numbers must be entered in international format when using the
APIs & interfaces.
Request
The request for message submission using the POST method conforms to the following structure:
POST apac.soprano.com.au/cgphttp/servlet/sendmsg HTTP/1.1

Authorization: Basic YWxpYXNAc29wcmFuby5jb20uYXU6cGFzc3dvcmQ=
HTTP/1.x 200 OK
Content-Type: application/x-www-form-urlencoded;charset=utf-8
Content-Length: 30
Date: Wed, 20 Aug 2008 07:14:32 GMT
destination=61491234568&text=initial+test+message
The above example displays a basic SMS request, where the customer’s username and password are provided
within the authorization header field.
The example is only valid when there is a pooled SMS source address defined to be used as a source address.
Users have the option to use a specific source address from the address list available for the user by adding 'source'
parameter to the request.
An example of message submission 'Request' using the GET method may look like:
https://apac.soprano.com.au/cgphttp/servlet/sendmsg?
Authentication
Access to the SOPRANO MEMS host requires authentication which is implemented via HTTP Basic Authentication.
You need to include the Base64 encoded value of username and password in 'Authorization' header of HTTP.
Format of the Authorization header:
Authorization: Basic {base64-encoded username:password}
The username and password are expected to be presented in the format username:password and encoded into
Base64. For example, the below header will present a username and password of user@url.com:Password1.
Authorization: Basic dXNlckB1cmwuY29tOlBhc3N3b3JkMQ==
Alternatively, if you do not wish to use the basic authentication method for your submission you may use the HTTP
parameters 'username' and 'password' to authenticate your request.

Send SMS Messages

username=demo@url.com.au&password=mypwd01&destination=61491234568&text=initia
l+test+message
Note: If you provide both username and password in the URL parameters AND in your basic authentication, the
URL parameters will be ignored and the basic authentication values will be used.
'sendmsg Commands section' describes the commands that can be used to submit messages to SOPRANO MEMS
and corresponding responses for the HTTP interface, and their corresponding parameters.
Response
The following is an example response for the example POST request above:
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=B76916114E6610F0E636EE355FE2B8B7; Path=/cgphttp
Content-Type: application/x-www-form-urlencoded;charset=utf-8
Content-Length: 30
Date: Wed, 13 Aug 2008 03:52:48 GMT
Status Line=HTTP/1.1 200 OK
0 001 OK
Message-ID: 7836
The body of all successfully received responses to message submission requests by SOPRANO MEMS will contain
a one digit success code (0 = success or 1 = error), a three digit response code , a response string and an
identifier for the message (which can be used when querying/canceling the message).
If the request could not be interpreted by SOPRANO MEMS (e.g. due to an unrecognised format, or missing
mandatory parameters), the response will contain a success code of 2 (indicating an error with the command), a
response code (refer to Table 2) and a response string (refer to Table 2) identifying the error. Example response:
HTTP/1.1 200 OK
Server: Apache/1.3
Date: Mon, 21 Jun 2004 09:15:23 GMT
Content-Type: text/plain
Content-Length: 9
2 001 ERROR - command not recognised
Note that the response contains text intended for use in automated applications.
Section Appendix C: Response Details describes the commands and corresponding responses for the HTTP
interface, and their corresponding parameters.
Commands
'Send SMS Message' commands include:
sendmsg
startbatch
sendbatch

Send SMS Messages

sendmsg
The sendmsg command is used to send an SMS message to one or more recipients.
Parameters Description Restricted Values

username Username for the customer. Provided in HTTP Username will be in email address
Authorization field. format.
Usually the username is the user email address.

This is a mandatory parameter.
Note: If programming within the Authorization header

field is not possible, you may submit the username &
password parameters inside the GET or POST request.
password Password for this user. Provided in HTTP Authorization
field.
Note: If programming within the Authorization header

password parameters inside the GET or POST request.
destination Destination or recipient number. Typically a valid ISDN 1 – 15 digits
number, but other numbers can be specified along with
the use of the destinationTON and destinationNPI
parameters. Messages can be sent to multiple recipients
by separating the numbers with commas.
Note: If you specify multiple destination addresses, you

will also have to supply the source address.
Note: There is a maximum number of destinations

supported in a HTTP sendmsg request of 300
destinations.
text Message content. Will only accept text data. Either the
text parameter or the data parameter may be used in a
single request – not both.
source Valid international format number or alphanumeric string 1 – 15 digits or 11 character
(corresponding to the sourceTON and sourceNPI alphanumeric string
parameters) representing the sender or message
source, e.g. 61491234567
Note: If you define the source address as a non-pool

address in the request, some of the message reply
features are disabled. This includes linking Client
Message ID of submitted message to the response i.e.
the replyTo and replyToTON address specified will be
ignored. The source address must be defined as a pool
address for tracking and reply functions.
registered Request a Delivery Receipt (DR) acknowledgment for 0 Off (default)
message. Returns msg_id, user and status to the 1 Send network DR only
customer via the specified channel for 2 Reserved for Error only DRs
acknowledgments.
3 Send intermediary DR only
4 Send both intermediary and
network DRs

Send SMS Messages


5 Reserved for Error only DRs
delay Delay delivery of SMS to recipient. If used, must be less Integer-relative delay (from message
than 'valid' value. submission time) in minutes (typically
greater than 10 for best effect)
valid The validity period of the message, after which time the Relative validity (from message
message will not be sent. submission time) in minutes (positive
integer greater than 0, default = 10080
[7 days])
priority Message priority, used for message routing. 1 (default)
If no priority is supplied, a default priority of 1 will be
used for the message.
replyTo For SMS replies. Maximum 250 characters.
Specifies the destination the reply goes to. This can be If not provided:
a valid MSISDN, email, URL, or a valid inbound order ID
etc. Default: Empty/null
Note 1: When using replyTo parameter it is mandatory

to also use the replyToTON parameter.
Note 2: If you use the 'source' parameter in the request

the reply address specified will be ignored.
replyToNPI Not used, reserved for future.
replyToTON For SMS replies. 0 INBOX (Default)
1 MOBILE
Type of Number to be used for reply address to indicate 8 EMAIL
if replyTo field is: INBOX, MOBILE, EMAIL, INBOUND,
URL. 10 URL
mmsReplyTo For MMS replies. Same as 'replyTo'. Same as replyTo
Applicable only if customer has two

addresses with the same value: 1 SMS
and 1 MMS.
mmsReplyToTON For MMS replies. Same as 'replyToTON'. Same as replyTo TON

and 1 MMS.
responseType Specifies the envelope type to be used to send HTTP 0 Text/plain (Default)
response 1 Text/XML
costCentre User cost centre label 100 characters maximum
clientMessageId User message reference which will be sent back with 100 characters maximum
reply messages
Note: if you define the source address in the request,

some of the message reply features are disabled.
Including linking Client Message ID of submitted
message to the response.
destinationNPI Numbering Plan Indicator for destination address(es). 0 Unknown
1 ISDN (E.163/E.164) (default)
3 Data (X.121)
4 Telex (F.69)
6 Land Mobile (E.212)
8 National
9 Private

Send SMS Messages


10 ERMES
14 Internet (IP)
18 WAP Client ID
destinationTON Type of Number to be used for destination address(es). 0 Unknown
1 International (default)
2 National
3 Network Specific
4 Subscriber Number
5 Alphanumeric
6 Abbreviated
sourceNPI Numbering Plan Indicator for the source address. 0 Unknown
1 ISDN (E.163/E.164) (default)
3 Data (X.121)
4 Telex (F.69)
8 National
9 Private
10 ERMES
14 Internet (IP)
18 WAP Client ID
sourceTON Type of Number to be used for the source address. 0 Unknown
2 National
3 Network Specific
4 Subscriber Number
5 Alphanumeric
6 Abbreviated
data Message content (hexadecimal encoding). The data 160 characters or 140 bytes maximum
parameter is used to send Nokia Ringtones, Nokia
Operator Logos, Nokia Picture Messages, Nokia Group
Logos or raw binary data (as indicated by the
content_type parameter or the presence of the udh
parameter).
Either the text parameter or the data parameter may be

used in a single request – not both. If binary data is
used, dcs has to be provided and must be set to 2 or 4.
dcs Indicates the Data Coding Scheme for the SMS 0 SOPRANO MEMS will
determine the coding scheme
dcs must be provided if a data value is provided. based on provided content.
If no special characters (e.g.
For text, the only accepted dcs values are: 0, 8, 16 UCS2) are found then the
value 1 is used. (160
For data, the only accepted dcs values are: 0, 2, 4, 8 characters per message)
2 Octet unspecified (8-bit
For NOKIA_RINGTONE, NOKIA_OPERATOR_LOGO, binary), (140 characters per
NOKIA_PICTURE_MESSAGE, NOKIA_GROUP_LOGO message)
use dcs values: 2, 4 4 Octet unspecified (8-bit
binary), (140 characters per
For RAW_BINARY_DATA use dcs values: 0, 2, 4 message)
Note, DCS = 16,20,24 represent flash type messages. 8 UCS2 (ISO/IEC-10646), (70
characters per message)

Send SMS Messages


16 Flash Message, Standard
GSM 7 bit Alphabet. (160
20 Flash Message, Octet
unspecified (8-bit binary),
(140 characters per
message)
24 Flash Message, UCS2 (ISO/
IEC-10646), (70 characters
per message)
content_type Specifies the type of content in the text or data 1 Plain text (default)
parameter. 2 Nokia Ringtone
3 Nokia Operator Logo
This parameter is mainly used to indicate use of binary
messages like logos and ringtones. 4 Nokia Picture Message
Either the content_type parameter or udh parameter 5 Nokia Group Logo
must be used when the data parameter is used. If the 6 Business Card (vCard) - Not
content_type parameter is not included when the text currently supported
parameter is used, the text parameter is assumed to 7 Calendar Event (vCalendar)
contain plain text (URL encoded). - Not currently supported
8 Raw Binary Data (data
includes UDH)
udh Contains the UDH (hexadecimal encoding) for the data The udh parameter should be less than
contained in the data parameter. 139 bytes if it is to be delivered as a
Either the content_type parameter or udh parameter single SMS (refer to Appendix D for
must be used when the data parameter is used. more details)
Example: Send to Single Destination

Request:
http://apac.soprano.com.au/cgphttp/servlet/sendmsg?
destination=61491234568&text=initial+test+message&source=61498765432
For the above example, the mentioned source address has to be a valid address. The purpose is to force messages
to be sent from a specific source address rather using a pooled source address.
Alternatively, if you do not specify a source address, the system will automatically allocate one from a configurable
pool of source addresses.
Request ('source' parameter absent):
http://apac.soprano.com.au/cgphttp/servlet/sendmsg?
Using the above example sends the message using one of the pooled source addresses.
Response:
0 001 OK
Message-ID: 12300012

Send SMS Messages

Example: Send a Message to a Single Destination and Request XML Response

Request:
destination=61491234568&text=initial+test
+message&source=<61491234568&responseType=1
Response:
<response>
<message>
<success_code>0</success_code>
<response_code>001</response_code>
<response_string>OK</response_string>
<message_id>1167</message_id>
</message>
</response>
Example: Send a Message to a Single Destination with Error

Request:
destination=61491234568&text=initial+test+message&source=61498765432
Response:
1 031 ERROR - internal CGP failure
This error is returned if the service is not activated.
Example: Send a Message to Multiple Destinations

When sending a message to multiple addresses a valid 'source address' has to be provided. The requirement for
'source address' is to be able to handle and process incoming 'reply' messages on this source address.
Request:
destination=61491234568,61498765432,61491234567&text=initial+test
+message&source=61403020000
Response:
0 001 OK

Send SMS Messages

Example: Send a Message to Multiple Destinations with Single Destination Error

When an error has occurred in relation to one particular recipient/destination, all destinations in the request and
their corresponding status will be reported. Since messages can be sent to multiple destinations within the one HTTP
request, it could be possible for one destination to fail and others to succeed.
Request (TEXT):
destination=61491234568,61498765432,000024,095123&text=initial+test
+message&source=61403020000
Response (TEXT):
1 040 ERROR
61491234568 001
61498765432 001
000024 101
095123 101
Request (XML response specified):
destination=61491234568,61498765432,000024,095123&text=initial+test
+message&source=61491234567&responseType=1
Response (XML):
<response>
<message>
<response_string>ERROR
61491234568 001
61498765432 001
000024 101
095123 101
</response_string>
</message>
</response>
See Appendix C (Table 2) for a list of full Destination Status Codes.
Example: Send a Message to Multiple Destinations with Registered Flag

Request:
destination=61491234568,61498765432&text=initial+test
+message&source=61491234567&registered=1

Send SMS Messages

Response:
0 001 OK
Message-ID: 1001
Example: Send an SMS with Registered Delivery - Reply to Email
destination=61498765432&text=hello13&dcs=8&replyToTON=8&replyTo=demo@url.com
.au&replytoton=8&registered=1
Turn handset off. Once the message has expired, the SMSC platform will forward the delivery receipt to the reply
address, in this case an email address (into email client).
source=61491234568
destination=61498765432
clientMessageId=
text=id:4988312 sub:001 dlvrd:001 submit date:1005251604 done date:1005251609 stat:EXPIRED err:000 text:No
Text
startbatch
The 'startbatch' command is used to initiate batch messaging. It defines the common elements for a batch of
messages, including a message template containing customised fields (customised fields should be referred to within
the message template as field1 through to fieldN). The ID returned in response to a startbatch request must be used
in sendbatch requests to link data with a message template.

username Username for the customer. Provided in HTTP Authorization Username will be in email address
field. format.
(Note: If programming within the Authorization header field

is not possible, you may submit the username & password
parameters inside the GET or POST request.)
password Password for this user. Provided in HTTP Authorization
field.
(Note: If programming within the Authorization header field

is not possible, you may submit the username & password
parameters inside the GET or POST request.)
template Message template, including optional personalised fields
(field2 to fieldN) surrounded by ^ symbols (e.g. Hi ^field2^,
your appointment is at ^field3^ tomorrow).
Note: Field1 is used for the recipient’s mobile phone

number and is typically not included in the message
template. Hence the first field should be identified with
field2, with consecutive field numbers incremented by 1
identifying them.
delimiter Allows customisation of the delimiter. , (default)
Typically, a single character such as ‘,’, ‘.’, ‘|’ or ‘;’. Care

should be taken not to use characters such as ‘#’, ‘ ’, ‘%’ or

Send SMS Messages


‘&’ that have existing meanings within a URL.
source Valid international format number or alphanumeric string 1 – 15 digits or 11 character
(corresponding to the sourceTON and sourceNPI alphanumeric string
parameters) representing the sender or message source.
Note: If you define the source address as a non-pool

address in the request, some of the message reply features
are disabled. This includes linking Client Message ID of
submitted message to the response i.e. the replyTo and
replyToTON address specified will be ignored. The source
address must be defined as a pool address for tracking and
reply functions.
registered Request a delivery receipt (DR) acknowledgment for 0 Off (default)
message. Returns msgid, user and status to the customer 1 Send network DR only
via the specified channel for acknowledgments. 2 Reserved for Error only
DRs
3 Send intermediary DR
only
4 Send both intermediary
and network DRs
5 Reserved for Error only
DRs
delay Delay delivery of SMS to recipient. Integer-relative delay (from
message submission time) in
minutes (typically greater than 10
for best effect)
valid The validity period of the message, after which time the Relative validity (from message
message will not be sent. submission time) in minutes
(positive integer greater than 0,
default = 10080 (7 days))
priority Message priority, used for message routing. 1 (default)
If no priority is supplied, a default priority of 1 will be used

for the message.
sourceNPI Numbering Plan Indicator for the source address. 0 Unknown
1 ISDN (E.163/E.164)
(default)
3 Data (X.121)
4 Telex (F.69)
8 National
9 Private
10 ERMES
14 Internet (IP)
18 WAP Client ID
sourceTON Type of Number to be used for the source address. 0 Unknown
2 National
3 Network Specific
4 Subscriber Number
5 Alphanumeric
6 Abbreviated
destinationNPI Numbering Plan Indicator for destination address(es). 0 Unknown

Send SMS Messages


1 ISDN (E.163/E.164)
(default)
3 Data (X.121)
4 Telex (F.69)
8 National
9 Private
10 ERMES
14 Internet (IP)
18 WAP Client ID
destinationTON Type of Number to be used for destination address(es) 0 Unknown
2 National
3 Network Specific
4 Subscriber Number
5 Alphanumeric
6 Abbreviated
dcs Indicates the Data Coding Scheme for the SMS. 0 SOPRANO MEMS will
determine the coding
dcs must be provided if a data value is provided. scheme based on
provided content. If no
For text, the only accepted dcs values are: 0, 8, 16, 20, 24. special characters (e.g.
UCS2) are found then the
Note, DCS = 16,20,24 represent flash type messages. value 1 is used. (160
binary), (140 characters
per message)
binary), (140 characters
per message)
8 UCS2 (ISO/IEC-10646),
(70 characters per
message)
16 Flash Message, Standard
GSM 7 bit Alphabet. (160
20 Flash Message, Octet
unspecified (8-bit binary),
(140 characters per
message)
24 Flash Message, UCS2

(ISO/IEC-10646), (70
responseType Specifies the envelope type to be used to send HTTP 0 Text/plain (default)
response 1 Text/XML
The identifier returned from this command must be used when sending subsequent messages via the sendbatch
command.
The batch ID is valid for a period of 24 hours after it was generated, and is not persistent in the unlikely event of
SOPRANO MEMS failing (and having to be restarted). If this event does occur, the message template needs to be
re-established by re-issuing startbatch and sendbatch commands.

Send SMS Messages

Example: Initiate a Message Batch

Request:
https://apac.soprano.com.au/cgphttp/servlet/startbatch?template=Hi+^field2^,
+your+balance+is+^field3^
Response:
0 002 OK
Batch-ID: 241
Example: Initiate a Message Batch and Request XML Response

Request:
https://apac.soprano.com.au/cgphttp/servlet/startbatch?template=Hi+^field1^,
+your+balance+is+^field2^&responseType=1
Response:
<response>
<message>
<batch_id>1209139371</batch_id>
</message>
</response>
sendbatch
The sendbatch command is used to deliver the content for individual messages for a particular batch.

username Username for the customer. Provided in HTTP Username will be in email address format.
Authorization field.
(Note: If programming within the Authorization header

password parameters inside the GET or POST
request.)
password Password for this user.
Provided in HTTP Authorization field.
(Note: If programming within the Authorization header

password parameters inside the GET or POST
request.)

Send SMS Messages


batch_id Batch identifier returned from startbatch command.
content Contains the data to be inserted into the template with
x delimiterval x delimiterval etc. where x
each parameter separated by the delimiter value. denotes a data element. The destination
Each content refers to a single message being address must be the first data element of
generated from a template, defined by batch_id the content value and conform to the
format specified by the destinationTON
and destinationNPI parameters.
responseType Specifies the envelope type to be used to send HTTP 0 Text/plain (default)
response 1 Text&content=61491234568,Joh
n,100&content=61491234567,M
ark,50&content=61498765432,
Paul,120t/XML
mmsReplyTo For MMS replies. Same as sendmsg 'replyTo'. Same as sendmsg 'replyTo'.

and 1 MMS.
mmsReplyToTON For MMS replies. Same as sendmsg 'replyToTON'. Same as sendmsg 'replyToTON'.

and 1 MMS.
Note: This command contains no optional parameters.
Each content parameter represents a single message and a msg_id is returned for each content parameter in the
sendbatch command.
Batch_ids are only relevant for a period of 24 hours after they were created, and are not persistent in the unlikely
event of the SOPRANO MEMS failing (and having to be restarted). If this event does occur, the message template
needs to be re-established by re-issuing startbatch and sendbatch commands.
Batches may only be used by the user who established them (by virtue of the previous statement, batches started by
one customer may only be used by that customer).
Example: Send Batch Messages

Request:
https://apac.soprano.com.au/cgphttp/servlet/sendbatch?
batch_id=241&content=61491234568,Joe,250&content=61498765432,Jane,100
Response:
0 001 OK
61491234568 003
0 001 OK
61498765432 003

Send SMS Messages

Example: Send Batch Messages and Request XML Response (Invalid Content Value)
Request:
https://apac.soprano.com.au/cgphttp/sendbatch?
batch_id=61491234567&content=61491234568Joe,250&content=61498765432,Jane&res
ponseType=1
Response:
<response>
<message>
<response_string>ERROR</response_string>
<message_id/>
<destination>61491234568</destination>
<destination_code>108</destination_code>
<destination_description>PARAMS_FOR_TEMPLATE_NOT_MATCHED</
destination_description>
</message>
</response>
Care must be taken to ensure that the content values match with the corresponding numbered template fields.
Always check the destination value to determine whether there are any failed messages.
Example: Send Batch Messages (Error with batch_id)

Request:
https://apac.soprano.com.au/cgphttp/servlet/sendbatch?
batch_id=24&content=61491234568,John100&content=61498765432,Mark,50&content=
61491234567,Paul,120
Response:
1 002 ERROR – batch_id not found

Batch-ID: 24
Example: Send Batch Messages (Error with a Destination)

In case of an invalid destination value, the entire operation will fail, no messages will be sent.
Request:
http://apac.soprano.com.au/cgphttp/sendbatch?
batch_id=241&content=61498765432,John,100&content=61491234568,Mark,50&conten
t=61491234567,Paul,120
Response:
2 017 ERROR - content

Send SMS Messages

Send SMS Messages to Groups and Lists

The HTTP interface may be used to send SMS messages to existing groups and lists in your SOPRANO MEMS
address book.
Supported methods:
POST and GET ('POST' recommended)
HTTP and HTTPS
The POST or GET requests are to be initiated by the customer, and a response is returned from the SOPRANO
MEMS to the customer.
The unique ID of the destination Group or List is required. This can be found by logging into SOPRANO MEMS web
portal and viewing the relevant item in the 'Address Book' section.
Go to the 'Summary' page and click the required Group or List name.
Example: Find a List ID

There are 2 ways to open the 'List Summary' screen:
1. Click 'Show all lists' or 'Show personal lists' in 'Address Book' drop-down menu (top of the web interface).
2. Click 'Show Lists' under 'Contacts/Groups/Lists' in 'Personal Setup' menu (left-hand side).
The 'List Summary' will be displayed. You can filter the results if you know any details, or click a List name in the
table.
The 'List Details' page will be displayed. You can find the List ID here.
To find a Group ID, go to 'Groups' section of your address book and follow the same procedure.


Request
Message submission using the POST method conforms to the following structure:
Request:
POST /sms/sms_standard_orderApiCreate.do HTTP/1.1

Authorization = Basic ZXNtZTFAd2NhcDEuc29wcmFuby5jb20uYXU6c29wcmFubw==
User-Agent = Jakarta Commons-HttpClient/3.1
Host = apac.soprano.com.au
Content-Length: 105
Content-Type: application/x-www-form-urlencoded
subAction=20&customMessage=test&orderDestLists=1489
The above example shows an SMS request where the destination is is a list. The destination list is determined by its
unique ID in the platform (1489 in above example).
Developers can send 1 request to multiple groups, multiple lists, or a combination of multiple groups and lists in the
same request.
To include multiple lists/groups, every item will need to be provided as a separate 'orderDestLists' or
'orderDestGroups' parameter in the request.
Response
Sample OK response:
{"ApiResponse":
{"StatusCode":1000,"TransactionId":"","Operation":"apiCreate",
"RecordId":6127,"ResponseTime":"2014-02-27T09:44:25
+08:00","StatusText":"Success"
,"RequestTime":"2014-02-27T09:44:25+08:00","Object":"SMSStandardOrderBean"}}
Commands
The following is a list of all parameters that may be included in the request.
Parameters Description Optional/ Restricted Values Example

Mandatory
username Username used to log Mandatory Must be a valid email address. username=johnsmith@apac.
in to SOPRANO MEMS soprano.com.au
platform. This can be provided in request
header via basic authentication,
or as a parameter within the
request.
password Unique login Mandatory Password used to log in to password=a1b2c3d4e
password. SOPRANO MEMS platform.
This can be provided This can be provided in request

in request header via header via basic authentication,
basic authentication, or as a parameter within the
or as a parameter request.
within the request.
subAction Specify an operation Mandatory For sending Group/List subAction=20



Mandatory
to perform. messages, subAction value
must always be '20'.
Any other value will cause

message delivery to fail.
customMessage Message text content. Optional Mail merge variables are customMessage=Hello
supported. world
orderDestLists The destination List Optional (at Numeric. orderDestLists=1489

ID. least 1 of
'orderDestLi Must be a personal list If sending to List 'A', which
sts' or belonging to the user or a contains 7000 destinations,
'orderDestG shared list belonging to the and Group 'B', which
roups' parent customer. contains 5000 destinations,
required the interface will send to all
Maximum destinations: 10,000 7000 list destinations, and
(total including combination of the first 3000 group
groups and lists). contacts (beginning with
the oldest).
Where groups and lists are
included, data will be processed
in the following order:
1. Lists (in the order that IDs
are included in request;
oldest-newest data in each
list)
2. Groups (oldest-newest data
in each group)
orderDestGroups The destination Group Optional (at Numeric. orderDestGroups=1578
ID. least 1 of
'orderDestLi Must be a personal list
sts' or belonging to the user or a If sending to List 'A', which
'orderDestG shared list belonging to the contains 7000 destinations,
roups' parent customer. and Group 'B', which
required contains 5000 destinations,
Maximum destinations: 10,000 the interface will send to all
(total including combination of 7000 list destinations, and
groups and lists). the first 3000 group
contacts (beginning with
If sending to a combination of the oldest).
groups and lists, lists will be
processed first.
Where groups and lists are

included, data will be processed
in the following order:
1. Lists (in the order they are

provided; oldest-newest data
in each list)
2. Groups (in the order that IDs
are included in request;
oldest-newest data in each
list)
smsReplyToAddr The type of destination Optional INBOX=0 (Default) smsReplyToAddressTON=0
essTON which will receive MOBILE=1
message replies. EMAIL=8
URL=10



Mandatory
smsReplyToAddr The destination Optional The destination format must If: smsReplyToAddressTON=1
ess address for message (required if match the then:
replies. 'smsReplyTo 'smsReplyToAddressTON' smsReplyToAddress=614912
AddressTO value, if selected. 34567
N' is
specified) Valid: If: smsReplyToAddressTON=8
Mobile number (international then:
smsReplyToAddress=john.s
format) mith@company.com
or
Email address If:
or smsReplyToAddressTON=10
URL then:
smsReplyToAddress=http:/
/url.com
registeredDeliver Triggers a delivery Optional Off (default)=0 registeredDelivery=1
y receipt for every Send network DR only=1
message delivered (if Reserved for Error only DRs=2
the network supports Send intermediary DR only=3
delivery receipts) Send both intermediary and
network DRs=4
Reserved for Error only DRs=5
customMessage - Use mail merge to create message content

Lists
Each comma-separated item in each list row can be represented by a digit enclosed by 'curly-bracket' symbols.
e.g. if list row is:

61491234567,John,Smith
then:
61491234567={1}
John={2}
Smith={3}
Therefore, the following parameter:

customMessage=Hi {2} {3} this is your life
would deliver the message:

'Hello John Smith this is your life'
Groups
A Group is a set of Contacts. Each Group Contact has a number of details associated with it that can be
represented by text variables, which can be included in the 'messageContent' parameter.
Example Contact Details screen:


The following fields have corresponding text variables:

First Name $first
Last Name $last
Phone $phone
Mobile $mobile
Email $email
Fax $fax
Address $address ('Address Information' tab)
City $city ('Address Information' tab)
Country $country ('Address Information' tab)
Zip/Postal $postcode ('Address Information' tab)
Code
Therefore, the following parameter:

customMessage=Hi $first $last this is your life
would deliver the message:

'Hello John Smith this is your life'
Example: Send Message to a List

Request

Content-Length: 105
subAction=20&customMessage=test&orderDestLists=1489
Response
{"ApiResponse":
Example: Send Message to a Group

Request

Content-Length: 105
subAction=20&customMessage=test&orderDestGroups=1025


Response
{"ApiResponse":
Example: Send a Message to Multiple Lists

Request

Content-Length: 105
subAction=20&customMessage=test&orderDestLists=1561&orderDestLists=1234
Response
{"ApiResponse":
Example: Send Message to Multiple Groups

Request

Content-Length: 105
subAction=20&customMessage=test&orderDestGroups=1025&orderDestGroups=1132
Response
{"ApiResponse":


Example: Send a Message to a List and a Group

Request

Content-Length: 105
subAction=20&customMessage=test&orderDestGroups=1423&orderDestLists=1114
Response
{"ApiResponse":
Example: Error Response

The below example shows a request where neither 'orderDestGroups' or 'orderDestLists' parameters have been
provided.
Request

Content-Length: 105
subAction=20&customMessage=test
Example error response to the above is as follows:
Response
{"ApiResponse":{"StatusCode":2000,"TransactionId":"","Data":"Valid
destination,
and\/or orderDestLists (list id) and\/or orderDestGroups (group id) and\/or
orderDestContacts (contact id) must be provided","Operation":"apiCreate",
"ResponseTime":"2014-02-27T10:21:51+08:00","StatusText":"Client
error","RequestTime":
"2014-02-27T10:21:44+08:00","Object":"SMSStandardOrderBean"}}
The same response would be returned for a request where 'orderDestGroups' or 'orderDestLists' were provided, but
paired with an invalid Group or List ID.


Receive SMS Messages

SMS messages originating from a mobile device can be delivered to a customer via SOPRANO MEMS using the
HTTP GET or POST interface, provided they have configured the their account on SOPRANO MEMS to forward
incoming messages to URL.
In this instance, the GET or POST operation is initiated by SOPRANO MEMS, and the response should be returned
by the customer. Typically, customer(s) will handle the incoming HTTP requests (SMS messages are processed by
SOPRANO MEMS and the parameters of this SMS are forwarded to customer's web application) using a web-
application running on a web server.
Please note that all mobile addresses are forwarded in

international format.
The incoming POST or GET request will use UTF-8 encoding.
Retry on Forward to URL

There is a retry schedule for forwarding a Mobile Originated SMS Message to a URL via the API if the targeted web
server does not respond.
The retry occurs every 20 minutes for 24 hours.
Note: If you are using an Inbound Campaign to forward messages to a URL, no retry attempts will be made.
Preferences
To set the interface as either HTTP POST or GET, log into the SOPRANO MEMS portal as a Customer Administrator
and go to the 'Company Setup' Section.
Setup > Company Setup > Customer Information > SMS Preference
In the MO Delivery settings, there is an option to set the HTTP Method.
MO Delivery Settings Options for HTTP Method:

POST
GET
Note: For POST responses the default character set encoding is UTF-8.
The option in this section 'Use Plain Text Email' refers to 'Forward to Email' and is unrelated to the HTTP interface.


Request
Example 1 (HTTP GET): When receiving a mobile-originated message, SOPRANO MEMS will submit a HTTP GET
Request to the customer's nominated URL (e.g. http://CUSTOMER_HOST_URL:PORT):
https://yoururl.com/yourapplication?destination=61491234568&text=Hello+
World&source=213123&networkSubmitTime=2011-11-16+10%3A26%
3A13&clientSubmitTime=2011-11-16+10%3A26%3A13
Example 2 (HTTP GET): including legacy fields, from and to which should no longer be used by the application as
from equals source and to equals destination.
https://yoururl.com/yourapplication?
destination=61491234568&clientMessageId=10332&source=61498765432&text=Hello
+World&from=61498765432&to=61491234568&networkSubmitTime=2011-11-16+10%3A26%
3A13&clientSubmitTime=2011-11-16+10%3A26%3A13
Note - New fields may be added, without notice, to the request parameters. Your interface should be developed by
extracting only the required fields, rather than raising an exception if an unsupported field is received.
Response
SOPRANO MEMS expects the customer’s server to reply with a HTTP status code of 200 (OK) if the SMS message
was successfully received. Any other status value will result in failure to deliver the message and the delivery of the
message to the nominated URL will not be re-attempted.
A sample successful response from the customer would be:
HTTP/1.1 200 OK
Server: Apache/1.3
The response should be as minimal as possible and not contain any body.
Commands
The following is a list of all parameters that will be included in the HTTP GET Request to the customer's nominated
URL.

source Valid international format number representing the 1 – 15 digits
sender address.
This is the mobile number the message was sent

from.
destination Valid international format number representing the 1 – 15 digits
recipient address.
This is the number the sender sent the message to.

text Message content. Will only accept text data. To
send binary, use the data parameter instead.



Either the text parameter or the data parameter may
be used in a single request – not both.
clientMessageId User message reference. 100 characters maximum
This parameter will be set if the incoming message

was a reply to an outgoing message tagged with a
clientMessageId value.
clientSubmitTime The time that the Inbound application handed the Format: YYYY-MM-DD+HH:MM:SS
message and forwarded it on to the provisioned
URL. Example: Encoded 2011-11-16+10%
3A26%3A13 is equivalent to the
decoded string 2011-11-16 10:26:13
costCentre User cost centre label. 100 characters maximum
Only set if the user is allocated a cost centre label.

messageId The MO (Mobile Originated) message ID.
networkSubmitTime The time when the SOPRANO MEMS Platform Format: YYYY-MM-DD+HH:MM:SS
received the message from the network element
(typically the SMSC). Example: Encoded 2011-11-16+10%
3A26%3A13 is equivalent to the
decoded string 2011-11-16 10:26:13
segmentCount The total number of concatenated messages (Part x 1 – 2 digits
of y) that make up 1 long SMS message.
Note: When using the Inbound
application, forwarding to the URL
using the HTTP API does not use this
parameter for long messages.
segmentNumber The segment number of this concatenated message 1 – 2 digits
in a list of messages (Part x of y) that make up 1
long SMS message. Note: When using the Inbound
application, forwarding to the URL
using the HTTP API does not use this
referenceNumber A common identified for the multiple segmented 1 – 3 digits
messages of a long SMS message.
Note: When using the Inbound
Each segment of a long SMS message will all have application, forwarding to the URL
the same reference number. using the HTTP API does not use this
to Same as 'destination' field.
DO NOT USE this parameter.
This is provided for backward compatibility to an

older version of this interface. The use of this
parameter will be phased out in future versions of
this interface.
from Same as 'source' field.
DO NOT USE this parameter.
This is provided for backward compatibility to an

older version of this interface. The use of this
parameter will be phased out in future versions of
this interface.


Receive SMS Delivery Reports Messages

When sending an SMS message to a mobile you can request acknowledgment of when the handset received the
message (DELIVERED) or when it has expired from the network without being sent (EXPIRED).
This is known as a Delivery Report / Delivery Receipt.
Figure: Flow from the platform delivering a message to when a delivery receipt is provided back to the platform
The format of the text that you will receive in the Delivery Report / Receipt message follows that defined in the open
SMPP Specification version 3.4. Available for download from: http://soprano.com.au/wp-content/uploads/2013/10/
SMPP_v3_4_Issue1_2.pdf
Delivery Receipt Format

The format of the delivery receipt that you will receive can be seen in the following example:
Normal Delivery Receipt Message Text:

id:10127438101647284 sub:001 dlvrd:001 submit date:1005260205 done
date:1005260206 stat:DELIVRD err:000 text:ext:JZ TEST REGISTER
The following is extracted directly from the SMPP specification to assist you with the interpretation of the fields
provided.
The fields of the above delivery receipt example are explained in the following table:
Field Size Type Type Description

(Octets)
id 10 C-Octet The message ID allocated to the message by the SMSC when
String originally submitted.
(Decimal)
sub 3 C-Octet Number of short messages originally submitted. This is only
String relevant when the original message was submitted to a
(Decimal) distribution list. The value is padded with leading zeros if
necessary.
dlvrd 3 C-Octet Fixed Number of short messages delivered. This is only relevant
Length String where the original message was submitted to a distribution list.
(Decimal) The value is padded with leading zeros if necessary.
submit date 10 C-Octet Fixed The time and date at which the short message was submitted.
Length String In the case of a message which has been replaced, this is the


Field Size Type Type Description

(Octets)
date that the original message was replaced. The format is as
follows:
YYMMDDhhmm where:
YY = last two digits of the year (00-99)
MM = month (01-12)
DD = day (01-31)
hh = hour (00-23)
mm = minute (00-59
done date 10 C-Octet Fixed The time and date at which the short message reached its
Length String final state. The format is the same used for the submit date.
stat 7 C-Octet Fixed The final status of the message.
Length String For settings for this field see the table below.
err 3 C-Octet Fixed Where appropriate, this may hold a network-specific error
Length String code or an SMSC error code for the attempted delivery of the
message.
These errors are Network or SMSC specific

text 20 Octet String The first 20 characters of the short message.
The following table describes the states that may be received from the network upon delivering a message.
Message StateFinal Description

Message
State
DELIVERED DELIVRD Message is delivered to destination.
EXPIRED EXPIRED Message validity period has expired.
DELETED DELETED Message has been deleted.
UNDELIVERABL UNDELIV Message is undeliverable.
E
ACCEPTED ACCEPTD Message is in accepted state (i.e. has been manually read on behalf of the
subscriber by customer service).
UNKNOWN UNKNOWN Message is in invalid state.
REJECTED REJECTD Message is in a rejected state.


WAP Push
The HTTP POST interface can be used to send WAP Push messages to a recipient’s handset.
Request
Response
Commands
Request
A valid submission of a WAP Push request may look like:
POST /sendwappush HTTP 1.1

Host: xxx.xxxx.xxxx
Content-type: application/x-www-form-urlencoded; charset=utf-8
Content-length: 166
http://apac.soprano.com.au/cgphttp/servlet/sendwappush?
source=61491234567&destination=61491234568,61498765432&priority=1&message=Pl
ease+click+on+the+link+to+authorise+your+transaction&url=wap.blah.com/
wap&https=true
Where the customer’s username and password are provided within the Authorization header field. Refer to Section
2.1.1 for more details on the Authorization field.
Alternatively, if you do not wish to use the Basic Authentication method for your submission you may use the HTTP
username=demo@url.com.au&password=mypwd01&destination=61491234568&text=initi
al+test+message
If you provide both username and password in parameters AND in your Basic Authentication, the parameters will be
ignored and the Basic Authentication values will be used.
Response
The following response is an example response to the request above:
HTTP/1.1 200 OK
Server: Apache/1.3
Date: Mon, 05 Sep 2008 04:42:31 GMT
Content-Length: 30
0 001 OK
The body of all responses to WAP Push requests will contain a one digit success code (0 = success or 1 = error), a
three digit response code (refer to Table 2), a response string (refer to Table 2) and an identifier for the message.
If the request could not be interpreted (due to for example an unrecognised format, or the request lacking mandatory
parameters), the response will contain a success code of 2 (indicating an error with the command), a response
code (refer to Table 2) and a response string (refer to Table 2) identifying the error.

WAP Push

Example:
HTTP/1.1 200 OK
Server: Apache/1.3
Date: Mon, 21 Jun 2008 09:15:23 GMT
Content-Length: 9

2 001 ERROR - command not recognised
Commands
Commands for WAP Push include:
sendwappush
sendwappush
The WAP Push framework allows information to be transmitted to a device without a user request. Only the service
indication method can be used with this command. Service loading cannot be used.

username Username for the customer. Provided in HTTP Username will be in email address format.
Note: If programming within the Authorization

header field is not possible, you may submit
the username & password parameters inside
the POST request.
password Password for this user. Provided in HTTP
Note: If programming within the Authorization

header field is not possible, you may submit
the username & password parameters inside
the POST request.
source Valid international format number or 1 – 15 digits or 11 character alphanumeric
alphanumeric string (corresponding to the string
sourceTON and sourceNPI parameters)
representing the sender or message source.
Note 1: If you define the source address in

the request, some of the message reply
features are disabled. Including linking Client
Message ID of submitted message to the
response. i.e. If you use the 'source'
parameter in the request the replyTo and
replyToTON address specified will be ignored.
destination Destination or recipient number. Typically a
valid ISDN number, but other numbers can be
specified along with the use of the
destinationTON and destinationNPI
parameters. Messages can be sent to multiple
recipients by separating the numbers with
commas.

WAP Push


Note: If you specify multiple destination
addresses, i.e.
destination=61491234567,61491234568 you
will also have to supply the source address.
url The URL address where the mobile device is
to connect to when receiving this message.
message The alert message to display to the recipient.
https The flag indicating whether or not the URL True (default) if secure connection is used.
uses secure connection False if secure connection is not used.
priority Message priority, used for message routing. 1 (default) to 9
If no priority is supplied, a default priority of 1

will be used for the message.
sourceNPI Numbering Plan Indicator for the source 0 Unknown
address. 1 ISDN (E.163/E.164) (default)
3 Data (X.121)
4 Telex (F.69)
8 National
9 Private
10 ERMES
14 Internet (IP)
18 WAP Client ID
destinationNPI Numbering Plan Indicator for the destination 0 Unknown
address(es). 1 ISDN (E.163/E.164) (default)
3 Data (X.121)
4 Telex (F.69)
8 National
9 Private
10 ERMES
14 Internet (IP)
18 WAP Client ID
destinationTON Type of Number to be used for destination 0 Unknown
address(es). 1 International (default)
2 National
3 Network Specific
4 Subscriber Number
5 Alphanumeric
6 Abbreviated
sourceTON Type of Number to be used for the source 0 Unknown
address. 1 International (default)
2 National
3 Network Specific
4 Subscriber Number
5 Alphanumeric
6 Abbreviated
responseType Specifies the envelope type to be used to 0 Text/plain (default)
send HTTP response.

WAP Push


1 Text/XML
Example: Send WAP Push message

Request:
https://apac.soprano.com.au/sendwappush?
source=61491234568&destination=61498765432,61491234567&priority=1&url=wap.bl
ah.com/wap&message=Try%20this%20new%20stuff
Response:
0 005 OK
Example: Send WAP Push message to multiple destinations with request xml response
Request:
https://apac.soprano.com.au/sendwappush?
source=61491234568&destination=61498765432&priority=1&url=wap.blah.com/
wap&message=Try%20this%20new%20stuff&responseType=1
Response:
<response>
<message>
</message>
</response>

WAP Push

Query SMS Messages

The HTTP POST interface can be used to query a message previously sent to SOPRANO MEMS. The POST
operation is initiated by the customer, and the response returned by SOPRANO MEMS.
Note: 'querymsg' can only be run on messages sent using 'sendmsg' request.
Request
A valid submission of a query request may look like:
POST /cgphttp/servlet/querymsg HTTP 1.1

Host: api.apac.soprano.com.au
Content-type: application/x-www-form-urlencoded
Content-length:50
msg_id=12179
Where the customer’s username and password are provided within the Authorization header field.
parameters 'username' and 'password' to authenticator your request.
POST /cgphttp/servlet/querymsg HTTP 1.1

Content-length:50
msg_id=12179
username=demo@apac.soprano.com.au
password=mypwd01
If you provide both username and password in the URL parameters AND in Basic Authentication, the URL
parameters will be ignored and the Basic Authentication values will be used.
Response
The following response is valid for the request above:
HTTP/1.1 200 OK
Server: Apache/1.3
Date: Mon, 05 Sep 2008 05:42:31 GMT
Content-Length: 43
0 003 OK
12179 ACCEPTED_BY_NETWORK_ELEMENT
The body of all responses to 'query' requests that were received successfully by SOPRANO MEMS will contain:
1 digit success code (e.g. '0' = Success or '1' = Error)
3 digit response code (e.g. '003')
Response string (e.g. 'OK' or 'ERROR')
an identifier for the message, containing the message ID (e.g. '12179') and the message status (e.g.
'ACCEPTED_BY_NETWORK_ELEMENT').

Query SMS Messages

If the specified message ID is not found for the customer in SOPRANO MEMS, a sample error response may look
like:
HTTP/1.1 200 OK
Server: Apache/1.3
Date: Mon, 21 Jun 2004 09:12:23 GMT
Content-Length: 35

1 050 ERROR
45051 MSG_ID_NOT_FOUND
Commands
Commands include:
querymsg
querymsg
The 'querymsg' command is used to query the status of SMSes sent to SOPRANO MEMS before.
Note: 'querymsg' can only be run on messages sent using 'sendmsg' request.

msg_id The Message-IDs returned in previous
response to submit of WAP Push
requests.
username Username for the customer. Provided in Username will be in email address format.
HTTP Authorization field.
Note: If programming within the

Authorization header field is not
possible, you may submit the username
& password parameters inside the
POST request..
password Password for this user. Provided in
Note: If programming within the

POST request..
Example: Send Query Message

Request:
https://apac.soprano.com.au/cgphttp/servlet/querymsg?msg_id=12678

Query SMS Messages

Response:
0 003 OK
Example: Send Query Message with Non-Existent/Unmatched msg_id

Request:
Response:
1 050 ERROR
Example: Send Query Message with Multiple msg_Id

Request:
https://apac.soprano.com.au/cgphttp/servlet/querymsg?
msg_id=12678,12679,12680
Response:
0 003 OK
12680 ENROUTE_IN_CIQ
Example: Send Query Message - Long Concatenated Content Split into Multiple Parts
When a 'sendmsg' request is sent for a long message, it is split into 2 or more separate messages so it will be
received on the destination handset, but the response will only return a single message ID.
When 'querymsg' is sent for a msg_ID belonging to a split message, the response contains the original or 'parent'
msg_ID, as well as 'child' msg_IDs for the individual messages that were created.
Example:
Request:
Response:
0 003 OK
80661624 CONCATENATE_SPLIT
Where:
80661624 = msg_id returned in response to original request

Query SMS Messages

80661625 = msg_id for part 1 of split message content

80661626 = msg_id for part 1 of split message content

Query SMS Messages

Cancel SMS Messages

The HTTP POST interface can be used to cancel messages sent to SOPRANO MEMS and still queuing or
scheduling inside SOPRANO MEMS. The message status will be changed to 'DELETED' after a successful 'cancel'
request. The interface doesn't cancel messages that have been sent to the network through SOPRANO MEMS.
The POST operation is initiated by the customer, and the response returned by SOPRANO MEMS.
Request
A valid submission of a 'cancel' request may look like:
POST /cancelmsg HTTP 1.1

Content-length:50
msg_id=12179
Where the customer’s username and password are provided within the Authorization header field. Refer to Section
2.1.1 for more details on the Authorization field.
POST /cancelmsg HTTP 1.1

Content-length:50
msg_id=12179
username=demo@apac.soprano.com.au
password=mypwd01
If you provide both username and password in the URL parameters AND in Basic Authentication, the URL
parameters will be ignored and the Basic Authentication values will be used.
Response
The following response is valid for the request above:
HTTP/1.1 200 OK
Server: Apache/1.3
Date: Mon, 05 Sep 2008 05:42:31 GMT
Content-Length: 43
0 004 OK
The body of all responses to cancel requests that were received successfully by the SOPRANO MEMS will contain a
one digit success code (0 = success or 1 = error), a three digit response code (refer to Table 2), a response string
(refer to Table 2).

Cancel SMS Messages

If SOPRANO MEMS cannot cancel the message(s) for some reason, an extra line of the response will contain the
message id and the message's current status. Refer to Table 3 for a list of possible message statuses and the
statuses that can be canceled.
HTTP/1.1 200 OK
Server: Apache/1.3
Date: Mon, 05 Sep 2008 05:42:31 GMT
Content-Length: 43
1 050 ERROR
If the msg_id specified is not found for the customer in SOPRANO MEMS, a sample response may look like:
HTTP/1.1 200 OK
Server: Apache/1.3
Date: Mon, 21 Jun 2004 09:12:23 GMT
Content-Length: 35

1 050 ERROR
Commands
Commands include:
cancelmsg
cancelmsg
The 'cancelmsg' command is used to cancel sending out an SMS through SOPRANO MEMS.

msg_id The Message-IDs returned in previous
response to submit of WAP Push
requests.
username Username for the customer. Provided in Username will be in email address format.
(Note: If programming within the

POST request.)
password Password for this user. Provided in
(Note: If programming within the

POST request.)

Cancel SMS Messages

Example: Send cancel message

Request:
https://apac.soprano.com.au/cgphttp/servlet/cancelmsg?msg_id=12678
Response:
0 003 OK
Example: Send cancel message with non-existent/unmatched msg_id

Request:
Response:
1 050 ERROR
Example: Send cancel message with multiple msg_id

Request:
https://apac.soprano.com.au/cgphttp/servlet/cancelmsg?
msg_id=4566,4565,776576
Response:
1 050 ERROR
4566
4565 ACCEPTED_BY_CLIENT

Cancel SMS Messages

Appendices
Appendix A - API Capabilities

The following table provides an overview of common API capabilities supported on SOPRANO Mobile Enterprise
Messaging Suite.
HTTP WSDL SMPP SMTP SMTP OMS MM7 SMAP WCTP Java .NET
(Simple) (Standard) API
Send SMS
Send MMS
Receive Inbound SMS
Receive Inbound MMS
Scheduled Delivery
Registered Delivery
Define Validity Period
Reply Control & Management
Source Address Control
Send to Multiple Recipients
Query Message Status
Cancel Message
Replace Message
Limit Content to Single SMS
Mobile Barcode
Binary Message (Ringtone)
vCard / vCalendar Messages
WAP Push (SI/SL) Messages

Appendices

One Time Password

*
Secure Connection HTTPS
Secure Tunnel (OpenSSL)
Username and Password Auth.

Basic
Username and Password Auth.
Parameters
User List Based Authentication
Passcode Authentication
Source Domain IP Auth.
* One time password for the HTTP interface requires Authenticator HTTP API.
API Functions
Function Description
Send SMS The protocol/API call provides the ability to send an SMS (Mobile Terminated
Short Message) to one or more destinations.
Send MMS The protocol/API call provides the ability to send an MMS (Mobile Terminated
Multimedia Message) to one or more destinations.
Receive Inbound SMS The protocol/API provides the ability to receive SMS (Mobile Originated Short
Messages) originating from a mobile device and deliver to a customer system in
real-time, or batched, using different time intervals (monthly, weekly, daily, hourly,
5 minutes).
Scheduled Delivery The protocol/API provides the ability to schedule a Mobile Terminated short
message for delivery at a time specified in the future.
Messages can be triggered to be sent at a later scheduled time using a relative

value from when the request was submitted (e.g. 2 hours from now).
Registered Delivery The protocol/API provides the ability to request a notification when the network
delivers a message to the mobile device.
A registered flag can be set on a message, prompting the mobile network to return
back a delivery receipt once the message is delivered to the device. Delivery
receipts are delivered the same way as an Inbound messages.
Delivery Receipts (or 'Delivery Reports') may not be fully supported across
interconnect (such as delivering a message from GSM to CDMA networks or when
delivering internationally).
Define Validity Period The protocol/API provides the ability to set the length of time the message may
reside in the mobile network SMSC without delivery (when a mobile handset is
switched off or unavailable).
Setting an expiry time for each message (e.g. 1 day or 8 hours) enables
messages to expire when not delivered within a desired period. This is useful for

Appendices

situations where the message is no longer relevant if not delivered within the
defined validity period.
Reply Control & Management The protocol/API provides the ability to control where replies (Mobile Originated/
Delivery Receipts or Reports) are to sent to in our system. This may be defined as
a web URL, email address, another mobile, or the platform database for reporting
purposes only.
While a default reply path exists within SOPRANO MEMS, this can be overwritten
using the API.
Source Address Control The protocol/API provides the ability to define the 'From' address that will appear
on the receiving mobile phone. This may be a Short Code / Vanity Short Code,
Long Code (standard international mobile number) or an Alpha Address (up to 11
characters).
SOPRANO MEMS will automatically allocate a short code to the message if no

source address is assigned to the message. If you have multiple short codes you
have the ability to nominate which short code to use for each message.
Note: The available source addresses may be limited to one or more which have
been provisioned for the root customer specifically.
Some countries do not support the sending of messages with alphanumeric

addresses.
There are also some constraints when setting the source address which will
disable automatic reply management in the platform.
Transaction ID The protocol/API provides the ability to automatically manage sessions for
customers.
To track responses to internal transactions, customers can assign an ID to each

message sent, so SOPRANO MEMS can provide the ID in the response received
and forwarded to the nominated or default reply address.
Send to Multiple Recipients The protocol/API provides the ability to send to multiple recipients in a single
request/API call.
Query Message Status The protocol/API provides the ability to query the status of a message for final
status updates (SMSC response or receipt update), using the message ID that
you receive from the platform after sending.
Cancel Message The protocol/API provides the ability to cancel a message that has been
scheduled or queued for future delivery, and has not been delivered to a mobile
device that is switched off or unavailable.
Replace Message The protocol/API provides the ability to override and replace the content of a
message that you have previously sent.
Note: Not all carriers support this function.
Limit Content to Single SMS Protocol/API preferences in the platform allow SMS messages to be truncated to a
maximum of 160 characters (1 SMS), which prevents long messages from being
generated.
This is applicable to SMTP (Email2SMS API, where an enterprise mail server may
append a footer to the email that is received by the platform).

Appendices

Long Concatenated Messages The protocol/API supports long messages (up to 1400 characters).
Mobile Barcode Not currently supported.
Binary Message (Ringtone) Not currently supported.
vCard / vCalendar Messages Not currently supported.
WAP Push (Si/SL) Messages The protocol/API provides the ability to send a WAP push (SI - Service Indicator
or SL - Service Loading) over SMS. These messages are limited to 140 octets and
may not be supported by all networks, or the current smart phone range.
One-Time Password The API (code) provides the ability to call a function that will generate a one-time
password, which can be used in the transmission of the SMS (one-time password
is then stored in a variable for your code to utilise upon challenging).
Secure Connection HTTPS The transport layer of communication with the platform is secured over an SSL
socket, utilising HTTPS.
Secure Tunnel (OpenSSL) The platform provides the ability to utilise Open SSL to set up a 'soft' VPN-type
connection, to secure communications protocols not already using SSL or
equivalent.
Username & Password Auth. The platform supports validation of API access using a username and password
Basic encoded with Basic Authentication method and transmitted in the HTTP header.
Username & Password Auth. The platform supports validation of API access using username and password
Parameters parameters transmitted in the GET / POST parameters.
User List Based Auth. The platform supports validation of API access by looking up a whitelist of allowed
senders (the sender does not have to be a platform user).
Passcode Auth. The platform supports validation of API access by checking a passcode in an
email subject line. This means that the sender of the message does not have to be
a platform user, and is typically used in conjunction with 'User List Based Auth.'.
Secure Domain IP Auth. The platform has the ability to lock down API access to a limited set of IP
addresses. IP address checking can be controlled in the Email API Preferences
for SMTP. All supported protocols require configuration by the provisioning team.

Appendices

Appendix B - Abbreviations
API Application Programming Interface – a programmatic interface which enables an application to use
the facilities of SOPRANO MEMS.
CGP Corporate Gateway Platform – underlying technology of SOPRANO MEMS – mobile messaging
infrastructure which enables the sending and receipt of mobile messages.
HTTP Hypertext transfer protocol – an internet standard for transporting information to/from a web server.
Inbound Inbound messages – messages sent from a handset (i.e. 'MO' messages) arriving at SOPRANO
MEMS from the telecommunications network, to be forwarded to a SOPRANO MEMS customer.
MMS Multimedia messaging service – a mobile messaging service which enables the sending and receipt of
multi-part multi-media messages (text, picture, video, audio etc).
MO 'Mobile Originating' – inbound messages sent from a handset – to be routed to a SOPRANO MEMS
customer by SOPRANO MEMS.
MT 'Mobile terminated' – outbound messages sent by an application through SOPRANO MEMS to reach a
particular handset.
Outbound Outbound messages are messages sent by the SOPRANO MEMS (on instruction from a customer)
out through the telecommunications network to mobile handsets.
SMS Short Message Service – a mobile messaging service enabling the sending of short text and data
messages.
SMTP Simple Mail Transfer Protocol – a standard API used for email.
UDH UDH stands for User Data Header and is specialised information that is normally posted with 8-bit
messages. The UDH contains information on the message type, the length of a message,
concatenation and more. The UDH is specific to each manufacturer.
XML Extensible Markup Language – a flexible standard for formatting information exchanged between
applications.
Appendix C - Response Details HTTP

Table 1 shows the responses that could be returned from SOPRANO MEMS as part of the response to an HTTP
request. Note that not all responses are relevant for each of the HTTP POST commands.
Table 1 - Response Status Codes & Details
Succe Respon Response String Explanation sen star sen que can WA sen sen WS
ss se dm tbat dba rym clm PP dba dm DL
sg ch tch sg sg ush rco ms
Code Code de
0 001 OK sendmsg, or sendbatch or sendmms

command completed successfully
0 002 OK startbatch command completed
successfully
0 003 OK querymsg command completed
successfully
0 004 OK cancelmsg command completed
successfully
005 OK WAPPush command completed
0 successfully

Appendices

Code Code de
2 001 ERROR – command not recognised, command

command not contains unknown or missing
recognised mandatory parameter(s), contains
repeated parameters or XML parsing
error, etc.
Note that no identifier will be returned

if this error occurs.
1 002 ERROR – batch_id Could not find message template with
not found the specified batch_id
1 050 ERROR – msg_id Could not find message id with the
not found specified msg_id
2 005 ERROR – Invalid parameter value - sourceNPI
sourceNPI value
2 021 ERROR – Invalid parameter value -
destinationNPI destinationNPI
value
2 006 ERROR – onNet Invalid parameter value – onNet
value
2 007 ERROR – Invalid parameter value - registered
registered value
2 008 ERROR – dcs Invalid parameter value - dcs
value
2 009 ERROR – Invalid parameter value –
content_type value content_type
2 022 ERROR – 8-bit dcs value does not match
binary dcs value content_type value. Refer to Table 1
expected
2 023 ERROR – 8-bit dcs value does not match
binary dcs value content_type value. Refer to Table 1
not expected
2 028 ERROR – dcs dcs value is not supported
value (not
supported)
2 029 ERROR – udh Combination of separate and
parameter not integrated udh not supported in
expected SOPRANO MEMS
2 030 ERROR – text dcs value does not match with text
parameter not parameter (data parameter expected)
expected
1 031 ERROR – Internal Internal system error
System error
1 032 ERROR – Request User is not authorised to send this
is not authorised request
1 040 ERROR 1:n The error response code when an
{destination + error occurs with a specific
status} destination.
See Table 2 below for the full list of

Destination States
2 013 ERROR – Invalid parameter value - destination
destination value

Appendices

Code Code de
2 014 ERROR – source Invalid parameter value - source

value
2 015 ERROR – delay Invalid parameter value - delay
value
2 016 ERROR – valid Invalid parameter value - valid
value
2 017 ERROR – content Invalid parameter value - content
2 018 ERROR – priority Invalid parameter value - priority
2 019 ERROR – Invalid parameter value - sourceTON

sourceTON value
2 020 ERROR – Invalid parameter value -
destinationTON destinationTON
value
2 025 ERROR – udh Invalid parameter value – udh
value (invalid invalid hexadecimal format.
hexadecimal
string)
2 027 ERROR – data Invalid parameter value – data
value (invalid invalid hexadecimal format.
hexadecimal
string)
2 041 ERROR – Invalid reply to TON
replyToTON value
2 042 ERROR – Invalid reply to NPI
replyToNPI value
2 045 ERROR – invalid Invalid response type
response type
2 046 ERROR – valid Validity period value must be greater
must be greater than delay value
than delay
2 050 ERROR – https Invalid https value
value
2 070 ERROR – Invalid textToEncode value
textToEncode
value
2 071 ERROR – Invalid symbology value
symbology value
2 072 ERROR – scaling Invalid scaling value
value
2 073 ERROR – Invalid whiteSpace value
whiteSpace value
2 074 ERROR – Invalid messageType value
messageType
value
2 075 ERROR – barcode Invalid barcode width value
width value
2 076 ERROR – barcode Invalid barcode height value
height value
2 077 ERROR – barcode Invalid barcode dimensions value
dimensions value

Appendices

Code Code de
078 ERROR – barcode Barcode width and height are too big
2 dimensions value for a barcode symbology or
exceeded messageType
079 ERROR – barcode Barcode width and height are too big
2 picture sise for a Nokia Picture Message
exceeded value barcode
2 080 ERROR - Ean8Barcode type/data is invalid or
Ean8Barcode not numeric
type/data is invalid
or not numeric
2 081 ERROR – invalid Format of the textFile is invalid or not
textFile format supported
2 082 ERROR – invalid Format of the audioFile is invalid or
audioFile format not supported
2 083 ERROR – invalid Format of the imageFile is invalid or
imageFile format not supported
2 084 ERROR – invalid Format of the videoFile is invalid or
videoFile format not supported
2 085 ERROR – An attachment is missing. The
attachment message will be sent without the
missing attachment
2 086 ERROR – invalid The length of costCentre exceeds the
costCentre max length(100)
2 087 ERROR – invalid The length of clientMessageId
clientMessageId exceeds the max length(100)
2 088 ERROR – invalid The content_type is invalid
content_type
2 089 ERROR – missing The default handset profile for the
default handset customer is not defined in database.
profile
2 090 ERROR – subject The length of subject exceeds the
too long max length
Some messages could have been successfully sent before SOPRANO MEMS went offline or encountered an error.
Therefore it is recommended to query the identifier to determine which (if any) messages were received. The
command parameters can then be adjusted accordingly before resubmitting the command.
Table 2 shows the possible status and state codes for an individual destination. These codes are used when Error 1
040 occurs.
When an error has occurred in relation to one particular recipient/destination, all destinations in the request and
their corresponding status will be reported. Since messages can be sent to multiple destinations within one HTTP
request, it could be possible for one destination to fail and others to succeed, as shown below:
HTTP/1.1 200 OK
Server: Apache/1.3
Date: Mon, 21 Jun 2004 09:12:23 GMT
Content-Length: 22
1 040 ERROR
61491234568 101
61491234567 001

Appendices

Table 2 - Destination States
Status State Code Description

OK 001 RECEIVED by CGP
002 SCHEDULED
003 ENROUTE in CIQ
004 DELETED
ERROR 101 REJECTED by CGP
103 NOT DELETED
108 number of parameters does not match
message template definition
110 msg_id not found
111 destination not found for msg_id
112 msg_id not found for destination
113 source not found for msg_id
114 msg_id not found for source
115 msg_id not found for destination and
source
Table 3 shows all the possible states for an outbound message returned when the user query a message status using
the querymsg or when the user attempts to cancel a message.
Table 3 - Outbound Message Status
Status Description
ACCEPTED_BY_NETWORK_ELEMENT* Message has been sent to the network through SOPRANO MEMS
DELIVERED* Message has been delivered and a deliver receipt has been
received from the network
ENROUTE_IN_CIQ Message is queuing in SOPRANO MEMS
ENROUTE_IN_NOQ Message is queuing in SOPRANO MEMS
SCHEDULED_IN_CIQ Message is scheduled to be sent in SOPRANO MEMS
SCHEDULED_IN_NOQ Message is scheduled to be sent in SOPRANO MEMS
UNDELIVERABLE* Cannot send this message
EXPIRED* Message has been expired and will not be sent
DELETED Message has been canceled
REJECTED* Message has been rejected by the network
CONCATENATE_SPLIT* Message has been split into few child messages to send to the
network
SUBMIT_MULTI_SPLIT* Message has been split into few child messages to send to the
network
Error Code = <xxx>* Message failed to be sent as network rejected it with the error code.
* Messages with this message state cannot be canceled.
Appendix D - DCS Parameter Details
The 'dcs' parameter is an optional parameter within the interface however it is required when sending a message to
an SMSC. Therefore, it is the SOPRANO MEMS responsibility to determine a value for the 'dcs' parameter when it
has not been included in a request. The 'dcs' value is dependent on the value of the contentType parameter, and

Appendices

this is used (as described below) to set an appropriate value for the 'dcs' parameter (rather than applying a default
value for all messages).
If the 'dcs' parameter is not included AND the 'contentType' parameter is set to 2, 3, 4, 5 or 8, the SOPRANO
MEMS will set the 'dcs' value to 8-bit binary when submitting the message to the SMSC.
If the 'dcs' parameter is not included AND the 'contentType' parameter is set to 1, 6 or 7, the SOPRANO MEMS
should set the 'dcs' value to SMSC default alphabet when submitting the message to the SMSC.
If the 'dcs' parameter is included but is not set to 8-bit binary AND the 'contentType' parameter is set to 2, 3, 4, 5
or 8, an error will be returned.
If the 'dcs' parameter is included and set to 8-bit binary AND the 'contentType' parameter is set to 6 or 7, an error
will be returned.
Table 1 and Table 2 below explicitly define the behaviour of SOPRANO MEMS when both the 'dcs' and 'contentType'
parameters are included in a message for both the 'text' and 'data' parameters respectively.
Table 1: SOPRANO Mobile Enterprise Messaging Suite behaviour when 'dcs', 'contentType' and 'text' parameters
are included in an EMAIL message.
contentType
1 2 3 4 5 6 7 8
udh udh udh udh udh udh udh udh udh udh udh udh udh udh udh
absen prese absen prese absen prese absen prese abse prese abse prese abse prese abse udh
t nt t nt t nt t nt nt nt nt nt nt nt nt present
0 B C B C B C B C C C E F
1I I I I I I I I I I I I I I I I
2 H H H H H H H H H H H H H H H H
3 I I I I I I I I I I I I I I I I
dcs 4 A A B C B C B C B C D C D C E F
8 B C B C B C B C C C E F
Legend:
message accepted
A Invalid: 8-bit data is not text
(reject message and return error 2 030)
B Invalid: pictures and tones are not text
C Combination of user-supplied and SOPRANO MEMS-generated udh not
supported in SOPRANO MEMS 4.0
D Invalid: vCards/ vCalendars are text
E Invalid: data including udh is not text
F Combination of separate and integrated udh not supported in SOPRANO
MEMS 4.0
H Set dcs value to 4 (refer to the behaviour for 4)

Appendices

I dcs value not supported by SOPRANO MEMS 4.0

Table 2: SOPRANO MEMS behaviour when 'dcs', 'contentType' and 'data' parameters are included in an EMAIL
message
contentType
1 2 3 4 5 6 7 8

udh udh udh udh udh udh udh udh udh udh udh udh udh udh udh
absen prese absen prese absen prese absen prese abse prese abse prese abse prese abse udh
t nt t nt t nt t nt nt nt nt nt nt nt nt present
0 G C G C G C G C C C F
2 H H H H H H H H H H H H H H H H
dcs 4 C C C C D C D C F
8 G C G C G C G C C C F
Legend:
message accepted
C Combination of user-supplied and SOPRANO MEMS-generated udh not
D Invalid: vCards/ vCalendars are text
F Combination of separate and integrated udh not supported in SOPRANO
MEMS 4.0
G Invalid: pictures & tones are 8-bit data
H Set dcs value to 4 (refer to the behaviour for 4)
I dcs value not supported by the SOPRANO MEMS 4.0
Appendix E - Text & Data Parameter Restrictions
Restrictions on the length of the text and data parameters are shown in the table below. Please note that the
restrictions identified below apply to messages that will not require concatenation. The SOPRANO MEMS can
guarantee the delivery of any message within these limits as a single SMS message.
content_type content field udh field dcs Restrictions for message delivery
as a single SMS message
1 text absent 0 (default) text length <= 160 characters

Appendices

content_type content field udh field dcs Restrictions for message delivery
as a single SMS message
8 text length <= 70 characters
present 0 (default) text length <= 160 - (1 + udh length in
bytes) * 8 / 7 characters
8 text length <= 70 - (1 + udh length in

bytes) / 2 characters
any 4 Invalid: 8-bit data is not text
data absent 0, 4, 8 data length <= 140 bytes
present data length + udh length <= 139 bytes
2-5 text any Invalid: pictures & tones are not text
data absent 4 (default) data length <= 133 bytes

any any other than 2, 4 Invalid: pictures & tones are 8-bit data
6-7 text absent 0 (default) text length <= 152 characters
data 8 text length <= 66 characters
any 0 (default), 8 data length <= 133 bytes
4
2-7 any present any Combination of user-supplied and
SOPRANO MEMS-generated UDH not
8 text any Invalid: data including UDH is not text
data absent 0, 4, 8 data length <= 140 bytes

any present any Combination of separate and
integrated UDH not supported in
SOPRANO MEMS 4.0
any 2 Not supported by GSM: Mapped to 4
by SOPRANO MEMS for GSM
networks. See case for 4.
any other than 0, 2, 4, 8 Not supported by GSM or SOPRANO
MEMS 4.0
Note: 'data length' and 'udh length' mean the length of the raw data represented by the supplied hexadecimal. For
example, '0a2b3c' has a length of 3 bytes.
Appendix F - XML response DTD
Document Type Definition (DTD) for XML response:
<!DOCTYPE response [
<!ELEMENT response (message+)>
<!ELEMENT message (success_code,response_code,response_string,(message_id|
batch_id),destination?,destination_code?,destination_description?)>
<!ELEMENT success_code (#PCDATA)>
<!ELEMENT response_code (#PCDATA)>
<!ELEMENT response_string (#PCDATA)>
<!ELEMENT message_id ANY>
<!ELEMENT batch_id (#PCDATA)>
<!ELEMENT destination (#PCDATA)>
<!ELEMENT destination_code (#PCDATA)>
<!ELEMENT destination_description (#PCDATA)>
]>

Appendices

Appendix G - Example Code
Shell Script examples: Perl, wget
Code Snippets: Encoding Authentication Strings
wget - HTTP API Test Script

The following Shell script requires 'wget' to be installed on the server.
Fill in the relevant username and password for the script.

#!/bin/bash
username=""
password=""
url="http://apac.soprano.com.au/cgphttp/servlet/sendmsg?destination=61491234568&text=hello+world"
wget -O- -v --http-user=$username --http-password=$password --no-check-certificate $url
Options in the wget that are not mandatory depending on the deployment:
-v: Verbose
--no-check-certificate: to prevent validation of server certificates
perl - HTTP API Test Script

Save the following file as: testHTTP.pl
#!/usr/bin/perl
use LWP::UserAgent;
$url='http://apac.soprano.com.au/cgphttp/servlet/sendmsg';
$destination='61491234568';
$text='Test the HTTP Interface';
$username='<<username>>';
$password='<<password>>';
$ua = LWP::UserAgent->new;
$req = HTTP::Request->new(GET => "$url?destination=$destination&text=$text");
$req->authorization_basic("$username", "$password");
print $ua->request($req)->as_string;
Encoding Authentication Strings

Setting the encoding string.
.NET
Dim oWeb As New System.Net.WebClient
Dim bytHeaders As Byte()
'code the username and password into basic authorization

Appendices

bytHeaders = System.Text.ASCIIEncoding.UTF8.GetBytes("somebody@somewebsite.com.au" +
":" + "thepassword")
oWeb.Headers.Add("Authorization", "Basic " + Convert.ToBase64String(bytHeaders))
oWeb.Headers.Add("Content-Type", "text/plain;charset=utf-8")
Perl
use MIME::Base64;
print encode_base64("Aladdin:open sesame"), "\n";
print decode_base64("QWxhZGRpbjpvcGVuIHNlc2FtZQ=="), "\n";
PHP
echo base64_encode("Aladdin:open sesame")."\n";
echo base64_decode("QWxhZGRpbjpvcGVuIHNlc2FtZQ==")."\n";
Python
print "Aladdin:open sesame".encode("base64")
print "QWxhZGRpbjpvcGVuIHNlc2FtZQ==".decode("base64")
Ruby
require 'base64'
puts Base64::encode64("Aladdin:open sesame")

puts Base64::decode64("QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
XQuery (eXist-db)
let $encode := util:base64-encode('Aladdin:open sesame')
let $decode := util:base64-decode('QWxhZGRpbjpvcGVuIHNlc2FtZQ==')
OpenSSL
$ printf "Aladdin:open sesame" | openssl enc -base64
QWxhZGRpbjpvcGVuIHNlc2FtZQ==
$ echo "QWxhZGRpbjpvcGVuIHNlc2FtZQ==" | openssl enc -base64 -d
Aladdin:open sesame
Server response
HTTP/1.0 200 OK
Server: HTTPd/1.0
Date: Sat, 27 Nov 2004 10:19:07 GMT
Content-Type: text/html
Content-Length: 10476

Appendices

Appendix H - FAQ
1. How do I insert a new line in the message text using the HTTP API (HTTP GET request)?
URL encode the carriage return '%0D%0A' Example: text=Test+Message%0D%0ANew+Line.
E.g:
USER DETAILS:
Username: demo@apac.soprano.com.au
Password: XXXXXXXX
REQUEST URL:
https://apac.soprano.com.au/cgphttp/servlet/sendmsg?destination=61491234567&text=Test+Message%0D%0ANew
+Line
RESPONSE:
0 001 OK

Appendices

SOPRANO HTTP Interface Developer Guide 199 PDF

Diunggah oleh

Informasi Dokumen

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

SOPRANO HTTP Interface Developer Guide 199 PDF

Diunggah oleh

Hak Cipta:

Format Tersedia

HTTP Interface Developer Guide

SOPRANO Mobile Enterprise Messaging Suite

© 2017 Soprano Design Limited

HTTP Interface Developer Guide v199

Printed: May 2017

CONFIDENTIAL INFORMATION: Do not disclose

© 2017 Soprano Design Limited 3

CONFIDENTIAL INFORMATION: Do not disclose

© 2017 Soprano Design Limited 4

CONFIDENTIAL INFORMATION: Do not disclose

Overview and Document Purpose

© 2017 Soprano Design Limited 5

CONFIDENTIAL INFORMATION: Do not disclose

We support both HTTP and HTTPS.

© 2017 Soprano Design Limited 6

CONFIDENTIAL INFORMATION: Do not disclose

Getting Started with the HTTP Interface

Step 1: Provision your HTTP API Access

Step 2: Test your Service Provisioning

Step 2.a: In your browser's address bar, type/paste the URL.

Step 3: Build your HTTP API Application

© 2017 Soprano Design Limited 7

CONFIDENTIAL INFORMATION: Do not disclose

Send SMS Messages

Delivery to one or more destination.

POST apac.soprano.com.au/cgphttp/servlet/sendmsg HTTP/1.1

Authorization: Basic {base64-encoded username:password}

Authorization: Basic dXNlckB1cmwuY29tOlBhc3N3b3JkMQ==

© 2017 Soprano Design Limited 8

CONFIDENTIAL INFORMATION: Do not disclose

2 001 ERROR - command not recognised

© 2017 Soprano Design Limited 9

CONFIDENTIAL INFORMATION: Do not disclose

Parameters Description Restricted Values

Usually the username is the user email address.

Note: If programming within the Authorization header

This is a mandatory parameter.

Note: If programming within the Authorization header

This is a mandatory parameter.

Note: If you specify multiple destination addresses, you

Note: There is a maximum number of destinations

Note: If you define the source address as a non-pool

© 2017 Soprano Design Limited 10

CONFIDENTIAL INFORMATION: Do not disclose

Parameters Description Restricted Values

Note 1: When using replyTo parameter it is mandatory

Note 2: If you use the 'source' parameter in the request

Applicable only if customer has two

Applicable only if customer has two

Note: if you define the source address in the request,

© 2017 Soprano Design Limited 11

CONFIDENTIAL INFORMATION: Do not disclose

Parameters Description Restricted Values

Either the text parameter or the data parameter may be

© 2017 Soprano Design Limited 12

CONFIDENTIAL INFORMATION: Do not disclose

Parameters Description Restricted Values

Example: Send to Single Destination

Request ('source' parameter absent):

© 2017 Soprano Design Limited 13

CONFIDENTIAL INFORMATION: Do not disclose

Example: Send a Message to a Single Destination and Request XML Response

Example: Send a Message to a Single Destination with Error