1 Revision history
Date | Revision | Initials | Comments |
09-06-2008 | 1.0 | CG | Initial version based on previous documentation format. |
02-02-2009 | 1.1 | CG | Updated SMS and MMS alphatext documentation. |
02-02-2009 | 1.1 | CG | Corrected SSL SOAP service endpoint file extension. |
02-02-2009 | 1.1 | CG | Completed SMS status code table (Table 4). |
13-02-2009 | 1.1 | CG | Documented additional SMS gateway functions. |
13-02-2009 | 1.1 | CG | Documented additional MMS gateway functions. |
16-02-2009 | 1.1 | CG | Added link to TDC mailing list best practices. |
03-04-2009 | 1.1 | CG | Additional documentation and misc. error correction. |
28-05-2009 | 1.1 | CG | Added details regarding attachment file types and corrected misc. errors. |
07-05-2010 | 1.2 | CG | Corrected MMS status and error code tables. |
14-05-2010 | 1.2 | CG | Documented HTTP GET/POST interface. |
03-06-2010 | 1.2 | CG | Updated information regarding MMS text attachments. |
10-10-2011 | 1.3 | CG | Minor update to HTTP GET/POST interface. |
21-06-2012 | 1.3 | TH | Update document layout. |
02-10-2012 | 1.3 | CG | Added details on Premium SMS content categories to Appendix 7.4, “Gateway information sheet” |
23-01-2015 | 1.3 | CG | Updated terminology and information regarding SMS message length limitation. |
2 Terminology
Term | Description |
IP address | Internet Protocol address |
MIME | Multipurpose Internet Mail Extensions |
MMS | Multimedia Messaging Service, 3GPP TS 23.140 V6.15.0: “Multimedia Messaging Service (MMS); Functional description”, see http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/23140-6f0.zip Media formats: Open Mobile Alliance OMA-TS-MMS-CONF-V1_3-20080128-C: "MMS Conformance Document", see http://ocq.dk/mmsformats |
MNO | Mobile Network Operator |
MO | Mobile Originated traffic, i.e. inbound SMS or MMS traffic originating from a mobile handset. |
MT | Mobile Terminated traffic, i.e. outbound SMS or MMS traffic terminating in a mobile handset. |
SMIL | Synchronized Multimedia Integration Language. See http://ocq.dk/mmsformats |
SOAP | Simple Object Access Protocol. Standard for accessing remote objects and methods using XML over HTTP. See http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ |
SSL | Secure Sockets Layer. A cryptographic protocol that provides secure communications on the Internet. |
URL | Uniform Resource Locator |
UTF-8 | UCS (Universal Character Set) Transformation Format 8. See http://www.unicode.org/versions/Unicode5.0.0/ch03.pdf#G7404 |
WSDL | Web Service Description Language. See http://www.w3.org/TR/wsdl |
XML | Extensible Markup Language. Standard for structured mark-up languages. |
XSD | XML Schema Definition. Definition of a specific XML-based language |
Table of Contents
4.2 Connection and Authentication
5.4 Receiving Messages and Status Information
5.4.2 SMS MT status information
5.4.3 MMS MT status information
5.5.1 Receive messages and status information
6.1.2 HTTP GET/POST request parameters
6.2 Status information callback
7.2.1 SMS status codes (SOAP/HTTP)
7.2.2 SMS error codes (SOAP/HTTP)
7.2.3 SMS callback status code (HTTP GET/POST)
3 Introduction
This document describes the application programming interfaces (APIs) available for the NIMTA messaging gateway provided by OnlineCity. The provided interfaces enable OnlineCity customers to build message based services on top of the gateway (including content-based and charging services), aimed at mobile network subscribers.
The intended audience for this document is developers of third party applications that need to interact with end users in mobile networks regarding content providing services. Basic knowledge of HTTP, web services and mobile terminology in general is required.
The first part of the document gives an overview of the interfaces and describes client requirements in general whereas the second part includes a detailed description of each provided API.
4 Overview
The NIMTA gateway enables access to mobile network users in order to perform message- and content-based charging services. Figure 1 below provides an overview of the system topology. All communication between client applications and the NIMTA gateway can be encrypted using SSL services.
Figure 1: Illustration of NIMTA gatewayʹs position in the mobile network landscape.
4.1 Supported interfaces
The NIMTA gateway supports the following protocol interfaces:
- SOAP/HTTP
- HTTP GET/POST
4.2 Connection and Authentication
Regardless of whether you will be using the SOAP/HTTP or HTTP GET/POST interface you need the following provided by OnlineCity:
- Gateway username and password.
- Username and password for status delivery (optional).
- One or more active gateway classes – typically ‘A’ (Premium/Professional) or ‘B’ (Bulk).
Furthermore, you must have provided OnlineCity with valid information concerning:
- The IP(s) from which you access the gateway.
- The URL to which the NIMTA gateway should deliver status information (optional).
5 SOAP/HTTP API Specification
5.1 General guidelines
The following issues all apply broadly to interfacing with the message gateway:
Text string encoding
Make sure all strings are UTF-8 encoded.
Server time zone
Be aware of your server’s time zone – the gateway is configured for Danish local time, i.e. GMT+1 also known as CET.
5.2 Sending Messages
5.2.1 SOAP Service Endpoint
The gateway service can be reached at:
http://www.nimta.com/Gateway/Kunder/Opret/Gateway.asmx
Using SSL, it is possible to encrypt requests sent to the gateway by using:
https://www.nimta.com/Gateway/Kunder/Opret/Gateway.asmx
In the latter case data sent to the gateway is encrypted and stays so until it is handed over to the mobile network. Regardless of whether SSL is used or not, all messages are encrypted when they reach the mobile network.
WSDL[1] files for the gateway service are available at:
http://www.nimta.com/Gateway/Kunder/Opret/Gateway.asmx?WSDL (non-SSL)
and
https://www.nimta.com/Gateway/Kunder/Opret/Gateway.asmx?WSDL (SSL)
5.2.2 SMS
sendSMSes | ||
Element | Type | Description |
username | xsd:string | The gateway username supplied by OnlineCity. |
password | xsd:string | The gateway password supplied by OnlineCity. |
gatewayClass | xsd:string | The gateway class to use for message delivery. Several classes exist depending on whether delivery is ordinary SMS, bulk SMS etc. Please refer to your gateway subscription and contact OnlineCity if in doubt. |
messages | SMSSendMes sage | An enumeration containing the SMS text messages to send. |
SMSSendMessage Enumeration | ||
Element | Type | Description |
message | xsd:string | The message text. |
sendTime | xsd:dateTime | The time at which the message should be sent (only used if ‘delayed’ is true). |
delayed | xsd:boolean | If set to true, the message will be sent at ‘sendTime’. If set to false, the message is sent immediately. |
alphatext | xsd:string | Optional, if NULL -> ordinary message. Name of sender as shown on recipient’s phone, used instead of 4 digit shortcode. Max. length is 11 characters. Note: Alpha text messages may be priced differently than ordinary messages. Please refer to your gateway subscription. Alpha text messages cannot be charged. |
charge[2] | xsd:int | The charge debited the recipient’s account. Charge must be specified in Danish ‘ører’, i.e. DKK 1 = 100 ører. A value of ‘0’ means no charge. Note: If message is longer than 160 characters, only the first message is charged. |
donation | xsd:string | Note: Use of donations requires prior arrangements with OnlineCity. Optional, do not set unless your gateway subscription specifically allows donations. Indicates whether the charge is a donation or not. Accepted values are True or NULL. |
wapurl | xsd:string | Optional, if NULL -> ordinary message. If not NULL message is sent as WAP-PUSH. Note: WAP-PUSH messages are limited to 140 characters in length, including the WAP URL. |
recipients | Recipients | An enumeration containing the recipients of the message. Minimum length is 1 Note: If charge > 0 multiple recipients are not allowed. |
Recipients Enumeration | ||
Element | Type | Description |
countryCode | xsd:string | The country code (without ‘+’ or leading zeroes). ‘0045’ thus becomes ‘45’. |
number | xsd:string | The recipient’s phone number |
operatorCode | xsd:string | The code for the recipient’s operator - see Table 3. Note: Operator code is mandatory for charged messages. Specify operator code #4 for uncharged messages. If you previously have received a message from the recipient, the gateway provides you with the operator code. |
deleteSMS | ||
Element | Type | Description |
username | xsd:string | The gateway username supplied by OnlineCity. |
password | xsd:string | The gateway username supplied by OnlineCity. |
messageID | xsd:string | The unique identifier of the SMS message that is to be deleted, as returned by the gateway when the message was originally sent. |
getSMSMessages | ||
Element | Type | Description |
username | xsd:string | The gateway username supplied by OnlineCity. |
password | xsd:string | The gateway username supplied by OnlineCity. |
query | SMSGetMessageQuery | The parameters of the query that determines which messages are returned. |
SMSGetMessageQuery | ||
Element | Type | Description |
gatewayClass | xsd:string | Specifies the query should return messages sent using this gateway class. Optional. |
countryCode | xsd:string | Specifies the query should return messages sent to this country code. Optional. |
number | xsd:string | Specifies the query should return messages sent to this recipient number. Optional. |
specifyInterval | xsd:boolean | Determines if the query should only return messages sent during a specific time interval, specified by ‘intervalStart’ and ‘intervalEnd’. Mandatory. |
intervalStart | xsd:dateTime | Specifies the start date for which sent messages should be returned. Mandatory. |
intervalEnd | xsd:dateTime | Specifies the end date for which sent messages should be returned. Mandatory. |
statusCode | xsd:unsigned Byte | Specifies the query should return messages with this status code. Mandatory. |
5.2.3 MMS
sendMMSes | ||
Element | Type | Description |
username | xsd:string | The gateway username supplied by OnlineCity. |
password | xsd:string | The gateway password supplied by OnlineCity. |
gatewayClass | xsd:string | The gateway class to use for message delivery. Several classes exist depending on whether delivery is ordinary MMS, bulk MMS etc. Please refer to your gateway subscription and contact OnlineCity if in doubt. |
messages | MMSSendMessage | An enumeration containing the MMS text messages to send. |
MMSSendMessage Enumeration | ||
Element | Type | Description |
message | xsd:string | Optional. The message text. Max. length is 800 characters. |
subject | xsd:string | Message subject line. Max. length is 40 characters. |
sendTime | xsd:dateTime | The time at which the message should be sent (only used if ‘delayed’ is true). |
delayed | xsd:boolean | If set true, the message will be sent at ‘sendTime’. If set to false, message is sent immediately. |
alphatext | xsd:string | Optional, if NULL -> ordinary message. Name of sender as shown on recipient’s phone, used instead of 4 digit shortcode. Max. length is 10 characters and can be set to a phone number (without ‘+’) or an email address. |
charge[3] | xsd:int | The charge debited the recipient’s account. Charge must be specified in Danish ‘ører’, i.e. DKK 1 = 100 ører. A value of ‘0’ means no charge. |
recipients | Recipients | An enumeration containing the recipients of the message. Note: If charge > 0 multiple recipients are not allowed. |
pictureFiles[4] | PictureFiles | Optional. An enumeration containing zero or more URLs to image files to attach. |
soundFiles | SoundFiles | Optional. An enumeration containing zero or more URLs to audio files[5] to attach. |
videoFiles | VideoFiles | Optional. An enumeration containing zero or more URLs to video files to attach. |
texts | Texts | Optional. An enumeration containing zero or more strings of text to attach. Each text string may consist of a maximum of 6000 characters. |
smilFiles | SmilFiles | Optional. An enumeration containing zero or more URLs to SMIL[6] files to attach. |
Recipients Enumeration | ||
Element | Type | Description |
countryCode | xsd:string | The country code (without ‘+’ or leading zeroes). ‘0045’ thus becomes ‘45’. |
number | xsd:string | The recipient’s phone number |
operatorCode | xsd:string | The code for the recipient’s operator - see Table 3. Note: Operator code #4 cannot be used with charged messages. |
Picture Files Enumeration | ||
Element | Type | Description |
url | xsd:string | Well-formed URL pointing to a valid image file. Max. length is 1000 characters. |
Sound Files Enumeration | ||
Element | Type | Description |
url | xsd:string | Well-formed URL pointing to a valid audio file of type AMR with extension .amr. Max. length is 1000 characters. |
Video Files Enumeration | ||
Element | Type | Description |
url | xsd:string | Well-formed URL pointing to a valid video file. Max. length is 1000 characters. |
Text Files Enumeration | ||
Element | Type | Description |
text | xsd:string | A string of text to insert. The text string may consist of a max-‐‑ imum of 6000 characters. Other restrictions may apply. |
SMIL Files Enumeration | ||
Element | Type | Description |
url | xsd:string | Well-formed URL pointing to a valid SMIL file. Max. length is 1000 characters. |
deleteMMS | ||
Element | Type | Description |
username | xsd:string | The gateway username supplied by OnlineCity. |
password | xsd:string | The gateway password supplied by OnlineCity. |
messageID | xsd:string | The unique identifier of the MMS message that is to be deleted, as returned by the gateway when the message was originally sendt. |
getMMSMessage | ||
Element | Type | Description |
username | xsd:string | The gateway username supplied by OnlineCity. |
password | xsd:string | The gateway username supplied by OnlineCity. |
messageID | xsd:string | The unique identifier of the MMS message that is to be returned, as returned by the gateway when the message was originally sent. |
getMMSMessage | ||
Element | Type | Description |
username | xsd:string | The gateway username supplied by OnlineCity. |
password | xsd:string | The gateway username supplied by OnlineCity. |
query | MMSGetMessageQuery | The parameters of the query that determines which messages are returned. |
MMSGetMessageQuery | ||
Element | Type | Description |
gatewayClass | xsd:string | Specifies the query should return messages sent using this gateway class. Optional. |
countryCode | xsd:string | Specifies the query should return messages sent to this country code. Optional. |
number | xsd:string | Specifies the query should return messages sent to this recipient number. Optional. |
specifyInterval | xsd:boolean | Determines if the query should only return messages sent during a specific time interval, specified by ‘intervalStart’ and ‘intervalEnd’. Mandatory. |
intervalStart | xsd:dateTime | Specifies the start date for which sent messages should be returned. Mandatory. |
intervalEnd | xsd:dateTime | Specifies the end date for which sent messages should be returned. Mandatory. |
statusCode | xsd:unsigned Byte | Specifies the query should return messages with this status code. Mandatory. |
5.2.4 Email[7]
sendEmails | ||
Element | Type | Description |
username | xsd:string | The gateway username supplied by OnlineCity. |
password | xsd:string | The gateway password supplied by OnlineCity. |
gatewayClass | xsd:string | The gateway class to use for message delivery. Several classes exist.
|
messages | EmailSendMessage | An enumeration containing the emails to send. |
EmailSendMessage Enumeration | ||
Element | Type | Description |
htmlbody | xsd:string | The message text, UTF encoded. If ‘htmlbody’ is set, the mail is sent as HTML. |
textbody | xsd:string | The body text of the mail. If both ‘textbody’ AND ‘htmlbody’ are set, ‘htmlbody’ is attached as “alternative” content (HTML capable email clients will display the ‘htmlbody’ text, all others will display ‘textbody’). |
sendTime | xsd:dateTime | The time at which the message should be sent (only used if ‘delayed’ is true). |
delayed | xsd:boolean | If set to true, the message will be sent at ‘sendTime’. If set to false, message is sent immediately. |
senderAddress | xsd:string | The email address of the sender. Max. length is 320 characters. |
senderName | xsd:string | The name of the sender. Max. length is 100 characters. |
replyAddress | xsd:string | The reply email address. Max. length is 320 characters. |
replyName | xsd:string | The reply name. Max. length is 100 characters. |
subject | xsd:string | Email subject. Max. length is 1000 characters. Newline characters are not accepted. |
tags | Tags | An enumeration of tag names. Tags can be used in both ‘htmlbody’ and ‘textbody’. The number of tags must match the number of tagValues and their ordering must be identical. |
recipients | EmailRecipients | An enumeration containing the recipients of the mail. |
attachments | EmailAttach ments | An enumeration of attached files. Note attachments are limited to a combined size of 512 KB. |
Tags Enumeration | ||
Element | Type | Description |
Name | xsd:string | The name of the tag |
EmailRecipients Enumeration | ||
Element | Type | Description |
emailaddress | xsd:string | A valid email address. Maximum length 320 characters. |
name | xsd:string | The name of the recipient. |
tagvalues | Tagvalues | An enumeration of tag values. The number of tag values must match the number of tags (see above) and the position of each tag within the enumeration must match the position of the corresponding tag name within the tags enumeration.
|
Tagvalues Enumeration | ||
Element | Type | Description |
value | xsd:string | Tag value that corresponds to a tag name. |
EmailAttachment Enumeration | ||
Element | Type | Description |
url | xsd:string | The URL pointing to the file to attach. |
mimetype | xsd:string | The content type of the attached file (i.e. image/gif, audio/ac3 etc[8]) |
5.3 Sample Code
With this document you should have received a zipped archive with C# and PHP code samples. This section briefly describes the contents of the zipped archive.
5.3.1 Sending SMS
The file ‘C#\SendSMS.cs’ illustrates how to connect to the gateway using C# (.NET) to send SMS text messages. The accompanying file, ‘C#\SMSClasses.cs’, contains C# class definitions for classes that are used when sending SMS text messages.
The file ‘PHP5\sendsms.php’ illustrates how to connect to the gateway using PHP to send SMS text messages.
5.3.2 Sending MMS
The file ‘C#\SendMMS.cs’ illustrates how to connect to the gateway using C# (.NET) to send MMS messages. The accompanying file, ‘C#\MMSClasses.cs’, contains C# class definitions for classes that are used when sending MMS text messages.
5.3.3 Sending Email
The file ‘C#\SendEmail.cs’ illustrates how to connect to the gateway using C# (.NET) to send email messages. The accompanying file, ‘C#\EmailClasses.cs’, contains C# class definitions for classes that are used when sending email messages.
5.4 Receiving Messages and Status Information
5.4.1 SOAP Service Endpoint
In order to receive incoming messages as well as status information on sent messages, you must implement a SOAP service endpoint according to the specifications listed below.
A sample WSDL[9] file for this service is available at:
http://www.nimta.com/Gateway/Kunder/Udsend/GatewayModtager.wsdl
You must submit the URL of the service endpoint to OnlineCity and we will then provide you with a username and password the gateway will use when connecting to your service (see section 4.2). Please note that this username/password combination is different from the one used for sending messages.
5.4.2 SMS MT status information
ReceiveSMSStatuses | ||
Element | Type | Description |
username | xsd:string | A valid username to your service (supplied by OnlineCity, see section 4.2). |
password | xsd:string | A valid password to your service (supplied by OnlineCity, see section 4.2). |
statuses | ArrayOfStatus | An enumeration of message status information. |
ArrayOfStatus Enumeration | ||
Element | Type | Description |
messageID | xsd:int | The message ID returned by SendSMSes (see section 5.2.2) when the message was sent. |
countryCode | xsd:string | The recipient number country code. |
number | xsd:string | The number of the message recipient. |
latestStatus | xsd:dateTime | Time at which ‘statusCode’ was received. |
statusCode | xsd:unsignedByte | The delivery status, see possible values in Table 4. |
errorCode | xsd:unsignedByte | Only set if statusCode == 3, see possible values in Table 5. |
5.4.3 MMS MT status information
ReceiveMMSStatuses | ||
Element | Type | Description |
username | xsd:string | A valid username to your service (supplied by OnlineCity, see section 4.2). |
password | xsd:string | A valid password to your service (supplied by OnlineCity, see section 4.2). |
statuses | Status | An enumeration of message status information. |
ArrayOfStatus Enumeration | ||
Element | Type | Description |
messageID | xsd:int | The message ID returned by SendMMSes (see section 5.2.3) when the message was sent. |
countryCode | xsd:string | The recipient number country code. |
number | xsd:string | The number of the message recipient. |
latestStatus | xsd:dateTime | Time at which ‘statusCode’ was received. |
statusCode | xsd:unsignedByte | The delivery status, see possible values in Table 7. |
errorCode | xsd:unsignedByte | Only set if statusCode == 2, see possible values in Ta-‐‑ ble 8. |
5.4.4 Incoming SMS - SMS MO
ReceiveSMSes | ||
Element | Type | Description |
username | xsd:string | A valid username to your service (supplied by OnlineCity, see section 4.2). |
password | xsd:string | A valid password to your service (supplied by OnlineCity, see section 4.2). |
messages | ArrayOfSMSReceiveMessage | An enumeration of SMS messages. |
ArrayOfSMSReceiveMessage Enumeration | ||
Element | Type | Description |
messageID | xsd:int | The unique message ID. |
countryCode | xsd:string | The sender number country code. |
number | xsd:string | The number of the sender. |
keyword | xsd:string | The media code, the message was sent to. |
message | xsd:string | The body text of the message. |
received | xsd:dateTime | Timestamp indicating when the message was received by the gateway. |
operatorCode | xsd:int | The sender’s operator. See Table 3. |
5.4.5 Incoming MMS - MMS MO
ReceiveMMSes | ||
Element | Type | Description |
username | xsd:string | A valid username to your service (supplied by OnlineCity, see section 4.2). |
password | xsd:string | A valid password to your service (supplied by OnlineCity, see section 4.2). |
messages | ArrayOfMMSReceiveMessage | An enumeration of message status information. |
ArrayOfMMSReceiveMessage Enumeration | ||
Element | Type | Description |
messageID | xsd:int | The unique message ID. |
countryCode | xsd:string | The sender number country code. |
number | xsd:string | The number of the sender. |
keyword | xsd:string | The media code, the message was sent to. |
subject | xsd:string | Message subject line. |
message | xsd:string | The body text of the message. |
received | xsd:dateTime | Timestamp indicating when the message was received by the gateway. |
operatorCode | xsd:int | The sender’s operator. See Table 3. |
pictureFiles | ArrayOfString | An enumeration containing zero or more URL’s to image files attached to the message. |
soundFiles | ArrayOfString | An enumeration containing zero or more URL’s to audio files attached to the message. |
videoFiles | ArrayOfString | An enumeration containing zero or more URL’s to video files attached to the message. |
texts | ArrayOfString | An enumeration containing zero or more URL’s to text files attached to the message. |
smilFiles | ArrayOfString | An enumeration containing zero or more URL’s to SMIL[10] files attached to the message. |
ArrayOfString Enumeration | ||
Element | Type | Description |
string | xsd:string | Well-formed URL pointing to a valid file. |
5.5 Sample Code
With this document you should have received a zipped archive with C# and PHP code samples. This section briefly describes the contents of the zipped archive.
5.5.1 Receive messages and status information
The file ‘C#\ReceiverServiceInterface.cs’ describes the interface of the service you must implement in order to receive both incoming messages, as well as status information on sent messages. The file ‘C#\ReceiveClasses.cs’ illustrates how to implement various supporting classes in C#.
The file ‘PHP5\gatewayreceiver.php’ illustrates how the receiving service can be implemented using PHP. Note that all service methods are basically dummy methods, which simply log incoming messages and status information to a debug log.
6 HTTP GET/POST Specification
The HTTP GET/POST interface enables clients to send a SMS message to one or more recipients by submitting a HTTP GET or POST request to a URL at OnlineCity. This section details how to use the HTTP GET/POST interface.
Please note that to avoid server overload and prevent DoS attacks, traffic limitations are imposed on the HTTP GET/POST interface. Each client IP is restricted to 100 request submissions per second. It does not matter if it is 100 requests with one (1) recipient each, or 100 requests with 1000 recipients each.
If the 100 requests/sec limitation is violated, the client IP will be blocked from the service for 5 minutes.
Clients can for instance do one of the following to ensure the 100 requests/sec limitation is not violated:
- Add a delay (e.g. 10 ms) between requests.
- Put requests in a queue - take out and process 100 at a time.
6.1 Sending SMS (SMS MT)
A SMS message is sent out through OnlineCity’s gateway by submitting a HTTP GET or POST request containing the required parameters to the following URL:
https://httppost.nimta.com/sendsms
When submitting a HTTP POST request to this URL, the HTTP header Content-type must be set to application/x-www-form-urlencoded.
If any of the parameters are invalid or faulty in the initial parsing, a HTTP error code 400 is returned with a description of the error involved[11].
Example:
- Client sends HTTP POST request to:
https://httppost.nimta.com/sendsms containing the following data:
- HTTP Header Content-type must be set to application/x-www-form-urlencoded
- Required POST parameters in the request
- user
- password
- to
- smsc
- price
- text
- sessionid
- OnlineCity’s gateway responds with the following string:
- Processing:,or
- Processing: %%sessionid%%, if the sessionid parameter was included in the request. See Table 2.
- OnlineCity’s gateway sends the message to the recipient and charges him/her the requested amount.
6.1.1 POST example
POST /sendsms HTTP/1.1 User-Agent: client agent Host: httppost.nimta.com Accept: */* Content-Length: 139 Content-Type: application/x-www-form-urlencoded user=myusername&password=mypassword&to=4512345678&smsc=dk. tdc&sessionid=4512345678:20100507151010&price=6.00DKK&from =MyCompany&text=MyMessage |
6.1.2 HTTP GET/POST request parameters
All parameter names must be lowercase as described in the following tables.
All parameter values must be URL encoded (i.e. spaces replaced with "ʺ+"ʺ or "ʺ%20"ʺ etc.) according to the ISO-‐‑8859-‐‑1 character set.
Required HTTP GET/POST request parameters:
Parameter | Description |
user | The gateway username supplied by OnlineCity. |
password | The gateway password supplied by OnlineCity. |
to | The MSISDN of the recipient of the message. Example: 4512345678
...&to[]=4512345678&to[]=4587654321&to[]=4545612378&...  |
smsc | An ISO 3166-1[13] country code followed by a period and an ID representing the operator[14]. |
price15[15] | A numeric value with two decimals followed by an ISO 4217[16] currency code. Indicates the price which the subscriber is charged for the message. If the message is to be delivered free of charge the parameter should contain the zero charging price parameter value (0.00DKK for Denmark). Example: 10.00DKK |
text | An alphanumeric value representing the content of the SMS. The gateway will automatically split up messages longer than 160 characters into a number of linked messages. Each linked message is billed individually and consists of up to 153 characters. The linked messages are assembled into a single message by the receiving handset. Up to 255 messages can be linked in this way, equivalent to a maximum message length of 39015 characters.
|
sessionid | Maximum length is 30 characters – and must always be unique. Recommended format is msisdn:time where time is formatted YYYYMMDDhhmmss. Used for the purpose of tracing a session, but most importantly it allows a client to later keep track of whether a particular message was delivered or not. See Section 6.2 for further details.
|
Table 1: Required HTTP GET/POST parameters.
Optional HTTP GET/POST request parameters
Parameter | Description |
from | An alphanumeric sender address of maximum 11 characters with no special characters allowed (e.g. æøå, white space etc.). The default value is the shortcode used as a numeric value. Please note that it is not possible to directly reply to a message with an alphanumeric sender address on a mobile phone, and that not all operators support this feature.
|
wapurl | Alphanumeric URL with protocol prefixed. When the wapurl parameter is included, the message is automatically changed to a wap push message. The parameter contains the URL of the content to be accessed and must begin with a protocol prefix e.g.: http://
|
callbackurl | URL with protocol prefixed. This parameter is used by clients to receive confirmation of whether a transaction was successful or not. See Section 6.2 for a description of the callback procedure. |
class | The gateway class to use for message delivery. Several classes exist. Please refer to your gateway subscription and contact OnlineCity if in doubt. If the class parameter is not included in a HTTP POST/GET request, the gateway will default to gateway class ‘A’ (Premium/Professional). |
Table 2: Optional HTTP GET/POST parameters.
6.2 Status information callback
For many types of services it is important to keep track of whether the charging was successful and if the message was delivered successfully or not.
For this purpose OnlineCity’s gateway offers callback functionality, which allows gateway clients to get this information. See below for a detailed description of the callback service.
The callback consists of a HTTP GET request containing a sessionid and a status parameter. The URL which the callback request is sent to is defined by clients themselves by submitting the callbackurl parameter when sending messages17[17].
The callback receiver must respond with a HTTP statuscode (200 if successfully received). Callback event flow:
- The client sends a HTTP POST request containing the appropriate parameters, including optional parameters callbackurl and sessionid.
- OnlineCity’s gateway responds with the string: Processing %%session id%%
- OnlineCity’s gateway sends the message to the recipient via the SMSC specified.
- OnlineCity’s gateway receives a delivery notification from the SMSC/operator confirming that the charging was successful (or not) and the message was delivered to the mobil phone (or not). This event triggers the callback request to the callback URL specified by the client.
Callback request parameters
The parameters sent from OnlineCity to the client as HTTP GET parameters are:
Parameter | Description |
sessionid | The supplied session id from the MT push request. |
statuscode | A numeric value indicating whether the transaction was a success or why it failed. Table 6 lists the status codes used by OnlineCity’s gateway. |
Callback example:
6.3 Receiving SMS (SMS MO)
When OnlineCity’s gateway receives an MO SMS it will deliver the message to a URL defined by the gateway client owning the keyword/mediacode in the message. The MO SMS is delivered via a HTTP GET request. The client receiving service must respond to this request with a document of Content-type: text/plain (set as HTTP header) and with message body containing a simple text string cmd=asynch-no-trace.
MO SMS delivery example:
- A mobil subscriber sends a SMS with text news tilmeld to a OnlineCity shortcode: 1204.
- OnlineCity’s gateway receives the message and sends an HTTP request to the client owning the media code news: http://www.mysite.dk/receive?text=news+tilmeld&sender=4512345678&sm sc=dk.tdc&sessionid=4512345678:20100507151010&appnr=1204
- The client receiving service returns the required header and text string, which the gateway interprets as receipt for successful message delivery.
- Header: Content-type: text/plain
- Message body: cmd=asynch-no-trace
7 Appendices
7.1 Operator codes
Operator code (SOAP/HTTP) | SMSC parameter value (HTTP GET/POST) | Operator name |
1 | dk.tdc | TDC/Telmore |
2 | dk.telenor | Telenor |
3 | dk.telia | Telia |
4 | dk.unknown | Unknown. Note: Use this code if recipient operator is not known. |
6 | dk.hi3g | 3 |
Table 3: Danish Mobile Network Operator codes.
7.2 SMS codes
7.2.1 SMS status codes (SOAP/HTTP)
Status code | Description |
1 | Message delivered to recipient. |
2 | Delivered to network operator, but no status yet. |
3 | Error (see possible error code values in Table 4). |
4 | Delivery timed out and message was not delivered. |
5 | Message is not sent yet. |
6 | Insufficient funds on prepaid card. |
7 | Recipient blacklisted. |
8 | Unknown recipient. |
9 | Unknown provider error. |
10 | Message could not be delivered, typically because of error(s) in binary SMS. |
11 | Message was deleted, typically by the operator. |
Table 4: List of SMS status codes returned by gateway (SOAP/HTTP).
7.2.2 SMS error codes (SOAP/HTTP)
Error code | Description |
1 | Unknown error[18]. |
2 | Delivery timed out and message was not delivered. |
3 | Subscription account lacks the funds necessary to perform charge, message was not delivered[19]. |
4 | Recipient blacklisted by network operator. |
5 | Recipient not known by network operator. |
6 | Message could not be delivered, typically because of error in binary SMS. |
7 | Message was deleted by network operator. |
Table 5: List of SMS error codes returned by gateway (SOAP/HTTP).
7.2.3 SMS callback status code (HTTP GET/POST)
Status code | Meaning | Description |
1 | Message delivered to recipient | The message was delivered to the mobile and the charge (if any) completed. |
2 | Funds in recipient prepaid account insufficient | The subscriber’s prepaid card didn’t hold the amount necessary to complete the content charging and the message was not delivered. |
3 | Recipient blacklisted by network operator | The subscriber has been blacklisted by the operator[20] |
4 | Recipient not known by network operator - not a subscriber | The msisdn is not recognized by the operator and content charging and/or message delivery cannot be completed. |
5 | Unknown SMSC error | The content charging and message delivery failed because of an error at the SMSC. |
6 | Delivery timed out and message was not delivered | The message’s validity period expired before it was possi-‐‑ ble to deliver it to the mobile phone[21]. |
7 | Message is undeliverable | The message contains undeliverable content (usually due to illegal binary values). |
8 | Message cancelled | This covers status codes 2, 3 and 4 and is used whenever operators only return limited information when rejecting a content charged message. |
9 | Message has been deleted | The message was deleted and not delivered. |
10 | Communication error | Communication error between OnlineCity and the SMSC, the message was not successfully delivered. |
11 | Temporary operator error | The operator could not deliver the message to the end user because of a temporary error. When receiving this status code try pushing the message again, but do not do this in an infinite loop. |
Table 6: List of SMS status codes returned by gateway (HTTP GET/POST).
7.3 MMS codes
7.3.1 MMS status codes
Status code | Description |
1 | Message delivered to recipient. |
2 | Message could not be delivered to operator SMSC. |
3 | Recipient MSISDN is not recognized by the operator and content charging and/or message delivery cannot be completed. |
4 | The message contains undeliverable content. |
5 | Message delivered to operator, waiting for status. |
Table 7: List of MMS status codes used by gateway.
7.3.2 MMS error codes
Error code | Description |
1 | Message could not be sent to MMSC. |
2 | MSISDN or operator parameter malformed. |
3 | Unknown error |
4 | The message contains undeliverable (malformed) content. |
5 | Message Delivery Failed. |
6 | Message Rejected by MMSC. |
7 | Message Timed Out. |
8 | Unknown subscriber. |
9 | Insufficient funds in recipient’s account. |
10 | The subscriber has been blacklisted by the operator. |
Table 8: List of MMS error codes used by the gateway.
7.4 Gateway information sheet
To request a gateway subscription, please fill out the form on the next page and fax it to OnlineCity - our fax number is +45 6611 8309. Or scan it and email it to us.
Fields marked with * are mandatory.
Company information:
Company name: * | |
CVR. No.: * | |
Street: * | |
City: | |
Zip code: | |
Telephone nr.: * | |
Contact e-mail: * | |
Status e-mail: Gateway service announcements will be forwarded to this address. | |
Newsletter e-mail: |
Contact information:
First name: * | |
Sur name: * | |
E-mail: * | |
Mobile no |
Technical information:
IP no.: * | |||||||||||||||||||||||||||||||||||||
Incoming status URL[22]: | |||||||||||||||||||||||||||||||||||||
Incoming SMS URL[23]: | |||||||||||||||||||||||||||||||||||||
Incoming MMS URL[24]: | |||||||||||||||||||||||||||||||||||||
Please list the countries you would like to be able to send to: * | |||||||||||||||||||||||||||||||||||||
Desired media codes (”keywords”) | |||||||||||||||||||||||||||||||||||||
Premium SMS content category. Please tick appropriate box - one only. |
For more information about content categories, see http://onlinecity.dk/gateway/#api,faq |
[1] Web Service Description Language
[2] Please note that operatorCode must be assigned the appropriate value when sending charged messages – see Table 3. Also note that provision of premium charged services must act in compliance with “The Danish Framework Agreement on Mobile Content and Payment Services” - see http://www.rammeaftalen.dk.
[3] Please note that operatorCode must be assigned the appropriate value when sending charged messages – see Table 3. Also note that provision of premium charged services must act in compliance with “The Danish Framework Agreement on Mobile Content and Payment Services” - see http://www.rammeaftalen.dk.
[4] The following file extensions are valid for pictureFiles, soundFiles, videoFiles, texts, smilFiles attatchments: .jpg, .jpeg, .gif, .png, .txt, .smil, .amr, .3gp, .mp4. Files must be formatted in accordance with http://ocq.dk/mmsformats
[5] See .AMR information at http://en.wikipedia.org/wiki/Adaptive_Multi-Rate_audio_codec
[6] SMIL - Synchronized Multimedia Integration Language. See http://ocq.dk/mmsformats
[7] Please refer to TDC’s best practices for a set of guidelines on how to manage mailing lists:
http://postmaster.tdc.dk/publish.php?dogtag=f5_ms_po_po_ml
[8] For the full list of MIME types, see http://www.iana.org/assignments/media-types/index.html
[9] Web Service Description Language
[10] SMIL -‐‑ Synchronized Multimedia Integration Language. See http://www.w3.org/AudioVideo/
[11] Error message format: “The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications
%%Internal error message:%%”. Where %%Internal error message%% is the error message returned by OnlineCity’s gateway.
[12] Clients are advised to restrict GET requests to include no more than 200 recipients – this limitation does not apply to POST requests.
[13] See http://en.wikipedia.org/wiki/ISO_3166-1 for more information.
[14] Operator SMSC parameter values are listed in Table 3.
[15] Please note that operatorCode must be assigned the appropriate value when sending charged messages - see Table 3. Also note that provision of premium charged services must act in compliance with “The Danish Framework Agreement on Mobile Content and Payment Services” - see http://www.rammeaftalen.dk.
[16] See http://en.wikipedia.org/wiki/ISO_4217 for more information.
[17] See Table 2.
[18] Telia (Orange) often just returns error code ‘1’ if unable to deliver message.
[19] Sonofon returns error code ’3’ if funds on recipient’s prepaid card are below a certain threshold.
[20] This can be due to subscriber limit exceeded or the subscriber actively has disabled premium messages.
[21] This is usually due to the fact that the mobile has not been in the network for a long time (mobile phone has been turned off). The period varies between operators, but is usually between 48 - 96 hrs.
[22] See section 5.4, p. 16.
[23] See section 5.4, p. 16.
[24] See section 5.4, p. 16.