Soprano A Pi

EE Messaging Portal powered by Soprano
EEMP HTTP & WSDL Interface Developers Guide

v7.1.0
2013 Soprano Design Pty Ltd
Commercial In Confidence
EEMP HTTP & WSDL Interface Developers Guide v7.1.0
2013 Soprano Design Pty Ltd AND CONFIDENTIALITY

All rights reserved Soprano Design Pty 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 Pty 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: October 2013 in (wherever you are located)
Contents
Table of Contents
EEMP HTTP & WSDL Interface Developers Guide 5

API Capability 6
Interface Description 10
Getting Started with the HTTP Interface 12
Sending SMS Messages 14
Request 14
Response 15
Com m ands 15
sendmsg 16
Example: Sending to Single Destination 19
Example: Send a Message to a Single Destination w ith Error 20
Example: Send a Message to Multiple Destinations 20
Example: Send a Message to Multiple Destinations w ith Registered Flag 21
Example: Send a Message to a Single Destination and Request XML Response 21
Example: Send an SMS w ith Registered Delivery - Reply to Email 21
startbatch 22
Example: Initiate a Message Batch 25
Example: Initiate a Message Batch and Request XML Response 25
sendbatch 25
Example: Send Batch Messages 26
Example: Send Batch Messages and Request XML Response (Invalid Content
Value) 27
Example: Send Batch Messages (Error w ith batch_id) 27
Example: Send Batch Messages (Error w ith a Destination) 27
Receiving SMS Messages 29
Preferences 29
Request 30
Response 30
Com m ands 30
Receiving SMS Delivery Reports Messages 33
Delivery Receipt Form at 33
WAP Push 35
Request 35
Response 35
Com m ands 36
sendw appush 36
Example: Send WAP Push message 38
Example: Send WAP Push message to multiple destinations w ith request xml
response 39
Query SMS Messages 40
Request 40
Response 40
Com m ands 41
querymsg 41
Example: Send query message 42
Example: Send query message w ith non-existent/unmatched msg_id 42

3
EEMP HTTP & WSDL Interface Developers Guide v7.1.0
Example: Send query message w ith multiple msg_Id 42

Cancel SMS Messages 43
Request 43
Response 43
Com m ands 44
cancelmsg 44
Example: Send cancel message 45
Example: Send cancel message w ith w ith non-existent/unmatched msg_id 45
Example: Send cancel message w ith multiple msg_id 45
Web Services WSDL 47
Request 48
Response 49
Com m ands 49
Request 50
Response 52
Exam ple: Full trace WSDL Interaction 53
Appendices 55
Appendix A - Abbreviations 55
Appendix B - Response Details HTTP 56
Appendix C - DCS Param eter Details 61
Appendix D - Text & Data Param eter Restrictions 63
Appendix E - XML response DTD 64
Appendix F - Exam ple Code 64
w get - HTTP API Test Script 65
perl - HTTP API Test Script 65
Encoding Authentication Strings 65
Appendix G - WSDL Definition 66
Appendix H - FAQ 69

4
Overview and Document Purpose
EE Messaging Portal powered by Soprano 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 and WSDL interfaces for the EE Messaging Portal
powered by Soprano platform.
Intended Audience
This document is intended for EEMP customers interested in using:
EEMPs HTTP & WSDL interfaces for sending SMS

A basic knowledge of the HTTP protocol [5] is required.
References
[1] Soprano Design (2004), SOPRANO Corporate Gateway Platform System Requirements Specification,
version 4.0
[2] Dawson, F. and Howes, T. (1998), RFC 2426 - vCard MIME Directory Profile <http://www.ietf.org/rfc/
rfc2426.txt>
[3] Dawson, F. and Stenerson, D. (1998), RFC 2445 - Internet Calendaring and Scheduling Core Object
Specification (iCalendar), <http://www.ietf.org/rfc/rfc2445.txt>
[4] Dawson, F. et al. (1998), RFC 2447 - iCalendar Message-Based Interoperability Protocol (iMIP), <http://
www.ietf.org/rfc/rfc2447.txt>
[5] Fielding, R. et al. (1999), RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1, <http://www.faqs.org/rfcs/
rfc2616.html>
[6] Franks, J. et al. (1999), RFC 2617 - HTTP Authentication: Basic and Digest Access Authentication, <http://
www.faqs.org/rfcs/rfc2617.html>
[7] Freed, N. and Borenstein, N. (1996), RFC 2045 - Multipurpose Internet Mail Extensions (MIME) Part One:
Format of Internet Message Bodies, <http://www.faqs.org/rfcs/rfc2045.html>
[8] ETSI (1996), Digital cellular telecommunications system (Phase 2+); Alphabets and language-specific
information (GSM 03.38) <http://pda.etsi.org/pda/AQuery.asp>
[9] Howes, T. et al. (1998), RFC 2425 - A MIME Content-Type for Directory Information, <http://www.ietf.org/rfc/
rfc2425.txt>
[10] Silverberg, S. et al. (1998), RFC 2446 - iCalendar Transport-Independent Interoperability Protocol (iTIP)
Scheduling Events, BusyTime, To-dos and Journal Entries, <http://www.ietf.org/rfc/rfc2446.txt>
[11] SMPP Developers Forum (1999), Short Message Peer to Peer Protocol Specification v3.4, Issue 1.2
5
2013 Soprano Design Pty Ltd EEMP HTTP & WSDL Interface Developers Guide v7.1.0
API Capability
The following table describes the API capability available on EE Messaging Portal powered by Soprano.
HTTP WSDL SMPP SMTP SMTP OMS Java API .NET

(Sim ple) (Standard)
Send SMS
Receive Inbound SMS
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
One Time Passw ord
Secure Connection HTTPS

Secure Tunnel (OpenSSL)
Username and Passw ord Auth.
Basic
Username and Passw ord Auth.
Parameters
User List Based Authentication
Passcode Authentication
Source Domain IP Auth.
Please note that all mobile numbers must be entered in international format when
using the APIs & interfaces.
6
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 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 EEMP, 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).
EEMP 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
7
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 EEMP 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).
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
Basic password encoded with Basic Authentication method and transmitted in the
HTTP header.
8
Username & Password Auth. The platform supports validation of API access using username and
Parameters password 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.
9
Interface Description
Customers can be authorised to send or receive messages using this HTTP interface. Both HTTP and HTTPS are
supported.
This interface can be used in the form of HTTP POST or as 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 EE Messaging Portal powered by
Soprano and can be accessed via the web or other reporting interfaces.
EEMP is HTTP version 1.1 compliant.
All 'send' commands require authentication (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: 447312345678.
The following is a list of EEMP HTTP Interface URLs:
Command URL
sendmsg https://t-mmp.com/cgphttp/servlet/sendmsg
startbatch https://t-mmp.com/cgphttp/servlet/startbatch
sendbatch https://t-mmp.com/cgphttp/servlet/sendbatch
sendwappush https://t-mmp.com/cgphttp/servlet/sendwappush
querymsg https://t-mmp.com/cgphttp/servlet/querymsg
cancelmsg https://t-mmp.com/cgphttp/servlet/cancelmsg
NOTE: The above URLs will also work with HTTP.
Using the WSDL interface, defined customers can see what services are available, what parameters are available,
where to address the Web Services Requests.
The following are the EEMP WSDL interface URLs:
Command URL
sendmsg (WSDL) https://t-mmp.com/cgpwebservices/services/CGPWebSMSInterface
Request path:
https://t-mmp.com/cgpwebservices/services/CGPWebSMSInterface/
sendmsg
10
Command URL
11
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://t-mmp.com/cgphttp/servlet/sendmsg?destination=$mydestination&text=$text
Where:
$mydestination is the mobile number you want to send to in international format i.e. 447312345678
$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.
12
Step 3: Build your HTTP API Application
API code libraries include:
Java
VB .NET
Various shell script examples include:
Perl
wget
PHP
Code Snippets:
VB - Encoding Authentication Strings
Step 4. Additional Support
Additional support and information exists for API and interface development:
Support teams
Online Help
Additional Information
HTTP URL depends upon the service that you will utilise.
13
Sending SMS Messages
The HTTP interface may be used to send SMS messages (intended for delivery to one or more destinations). Both
POST and GET methods are supported.
The HTTP interface also supports batch messaging, allowing 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.
The POST and GET requests are to be initiated by the customer, and a response is returned from the EEMP to the
customer.
Please note that all mobile numbers must be entered in international format when
using the APIs & interfaces.
Request
Message submission using the POST method conforms to the following structure:
Request:
POST %HOST_URL%:PORT/cgphttp/servlet/sendmsg HTTP/1.1

Authorization: Basic YWxpYXNAc29wcmFuby5jb20uYXU6cGFzc3dvcmQ=
HTTP/1.x 200 OK
Content-Type: text/plain;charset=utf-8
Content-Length: 30
Date: Wed, 20 Aug 2008 07:14:32 GMT
destination=61491000000&text=initial+test+message
The above example displays a basic SMS request, where the customers 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://HOST_URL:PORT/cgphttp/servlet/sendmsg?destination=61491000000&
text=initial+test+message
Authentication
NOTE: Access to the EEMP host requires authentication (implemented via HTTP Basic Authentication). This
requires that the customers username and password be included in an authorization line in the HTTP header. The
Authorization header line is of the form:
Authorization: Basic base64_username_and_password
Example: 'YWxpYXNAc29wcmFuby5jb20uYXU6cGFzc3dvcmQ=' equates to: 'alias@soprano.com.au:password'
where base64_username_and_password is the customers username, followed by a colon (:) and the customers
password, all encoded as a single string using the base64 encoding scheme (refer to [7]). The first example above
includes authorization for a customer whose username is 'Aladdin' and password is 'open sesame'.
Alternatively, if you do not wish to use the basic authentication method for your submission you may use the HTTP
14
parameters 'username' and 'password' to authenticate your request.
https://HOST_URL:PORT/cgphttp/servlet/sendmsg?username=demo@soprano.com.au&
password=mypwd01&destination=61491000000&text=initial+test+message
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 EEMP 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-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 EEMP 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 (which can be used when querying/canceling the message).
If the request could not be interpreted by EEMP (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. For 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 recognized
Note that the response contains text intended for use in automated applications.
Section Appendix B: Response Details describes the commands and corresponding responses for the HTTP
interface, and their corresponding parameters.
Commands
Sending SMS Messages commands include:
sendmsg
startbatch
15
sendbatch
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

username & password parameters inside the GET
or POST request.
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.
destination Destination or recipient number. Typically a valid 1 15 digits
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.
Note: If you specify multiple destination addresses,

i.e. destination=447312345678,447312345679 you
will also have to supply the source address.
Note: There is a maximum number of destinations

supported in a HTTP sendmsg request of 100
destinations.
source Valid international format number or alphanumeric 1 15 digits or 11 character
string (corresponding to the sourceTON and alphanumeric string
sourceNPI parameters) representing the sender or
message source, e.g. 447312345678
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 i.e. If you use
the 'source' parameter in the request the replyTo
and replyToTON address specified will be ignored.
registered Request acknowledgment for message. Returns 0 Off (default)
16
msg_id, user and status to the customer via the 1 On
specified channel for acknowledgments.
delay Delay delivery of SMS to recipient. If used, must be Integer-relative delay (from
less than 'valid' value. message submission time) in
minutes (typically greater than 10 for
best effect)
valid The validity period of the message, after which time Relative validity (from message
the 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 Specifies the destination the reply goes to. This Maximum 250 characters.
can be a valid MSISDN, email, URL, or a valid
inbound order ID etc.
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 Type of Number to be used for reply address to 0 INBOX
indicate if replyTo field is: INBOX, MOBILE, EMAIL,
1 MOBILE
INBOUND, URL.
8 EMAIL
10 URL
responseType Specifies the envelope type to be used to send 0 Text/plain (default)
HTTP response
1 Text/XML
costCentre User cost centre label 100 characters maximum
clientMessageId User message reference which will be sent back 100 characters maximum
with 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 0 Unknown
(es).
1 ISDN (E.163/E.164)
(default)
3 Data (X.121)
4 Telex (F.69)
6 Land Mobile (E.212)
8 National
9 Private
10 ERMES
17
14 Internet (IP)
18 WAP Client ID
destinationTON Type of Number to be used for destination address 0 Unknown
(es).
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 0 Unknown
address.
2 National
3 Network Specific
4 Subscriber Number
5 Alphanumeric
6 Abbreviated
data Message content (hexadecimal encoding). The 160 characters or 140 bytes
data parameter is used to send Nokia Ringtones, maximum
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 EEMP will determine the
coding scheme based on
dcs must be provided if a data value is provided. 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, characters per message)
8
18
2 Octet unspecified (8-bit
For NOKIA_RINGTONE, binary), (140 characters
NOKIA_OPERATOR_LOGO, per message)
NOKIA_PICTURE_MESSAGE,
NOKIA_GROUP_LOGO use dcs values: 2, 4
binary), (140 characters
per message)
For RAW_BINARY_DATA use dcs values: 0, 2, 4
8 UCS2 (ISO/IEC-10646),
Note, DCS = 16,20,24 represent flash type (70 characters per
messages. message)
16 Flash Message, Standard
GSM 7 bit Alphabet. (160
characters per message)
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
This parameter is mainly used to indicate use of 3 Nokia Operator Logo
binary messages like logos and ringtones.
Either the content_type parameter or udh 4 Nokia Picture Message
parameter must be used when the data parameter 5 Nokia Group Logo
is used. If the content_type parameter is not
included when the text parameter is used, the text 6 Business Card (vCard) -
parameter is assumed to contain plain text (URL Not currently supported
encoded). 7 Calendar Event
(vCalendar) - Not
currently supported
8 Raw Binary Data (data
includes UDH)
udh Contains the UDH (hexadecimal encoding) for the The udh parameter should be less
data contained in the data parameter. than 139 bytes if it is to be delivered
Either the content_type parameter or udh as a single SMS (refer to Appendix C
parameter must be used when the data parameter for more details)
is used.
Note: Optional parameters are shown in italics.
Example: Sending to Single Destination
Request:
http://HOST_URL:PORT/cgphttp/servlet/sendmsg?destination=61403021234&text=initial+
test+message&source=61403020000
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.
19
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://HOST_URL:PORT/cgphttp/servlet/sendmsg?destination=61403021234&text=initial+
test+message
Using the above example sends the message using one of the pooled source addresses.
Response:
0 001 OK
Message-ID: 12300012
Example: Send a Message to a Single Destination with Error
Request:
https://HOST_URL:PORT/cgphttp/servlet/sendmsg?destination=61403021235&text=initial+
test+message&source=61403020000
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:
https://HOST_URL:PORT/cgphttp/servlet/sendmsg?destination=61403021235,61432145677,
61401425431&text=initial+test+message&source=61403020000
Response:
0 001 OK
20
Example: Send a Message to Multiple Destinations with Registered Flag
Request:
https://HOST_URL:PORT/cgphttp/servlet/sendmsg?destination=61403021235,61432145677&
text=initial+test+message&source=61403020000&registered=1
Response:
0 001 OK
Message-ID: 1001
Example: Send a Message to a Single Destination and Request XML Response
Request:
https://HOST_URL:PORT/cgphttp/servlet/sendmsg?destination=61403021234&text=initial+
test+message&source=61403020000&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 an SMS with Registered Delivery - Reply to Email
https://HOST_URL:PORT/cgphttp/servlet/sendmsg?destination=61494225344&text=hello13&dcs
=8&replyToTON=8&replyTo=peter@soprano.com.aureplytoton=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=61494225344
destination=61407838067
clientMessageId=
text=id:4988312 sub:001 dlvrd:001 submit date:1005251604 done date:1005251609 stat:EXPIRED err:000 text:No
Text
21
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 Username will be in email
Authorization field. address 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 recipients 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 & that have existing meanings within a URL.
source Valid international format number or alphanumeric 1 15 digits or 11 character
string (corresponding to the sourceTON and alphanumeric string
sourceNPI parameters) representing the sender or
message source.
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. i.e. If you use the 'source'
parameter in the request the replyTo and replyToTON
address specified will be ignored.
registered Request acknowledgment for message. Returns 0 Off (default)
msgid, user and status to the customer via the
specified channel for acknowledgments. 1 On
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
22
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

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
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
23
3 Network Specific
4 Subscriber Number
5 Alphanumeric
6 Abbreviated
dcs Indicates the Data Coding Scheme for the SMS. 0 EEMP will determine
the coding scheme
dcs must be provided if a data value is provided. based on provided
content. If no special
For text, the only accepted dcs values are: 0, 8, 16, 20, characters (e.g. UCS2)
24. are found then the
value 1 is used. (160
Note, DCS = 16,20,24 represent flash type messages. characters per
message)
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
characters per
message)
20 Flash Message, Octet
unspecified (8-bit
binary), (140
characters per
message)
24 Flash Message, UCS2

(ISO/IEC-10646), (70
characters per
message)
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
EEMP 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.
24
Example: Initiate a Message Batch
Request:
https://HOST_URL:PORT/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://HOST_URL:PORT/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
Authorization field. format.
(Note: If programming within the Authorization

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

username & password parameters inside the
GET or POST request.)
batch_id Batch identifier returned from startbatch
command.
content Contains the data to be inserted into the template x delimiterval x delimiterval etc. where x
with each parameter separated by the delimiter denotes a data element. The
value. Each content refers to a single message destination address must be the first
being generated from a template, defined by data element of the content value and
batch_id conform to the format specified by the
destinationTON and destinationNPI
parameters.
responseType Specifies the envelope type to be used to send 0 Text/plain (default)
HTTP response
1 Text&content=61403021235,
John,100&content=6143214
5677,Mark,50&content=6140
1425431,Paul,120t/XML
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 EEMP 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://HOST_URL:PORT/cgphttp/servlet/sendbatch?batch_id=241&content=61403021234,
Joe,250&content=61403041744,Jane,100
Response:
0 001 OK
61403021234 003
0 001 OK
61403041744 003
26
Example: Send Batch Messages and Request XML Response (Invalid Content Value)
Request:
https://HOST_URL:PORT/cgphttp/sendbatch?batch_id=1209139371&content=61403021234
Joe,250&content=61403041744,Jane&responseType=1
Response:
<response>
<message>
<response_string>ERROR</response_string>
<message_id/>
<destination>61403021234</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://HOST_URL:PORT/cgphttp/servlet/sendbatch?batch_id=24&content=61403021235,John
100&content=61432145677,Mark,50&content=61401425431,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://HOST_URL:PORT/cgphttp/sendbatch?batch_id=241&content=61403021235,John,100&
content=61432145A677,Mark,50&content=61401425431,Paul,120
Response:
27
2 017 ERROR - content
28
Receiving SMS Messages
SMS messages originating from a mobile device can be delivered to a customer via EEMP using the HTTP GET or
POST interface, provided they have configured the their account on EEMP to forward incoming messages to URL.
In this instance, the GET or POST operation is initiated by EEMP, and the response should be returned by the
customer. Typically, customer(s) will handle the incoming HTTP requests (SMS messages are processed by EEMP
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.
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 EEMP 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 the option in this section 'Use Plain Text Email' refers to 'Forward to Email' and is unrelated to the HTTP/WSDL
interface.
29
Request
Example 1 (HTTP GET): When receiving a mobile-originated message, EEMP will submit a HTTP GET Request to
the customer's nominated URL (e.g. http://CUSTOMER_HOST_URL:PORT):
https://CUSTOMER_HOST_URL:PORT/yourapplication?destination=61433000203&
text=Hello World&source=213123&networkSubmitTime=2011-11-16+10%3A26%3A
13&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://CUSTOMER_HOST_URL:PORT/yourapplication?destination=61429925830&
clientMessageId=10332&source=61494225344&text=KEYWORD+SUBKEYWORD+VALUE&
from=61494225344&to=61429925830
&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
EEMP expects the customers 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 1 15 digits
the sender address.
This is the mobile number the message was

sent from.
destination Valid international format number representing 1 15 digits
the recipient address.
30
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 Format: YYYY-MM-DD+HH:MM:SS
the 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 EEMP Platform received the Format: YYYY-MM-DD+HH:MM:SS
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 1 2 digits
(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 parameter for long
messages.
segmentNumber The segment number of this concatenated 1 2 digits

message 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
messages.
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 application, forwarding to the URL
have the same reference number. using the HTTP API does not
messages.
to Same as 'destination' field.
31
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.
32
Receiving 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 m essage to w hen 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://sopranodesign.com/downloads/
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
String when originally submitted.
(Decimal)
sub 3 C-Octet Number of short messages originally submitted. This is
String only relevant when the original message was submitted to
33
(Decimal) a 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
(Decimal) distribution list. 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
Length String submitted. In the case of a message which has been
replaced, this is the 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 State Final Message Description

State
DELIVERED DELIVRD Message is delivered to destination.
EXPIRED EXPIRED Message validity period has expired.
DELETED DELETED Message has been deleted.
UNDELIVERABLE UNDELIV Message is undeliverable.
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.
34
WAP Push
The HTTP POST interface can be used to send WAP Push messages to a recipients 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://HOST_URL:PORT/cgphttp/servlet/sendwappush?source=61491261028&
destination=61494022810,61496230051&priority=1&message=Please+click+
on+the+link+to+authorise+your+transaction&url=wap.blah.com/wap&https=true
Where the customers 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
https://HOST_URL:PORT/cgphttp/servlet/sendmsg?username=demo@soprano.com.au&
password=mypwd01&destination=61491000000&text=initial+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. The following is an
35
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 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 HTTP
Authorization field.

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.
36
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.
Note: If you specify multiple destination

addresses, i.e.
destination=447312345678,4473123456
79 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 1 (default) to 9

routing.
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 0 Unknown
destination address(es).
3 Data (X.121)
4 Telex (F.69)
8 National
9 Private
37
10 ERMES
14 Internet (IP)
18 WAP Client ID
destinationTON Type of Number to be used for destination 0 Unknown
address(es).
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.
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.
1 Text/XML
Note: Optional parameters are shown in italics.
Example: Send WAP Push message
Request:
https://HOST_URL:PORT/sendwappush?source=61421261028&destination=61414022810,
61416230051&priority=1&url=wap.blah.com/wap&message=Try%20this%20new%20stuff
Response:
0 005 OK
38
Example: Send WAP Push message to multiple destinations with request xml response
Request:
https://HOST_URL:PORT/sendwappush?source=61421261028&destination=61414022810&
priority=1&url=wap.blah.com/wap&message=Try%20this%20new%20stuff&
responseType=1
Response:
<response>
<message>
<message_id>1167</message_id>
</message>
</response>
39
Query SMS Messages
The HTTP POST interface can be used to query a message sent to EEMP before.
The POST operation is initiated by the Customer, and the response returned by EEMP.
Request
A valid submission of a query request may look like:
POST /cgphttp/servlet/querymsg HTTP 1.1

Host: api.soprano.com.au
Content-type: application/x-www-form-urlencoded
Content-length:50
msg_id=12179
Where the customers 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@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 EEMP will contain a one digit
Table 2) and an identifier for the message which contains the message's ID and the message's status. Refer to
40
Table 3 for a list of possible message status.
If the msg_id specified is not found for the Customer in EEMP, 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
45051 MSG_ID_NOT_FOUND
Commands
Commands include:
querymsg
querymsg
The querymsg command is used to query the status of SMSs sent to EEMP before.

msg_id The Message-IDs returned in
previous response to submit of WAP
Push requests.
username Username for the customer. Username will be in email address format.

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

inside the POST request..
41
Example: Send query message
Request:
https://HOST_URL:PORT/cgphttp/servlet/querymsg?msg_id=12678
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://HOST_URL:PORT/cgphttp/servlet/querymsg?msg_id=12678,12679,12680
Response:
0 003 OK
12680 ENROUTE_IN_CIQ
42
Cancel SMS Messages
The HTTP POST interface can be used to cancel messages sent to EEMP and still queuing or scheduling inside
EEMP. 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 EEMP.
The POST operation is initiated by the customer, and the response returned by EEMP.
Request
A valid submission of a 'cancel' request may look like:
POST /cancelmsg HTTP 1.1

Content-length:50
msg_id=12179
Where the customers 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@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 EEMP will contain a one digit
43
Table 2).
If EEMP 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 EEMP, 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 EEMP.

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

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

inside the POST request.)
Example: Send cancel message
Request:
https://HOST_URL:PORT/cgphttp/servlet/cancelmsg?msg_id=12678
Response:
0 003 OK
Example: Send cancel message with with non-existent/unmatched msg_id
Request:
Response:
1 050 ERROR
Example: Send cancel message with multiple msg_id
Request:
https://HOST_URL:PORT/cgphttp/servlet/cancelmsg?msg_id=4566,4567,4565,776576
Response:
45
1 050 ERROR
4566
4567
4565 ACCEPTED_BY_CLIENT
46
Web Services WSDL
The WSDL defines the relevant information to the SOPRANO WSDL API such as:
Interface information
Data types
Binding information
Address information
WSDL is, effectively, a different type of HTTP-based interface which uses a Request/Response interaction with an
XML payload over HTTP.
HTTP Request (POST)
XML
SOAP Envelope
SOAP Body
HTTP Response (POST)
XML
SOAP Envelope
SOAP Body
47
Request
A valid submission of a WSDL sendmsg request may look like:
POST /cgpwebservices/services/CGPWebSMSInterface
HTTP/1.1
Content-Type: application/soap+xml; charset=UTF-8; action="urn:sendmsg"

User-Agent: SopranoTestAgent
Host: my.localhost.com
Content-Length: 990
<?xml version='1.0' encoding='UTF-8'?>

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
<soapenv:Body>
<ns2:sendmsg xmlns:ns2="http://cgpwebservices.web.cgp.soprano.com.au">
<ns2:request>
<ns1:clientMessageId
xmlns:ns1="http://cgpwebservices.web.cgp.soprano.com.au/xsd">
</ns1:clientMessageId>
<ns1:destinations
61425318543
</ns1:destinations>
<ns1:message
test4, your account balance is $505.
</ns1:message>
<ns1:password
mypassword
</ns1:password>
<ns1:replyTo
</ns1:replyTo>
<ns1:source
</ns1:source>
<ns1:username
mytestacc@soprano.com.au
</ns1:username>
</ns2:request>
</ns2:sendmsg>
</soapenv:Body>
</soapenv:Envelope>
Note: the example above has been edited to alter the username and login credentials, which has in turn changed
the Content-length parameter.
48
Response
The following response is an example response to the request above:
HTTP/1.1 200 OK.

Server: Sun-ONE-Web-Server/6.1
Date: Fri, 20 Feb 2009 01:47:49 GMT
Content-type: application/soap+xml; action="urn:sendmsgResponse";charset=UTF-8
Set-Cookie : SMSESSION=DeVtGsphMisaXLgeSnwfY5wMb6Mk9AnzPZwrkfPncvnu3cwAlLzQmkt
hyNB+K0kAfomkkNvFzS1hMxOeO8rxP9R/591HKeNHyuaHXCEUbBiqmqe8gLEzlrz6asOsM5IG9sSi
4lP9OJnw96q+Mo6rbMJSAWelPYyxB6Xmi2ubLcLCjDnNnUy856VxGv+e+dLEQ5OSCgiywrBS/v8cw
/5+YcU4EJbltp6Mn6ttmsvSXUmBn+8d+TxkDvsk7rFMrlb61+ASManjZlyOt2/yxb/l7SuzwZoN5N
uCsIJU3H/VVQ8=; path=/; domain=.localhost.com
Cache-Control: private, max-age=60
Cache-control: private
X-powered-by: Servlet/2.4..Set-cookie: ESS-WebApp-8083=52f71a2852f71b0aa52dbac4;
path=/
Transfer-encoding: chunked

<soapenv:Body>
<ns:sendmsgResponse
xmlns:ns="http://cgpwebservices.web.cgp.soprano.com.au">
<ns:return xmlns:ax21="http://cgpwebservices.web.cgp.soprano.com.au/xsd"
type="au.com.soprano.cgp.web.cgpwebservices.Response">
<ax21:messageId>
97172314
</ax21:messageId>
<ax21:responseCode>
001
</ax21:responseCode>
<ax21:responseString>
OK
</ax21:responseString>
<ax21:successCode>
0
</ax21:successCode>
</ns:return>
</ns:sendmsgResponse>
</soapenv:Body>
</soapenv:Envelope>
Commands
Commands include:
WSDL Send Message Request

WSDL Send Message Response
49
Request
The WSDL framework allows information to be transmitted to a device without a User request.

username (*) Username for the customer. Username will be in email address format.
Provided in the Authorization
field.
password (*) Password for this user.
Provided in the Authorization
field.
ClientMessageId User message reference 100 characters maximum
(*) which will be sent back with
reply messages.
contentType This field is currently ignored. This field is currently ignored
costCentre User cost centre label. String, 100 characters maximum
data This field is currently ignored. This field is currently ignored
dcs dcs value in the request is SOPRANO CGP will determine the coding scheme
ignored. based on provided content. If no special characters
(e.g. UCS2) are found then the value 1 is used.
delay Delay field is used for the Time unit is minutes.
scheduling the time to for the
message to be sent. Scheduled time = Current Time + Number of minutes
delay.
If used the combined time must be less that set in the

'ValidityPeriod' field.
destinationTON Type of Number to be used for 0 Unknown
destination address(es).
2 National
3 Network Specific
4 Subscriber Number
5 Alphanumeric
6 Abbreviated
destinations (*) Destinations or recipient String
numbers. Typically a valid
MISDN number, but other Destinations are between 8-15 digits depending.
numbers can be specified
along with the use of the Note: If you want to send to multiple destinations then
destinationTON and you need to supply multiple "destinations" elements.
destinationNPI parameters.
message The alert message to display
to the recipient.
priority Message priority, used for 1 (default) to 9
message routing.
If no priority is supplied, a
default priority of 1 will be
50
registered Request acknowledgment for 0 Off (default)
message. Returns msg_id,
user and status to the
customer via the specified
channel for 1 On
acknowledgments.
replyTo (*) Specifies the destination the Maximum 250 characters.

reply goes to. This can be a
valid MSISDN, email, URL, or
a valid inbound order ID etc.
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 (*) Type of Number to be used for 0 INBOX
reply address to indicate if
1 MOBILE
replyTo field is: INBOX,
MOBILE, EMAIL, INBOUND, 8 EMAIL
URL.
10 URL
source Valid international format 1 15 digits or 11 character alphanumeric string
number or alphanumeric
string (corresponding to the
sourceTON and sourceNPI
parameters) representing the
sender or message source.
Note 1: When sending a

message to multiple
addresses a valid 'source
address' must be provided.
Note 2: 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.
sourceNPI Numbering Plan Indicator for 0 Unknown
the source address.
3 Data (X.121)
4 Telex (F.69)
51
8 National
9 Private
10 ERMES
14 Internet (IP)
18 WAP Client ID
sourceTON Type of Number to be used for 0 Unknown
the source address.
2 National
3 Network Specific
4 Subscriber Number
5 Alphanumeric
6 Abbreviated
udh This field is currently ignored This field is currently ignored
validityPeriod Unit (in minutes) that will be Long, unit in minutes
added into the current time to
make a future time for the
validity of the message.
Note: (*) denotes mandatory field.
Note: WSDL is a subset of HTTP Parameters. URL, HTTPS & responseType are not supported in WSDL currently.
Response

messageId Message reference which will be
sent back with submission
response.
responseCode A three digit response code. (refer to Table 2 )
responseString Textual response string. (refer to Table 2)
successCode One Digit Code summarising the 0 Success
result.
1 Error
52
Example: Full trace WSDL Interaction
POST /cgpwebservices/services/CGPWebSMSInterface HTTP/1.1

Content-Type: application/soap+xml; charset=UTF-8; action="urn:sendmsg"
User-Agent: Axis2
Host: 192.168.111.120:9081
Transfer-Encoding: chunked

<soapenv:Body>
<ns2:sendmsg xmlns:ns2="http://cgpwebservices.web.cgp.soprano.com.au">
<ns2:request>
<ns1:clientMessageId
xmlns:ns1="http://cgpwebservices.web.cgp.soprano.com.au/xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1" />
<ns1:costCentre
<ns1:destinations
61494225344</ns1:destinations>
<ns1:message
Hello World</ns1:message>
<ns1:password
Password</ns1:password>
<ns1:replyTo
<ns1:source
111111</ns1:source>
<ns1:username
username@email.domain</ns1:username>
</ns2:request>
</ns2:sendmsg>
</soapenv:Body>
</soapenv:Envelope>
53
HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=UTF-8; action="urn:sendmsgResponse"

Content-Language: en-US
Transfer-Encoding: chunked
Date: Wed, 15 Dec 2010 03:58:25 GMT
Server: WebSphere Application Server/7.0

<soapenv:Body>
<ns:sendmsgResponse xmlns:ns="http://cgpwebservices.web.cgp.soprano.com.au">
<ns:return xmlns:ax21="http://cgpwebservices.web.cgp.soprano.com.au/xsd"
type="au.com.soprano.cgp.web.cgpwebservices.Response">
<ax21:messageId>211879</ax21:messageId>
<ax21:responseCode>001</ax21:responseCode>
<ax21:responseString>OK</ax21:responseString>
<ax21:successCode>0</ax21:successCode>
</ns:return>
</ns:sendmsgResponse>
</soapenv:Body>
</soapenv:Envelope>
54
Appendices
Appendix A - Abbreviations
Appendix B - Response Details HTTP
Appendix C - DCS Parameter Details
Appendix D - Text & Data Parameter Restrictions
Appendix E - XML response DTD
Appendix F - Example Code
Appendix G - WSDL Definition
Appendix H - FAQ
Appendix A - Abbreviations
API Application Programming Interface a programmatic interface which enables an

application to use the facilities of EEMP,
CGP SOPRANO Corporate Gateway Platform - underlying technology of the EEMP 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
the EEMP from the telecommunications network, to be forwarded to a EEMP
customer.
MO Mobile Originating messages sent inbound from a handset to be routed to a
EEMP customer by EEMP.
MT Mobile Terminated outbound messages sent by an application through the EEMP to
reach a particular handset.
Outbound Outbound messages - messages sent by the EEMP (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 - User Data Header - 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.
55
Appendix B - Response Details HTTP
Table 2 shows the responses that could be returned from EEMP as part of the response to an HTTP request. Note
that not all responses are relevant for each of the HTTP POST commands.
Table 2 Response details

Success Code Respo Response Explanation s st s q c W s W
nse String e ar e u a A e S
Code n tb n e n P n D
d at d ry cl P d L
m c b m m u b
s h at s s s ar
g c g g h c
h o
d
e
0 001 OK sendmsg, or sendbatch 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
2 001 ERROR command not recognised,
command not command contains unknown or
recognised missing 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 Could not find message template
batch_id not with the specified batch_id
found
1 050 ERROR Could not find message id with the
msg_id not specified msg_id
found
2 005 ERROR Invalid parameter value - sourceNPI
sourceNPI
value
2 021 ERROR Invalid parameter value -
destinationNP destinationNPI
I value
2 006 ERROR Invalid parameter value onNet
onNet value
2 007 ERROR ack Invalid parameter value - ack
value
2 008 ERROR dcs Invalid parameter value - dcs
value
2 009 ERROR Invalid parameter value
content_type content_type
56
d at d ry cl P d L
m c b m m u b
s h at s s s ar
g c g g h c
h o
d
e
value
2 022 ERROR 8- dcs value does not match
bit binary dcs content_type value. Refer to Table 1.
value
expected
2 023 ERROR 8- dcs value does not match
bit binary dcs content_type value. Refer to Table 1
value 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 the
expected EEMP
2 030 ERROR text dcs value does not match with text
parameter not parameter (data parameter
expected expected)
1 031 ERROR Internal system error
Internal
System error
1 032 ERROR User is not authorised to send this
Request is not request
authorised
1 040 ERROR The error response code when an
error occurs with a destination. The
response should be extended to
include the status of each
destination
2 013 ERROR Invalid parameter value - destination
destination
value
2 014 ERROR Invalid parameter value - source
source value
2 015 ERROR Invalid parameter value - delay
delay value
2 016 ERROR Invalid parameter value - valid
valid value
2 017 ERROR - Invalid parameter value - content
content
2 018 ERROR - Invalid parameter value - priority
priority
sourceTON sourceTON
57
d at d ry cl P d L
m c b m m u b
s h at s s s ar
g c g g h c
h o
d
e
value
destinationTO destinationTON
N value
2 025 ERROR udh Invalid parameter value udh
value (invalid invalid hexadecimal format.
hexadecimal
string)
2 027 ERROR Invalid parameter value data
data value invalid hexadecimal format.
(invalid
hexadecimal
string)
2 041 ERROR - Invalid reply to TON
replyToTON
value
2 042 ERROR Invalid reply to NPI
replyToNPI
value
2 045 ERROR - Invalid response type
invalid
response type
2 046 ERROR Validity period value must be greater
valid must be than delay value
greater than
delay
2 050 ERROR Invalid https value
https value
2 070 ERROR - Invalid textToEncode value
textToEncode
value
2 071 ERROR - Invalid symbology value
symbology
value
2 072 ERROR - Invalid scaling value
scaling value
2 073 ERROR - Invalid whiteSpace value
whiteSpace
value
2 074 ERROR - Invalid messageType value
messageType
value
2 075 ERROR - Invalid barcode width value
barcode width
58
d at d ry cl P d L
m c b m m u b
s h at s s s ar
g c g g h c
h o
d
e
value
2 076 ERROR - Invalid barcode height value
barcode
height value
077 ERROR - Invalid barcode dimensions value
2 barcode
dimensions
value
078 ERROR - Barcode width and height are too
2 barcode big for a barcode symbology or
dimensions messageType
value
exceeded
079 ERROR - Barcode width and height are too
2 barcode big for a Nokia Picture Message
picture size barcode
exceeded
value
2 080 ERROR - Ean8Barcode type/data is invalid or
Ean8Barcode not numeric
type/data is
invalid or not
numeric
2 081 ERROR Format of the textFile is invalid or not
invalid textFile supported
format
2 082 ERROR Format of the audioFile is invalid or
invalid not supported
audioFile
format
2 083 ERROR Format of the imageFile is invalid or
imageFile
format
2 084 ERROR Format of the videoFile is invalid or
videoFile
format
2 085 ERROR An attachment is missing. The
attachment message will be sent without the
missing attachment
2 086 ERROR The length of costCentre exceeds
invalid the max length(100)
costCentre
2 087 ERROR The length of clientMessageId
59
d at d ry cl P d L
m c b m m u b
s h at s s s ar
g c g g h c
h o
d
e
invalid exceeds the max length(100)

clientMessage
Id
2 088 ERROR The content_type is invalid
invalid
content_type
2 089 ERROR The default handset profile for the
missing customer is not defined in
default database.
handset
profile
2 090 ERROR The length of subject exceeds the
subject too max length
long
Some messages could have been successfully sent before EEMP 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 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 Statuses
Status Description
ACCEPTED_BY_NETWORK_ELEMENT* Message has been sent to the network through EEMP
DELIVERED* Message has been delivered and a deliver receipt has been
received from the network
ENROUTE_IN_CIQ Message is queuing in EEMP
ENROUTE_IN_NOQ Message is queuing in EEMP
SCHEDULED_IN_CIQ Message is scheduled to be sent in EEMP
SCHEDULED_IN_NOQ Message is scheduled to be sent in EEMP
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
60
Status Description
code.
* Messages with this message state cannot be canceled.
Appendix C - 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 EEMP 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 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 EEMP 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 EEMP 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 C.1 and Table C.2 below explicitly define the behaviour of EEMP when both the 'dcs' and 'contentType'
parameters are included in a message for both the 'text' and 'data' parameters respectively.
Table C.1 EE Messaging Portal powered by Soprano 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 udh
abs pres abs pres abs pres abs pres abs pres abs pres abs pres abs presen
ent ent ent ent ent ent ent ent ent ent ent ent ent ent ent t
0 B C B C B C B C C C E F
1 I 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
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
61
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 EEMP-generated udh not supported in EEMP 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 EEMP 4.0
H Set dcs value to 4 (refer to the behaviour for 4)
I dcs value not supported by EEMP 4.0
Table C.2 EEMP 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 udh
abs pres abs pres abs pres abs pres abs pres abs pres abs pres abs presen
ent ent ent ent ent ent ent ent ent ent ent ent ent ent ent t
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
62
C Combination of user-supplied and EEMP-generated udh not supported in EEMP 4.0
D Invalid: vCards/ vCalendars are text
F Combination of separate and integrated udh not supported in EEMP 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 EEMP 4.0
Appendix D - 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 EEMP can guarantee the
delivery of any message within these limits as a single SMS message.
content_type content field udh field dcs Restrictions
1 text absent 0 (default) text length <= 160 characters

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 EEMP-generated UDH not
supported in EEMP 4.0
63
content_type content field udh field dcs Restrictions
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
EEMP 4.0
any 2 Not supported by GSM: Mapped
to 4 by EEMP for GSM networks.
See case for 4.
any other than 0, 2, 4, Not supported by GSM or EEMP

8 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 E - 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)>
]>
Appendix F - Example Code
Code libraries
Java
VB .NET
Various Shell Script examples include:
Perl
wget
Code Snippets:
Encoding Authentication Strings
64
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://t-mmp.com/cgphttp/servlet/sendmsg?destination=61494225344&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://t-mmp.com/cgphttp/servlet/sendmsg';
$destination='61494225344';
$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
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;
65
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
Appendix G - WSDL Definition
WSDL for Request and Response for EEMP
<?xml version="1.0" encoding="UTF-8"?>

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:axis2="urn:sopranoonline" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
xmlns:ns0="http://cgpwebservices.web.cgp.soprano.com.au" xmlns:soap12="http://
schemas.xmlsoap.org/wsdl/soap12/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:ns1="http://cgpwebservices.web.cgp.soprano.com.au/xsd" xmlns:wsaw="http://
66
www.w3.org/2006/05/addressing/wsdl" xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="urn:sopranoonline">
<wsdl:types>
<xs:schema xmlns:ns="http://cgpwebservices.web.cgp.soprano.com.au"
attributeFormDefault="unqualified" elementFormDefault="qualified"
targetNamespace="http://cgpwebservices.web.cgp.soprano.com.au">
<xs:element name="sendmsg">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" name="request" nillable="true"
type="ns1:Request"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="sendmsgResponse">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" name="return" nillable="true"
type="ns1:Response"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
<xs:schema xmlns:ax21="http://cgpwebservices.web.cgp.soprano.com.au/xsd"
attributeFormDefault="unqualified" elementFormDefault="qualified"
targetNamespace="http://cgpwebservices.web.cgp.soprano.com.au/xsd">
<xs:complexType name="Request">
<xs:sequence>
<xs:element minOccurs="0" name="clientMessageId" nillable="true"
type="xs:string"/>
<xs:element minOccurs="0" name="contentType" type="xs:int"/>
<xs:element minOccurs="0" name="costCentre" nillable="true"
type="xs:string"/>
<xs:element minOccurs="0" name="data" nillable="true"
type="xs:string"/>
<xs:element minOccurs="0" name="dcs" type="xs:int"/>
<xs:element minOccurs="0" name="delay" type="xs:int"/>
<xs:element minOccurs="0" name="destinationNPI" type="xs:byte"/>
<xs:element minOccurs="0" name="destinationTON" type="xs:byte"/>
<xs:element maxOccurs="unbounded" minOccurs="0" name="destinations"
nillable="true" type="xs:string"/>
<xs:element minOccurs="0" name="message" nillable="true"
type="xs:string"/>
<xs:element minOccurs="0" name="password" nillable="true"
type="xs:string"/>
<xs:element minOccurs="0" name="priority" type="xs:byte"/>
<xs:element minOccurs="0" name="registered" type="xs:byte"/>
<xs:element minOccurs="0" name="replyTo" nillable="true"
type="xs:string"/>
<xs:element minOccurs="0" name="replyToNPI" type="xs:byte"/>
<xs:element minOccurs="0" name="replyToTON" type="xs:byte"/>
<xs:element minOccurs="0" name="source" nillable="true"
type="xs:string"/>
<xs:element minOccurs="0" name="sourceNPI" type="xs:byte"/>
<xs:element minOccurs="0" name="sourceTON" type="xs:byte"/>
<xs:element minOccurs="0" name="udh" nillable="true"
type="xs:string"/>
<xs:element minOccurs="0" name="username" nillable="true"
type="xs:string"/>
<xs:element minOccurs="0" name="validityPeriod" type="xs:long"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="Response">
<xs:sequence>
<xs:element minOccurs="0" name="messageId" nillable="true"
type="xs:string"/>
67
<xs:element minOccurs="0" name="responseCode" nillable="true"
type="xs:string"/>
<xs:element minOccurs="0" name="responseString" nillable="true"
type="xs:string"/>
<xs:element minOccurs="0" name="successCode" nillable="true"
type="xs:string"/>
</xs:sequence>
<xs:attribute name="type" type="xs:string"/>
</xs:complexType>
</xs:schema>
</wsdl:types>
<wsdl:message name="sendmsgRequest">
<wsdl:part name="parameters" element="ns0:sendmsg"/>
</wsdl:message>
<wsdl:message name="sendmsgResponse">
<wsdl:part name="parameters" element="ns0:sendmsgResponse"/>
</wsdl:message>
<wsdl:portType name="CGPWebSMSInterfacePortType">
<wsdl:operation name="sendmsg">
<wsdl:input message="axis2:sendmsgRequest" wsaw:Action="urn:sendmsg"/>
<wsdl:output message="axis2:sendmsgResponse"
wsaw:Action="urn:sendmsgResponse"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="CGPWebSMSInterfaceSOAP11Binding"
type="axis2:CGPWebSMSInterfacePortType">
<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/
>
<soap:operation soapAction="urn:sendmsg" style="document"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:binding name="CGPWebSMSInterfaceSOAP12Binding"
<soap12:binding transport="http://schemas.xmlsoap.org/soap/http"
style="document"/>
<soap12:operation soapAction="urn:sendmsg" style="document"/>
<wsdl:input>
<soap12:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap12:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:binding name="CGPWebSMSInterfaceHttpBinding"
<http:binding verb="POST"/>
<http:operation location="CGPWebSMSInterface/sendmsg"/>
<wsdl:input>
<mime:content type="text/xml" part="parameters"/>
</wsdl:input>
<wsdl:output>
<mime:content type="text/xml" part="parameters"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="CGPWebSMSInterface">
68
<wsdl:port name="CGPWebSMSInterfaceSOAP11port_http"
binding="axis2:CGPWebSMSInterfaceSOAP11Binding">
<soap:address location="http://t-mmp.com/cgpwebservices/services/
CGPWebSMSInterface"/>
</wsdl:port>
<wsdl:port name="CGPWebSMSInterfaceSOAP12port_http"
binding="axis2:CGPWebSMSInterfaceSOAP12Binding">
<soap12:address location="http://t-mmp.com/cgpwebservices/services/
</wsdl:port>
<wsdl:port name="CGPWebSMSInterfaceHttpport"
binding="axis2:CGPWebSMSInterfaceHttpBinding">
<http:address location="http://t-mmp.com/cgpwebservices/services/
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
Note: For accuracy, please obtain the latest WSDL file directly from your Account Executive.
Or use the link:
http://t-mmp.com/wsdl/t-mmp.com.wsdl
Appendix H - FAQ
Q: How do I insert a new line in the message text using the HTTP API (HTTP GET request)?
A: URL encode the carriage return '%0D%0A' Example: text=Test+Message%0D%0ANew+Line.
e.g.
USER DETAILS:
Username: demo@soprano.com.au
Password: XXXXXXXX
REQUEST URL:
https://[DOMAIN]/cgphttp/servlet/sendmsg?destination=61494225344&text=Test+Message%0D%
0ANew+Line
RESPONSE:
0 001 OK
69

Soprano A Pi

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Soprano A Pi

Hochgeladen von

Copyright:

Verfügbare Formate

EE Messaging Portal powered by Soprano

EEMP HTTP & WSDL Interface Developers Guide

2013 Soprano Design Pty Ltd

2013 Soprano Design Pty Ltd AND CONFIDENTIALITY

Printed: October 2013 in (wherever you are located)

EEMP HTTP & WSDL Interface Developers Guide 5

2013 Soprano Design Pty Ltd

Example: Send query message w ith multiple msg_Id 42

2013 Soprano Design Pty Ltd

This document is intended for EEMP customers interested in using:

EEMPs HTTP & WSDL interfaces for sending SMS

HTTP WSDL SMPP SMTP SMTP OMS Java API .NET

Receive Inbound SMS

Reply Control & Management

Send to Multiple Recipients

Query Message Status

Limit Content to Single SMS

Secure Connection HTTPS

Messages can be triggered to be sent at a later scheduled time using a

A registered flag can be set on a message, prompting the mobile network to

EEMP will automatically allocate a short code to the message if no source

Some countries do not support the sending of messages with alphanumeric

To track responses to internal transactions, customers can assign an ID to

Note: Not all carriers support this function.

This is applicable to SMTP (Email2SMS API, where an enterprise mail server

Mobile Barcode Not currently supported.

Binary Message (Ringtone) Not currently supported.

vCard / vCalendar Messages Not currently supported.

EEMP is HTTP version 1.1 compliant.

The following is a list of EEMP HTTP Interface URLs:

NOTE: The above URLs will also work with HTTP.

The following are the EEMP WSDL interface URLs:

Step 1: Provision your HTTP API Access

Request HTTP API access to be provisioned for your account.

Step 2: Test your Service Provisioning

The easiest way to test the service is with your browser.

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

Various shell script examples include:

VB - Encoding Authentication Strings

Step 4. Additional Support

POST %HOST_URL%:PORT/cgphttp/servlet/sendmsg HTTP/1.1

Authorization: Basic base64_username_and_password

Example: 'YWxpYXNAc29wcmFuby5jb20uYXU6cGFzc3dvcmQ=' equates to: 'alias@soprano.com.au:password'

2 001 ERROR - command not recognized

Sending SMS Messages commands include:

Parameters Description Restricted Values

Usually the username is the user email address.

Note: If programming within the Authorization

This is a mandatory parameter.

Note: If programming within the Authorization

This is a mandatory parameter.

Note: If you specify multiple destination addresses,

Note: There is a maximum number of destinations

Note: If you define the source address in the

Note 1: When using replyTo parameter it is

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

Note: if you define the source address in the

Either the text parameter or the data parameter may

Note: Optional parameters are shown in italics.

Example: Sending to Single Destination

Request ('source' parameter absent):

Example: Send a Message to a Single Destination with Error

1 031 ERROR - internal CGP failure