Intelecom SMS Gateway - Technical specification for integration
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
Intelecom SMS Gateway
– Technical specification for integration
C
Version 2.1.0
Last Revised March 2014
Revised By Sven Ståle Osa
Contact Information:
Technical: Sven Ståle Osa
sven.stale.osa@intele.com
Pricing and other requests: Jostein Lund
jostein.lund@intele.com
SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
1 Contents
1 Contents ......................................................................................................... 2
1.1 Revision history ....................................................................................... 3
2 Introduction .................................................................................................... 4
2.1 Overview................................................................................................. 4
2.2 Abbreviations .............................................................................................. 5
3 Sending messages using the SMS Gateway ......................................................... 6
3.1 Pricing - Non-premium and premium messages (CPA / GAS) ......................... 6
3.2 Originator ............................................................................................... 7
3.3 Validity Period.......................................................................................... 8
3.4 Message Content ...................................................................................... 8
3.5 Sessions ................................................................................................. 9
3.6 Send Window..........................................................................................11
3.7 Message Parameters ................................................................................13
3.8 Message Response ..................................................................................16
3.9 Interfaces for sending SMS messages ........................................................17
4 Receiving messages using the SMS Gateway ......................................................23
4.1 Request parameters for incoming (MO - Mobile Originating) messages ...........23
4.2 Value-added services for MO messages ......................................................26
4.3 HTTP response for MO messages ...............................................................27
4.4 SMTP MO - Receiving email (from SMS) .....................................................27
5 Receiving Delivery Report messages..................................................................28
5.2 Response for DR messages .......................................................................32
6 Contact info ...................................................................................................33
7 Appendix A : Gateway Management API ............................................................34
7.1 Interfaces for using the management API ...................................................34
7.2 Message batch management.....................................................................34
8 Appendix B: SMPP Gateway..............................................................................38
8.1 Supported PDUs ......................................................................................38
8.2 Data coding scheme ................................................................................38
8.3 Validity period ........................................................................................38
8.4 Current limitations ..................................................................................38
SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
1.1 Revision history
Revision Date Revised by Change description
2.0.1 20.12.2013 Sven Ståle Osa Updated platform
2.1.0 03.03.2014 Andreas Häber Added Revision history (chapter 1.1)
Morten Trydal Added Gateway Management API description (Appendix
Kjetil Johannesen A).
Sven Ståle Osa Added information about PID (Protocol Identifier).
Added SMPP Gateway information (Appendix B).
Added information about GAS messages to Telenor
prepaid, and GAS/ CPA messages without delivery
success (chapter 3.1)
New HTTP GET interface that obsoletes the old HTTP GET
interface.
Added information about the new interfaces for
incoming messages (MO) (see chapter 4).
New value added services for incoming messages. New
request parameters added (see chapter 4.2).
Updated chapter and table references
SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
2 Introduction
2.1 Overview
This document describes the functionality of, and explains how to integrate with, the Intelecom SMS
Gateway (SMSGW). The SMSGW is an API that enables your solution(s) to both send and receive SMS
messages. Contrary to earlier versions of SMSGW this version of the API enables you to send both
single messages and bigger batches of messages using the same API.
To be able to connect to SMSGW you will need a service configured by Intelecom with sensible
defaults and settings for your use case. The service identifiers are serviceid, as well as a username
and password. If you have an active agreement, but have not received information about these three
identifiers, please contact Intelecom Support (support@intele.com) or your customer representative.
The SMSGW has three main functionalities with corresponding APIs:
Sending one or many SMS messages from your system to end-users (MT)
Receiving SMS messages from end-users to your system (MO)
Receiving delivery reports to your system for SMS messages sent to end-users (DR)
To send SMS messages to end-users you need to integrate with one of the API via REST (XML or JSON
over HTTP POST), Web Service (with corresponding WSDL), email (SMTP), SMPP, or via HTTP GET
(with query parameters). Due to the flexibility of the REST / SOAP interfaces, we generally
recommend that you choose to integrate with one of these endpoints if possible.
To receive SMS messages (MO) or delivery reports you need to provide a service endpoint that can
receive HTTP GET or POST requests. As an alternative, you can also receive MO messages as email
messages (SMTP) or using the SMPP protocol.
Figure 1: High-level sequence diagram for basic SMSGW operations
SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
Additionally, the Gateway provides a Management API to manage messages. A description of this API
is given in Appendix A : Gateway Management API.
2.2 Abbreviations
MCC Mobile Country Code
MNC Mobile Network Code
SNO Short Number (e.g. 1960)
TTL Time To Live
UDH User Data Header
DCS Data Coding Scheme
MO Mobile Originated (incoming messages sent from end users)
MT Mobile Terminated (outgoing messages sent to end users).
CP Content Providers (Customers of Intelecom and Intelecom itself)
DR Delivery Reports (Confirmations from operators that messages have been / not have
been received by end-user)
MSISDN Mobile Station International ISDN Number
SMSGW Intelecom SMS Gateway
REST Representational State Transfer
(https://en.wikipedia.org/wiki/Representational_state_transfer)
MNO Mobile Network Operation (e.g. Telenor, Telia)
CPA Content Provider Access – An agreement between (in this case) Intelecom and the
MNO’s to be able to use four digit shortnumbers with billing possibilities.
GAS Goods And Services – Like CPA only with the possibility to sell physical goods and
services.SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
3 Sending messages using the SMS Gateway
To send SMS messages you will need to integrate with one of the APIs described below and further in
chapter 3.9. The parameters are common for the SOAP, HTTP GET and REST APIs and divided into
three groups: common parameters, basic message parameters and message settings parameters.
The message settings parameters are optional, if you do not have any special need for custom
settings you can ignore these. In the current version of SMSGW, not all parameters are available for
SMTP (email) and SMPP methods.
The available APIs for sending SMS messages are:
SOAP Webservices
REST services – XML or JSON using HTTP POST
HTTP GET (with limited functionality)
SMTP (email – with limited functionality)
SMPP
Using the SOAP and REST interfaces it is possible to send several messages in one batch, this can be
messages with different recipients and different content. All interfaces except SMTP will
synchronously return a status code and message identifier, which is a unique identifier for each
message in the Intelecom platform. The status code will give information about whether the
messages was added to the internal queue in the Intelecom system or not. The status code will not
give information about whether the message was received at the end user handset or not. In order
to check for this you need to utilize the delivery report mechanism as described later in this
document.
3.1 Pricing - Non-premium and premium messages (CPA / GAS)
When sending messages there are some alternatives concerning pricing of the messages. The
messages may be sent to the end user free of charge, meaning that the end user will not have to pay
to receive your message. Your company typically pays for this message. The other alternative is that
the end user pays a price for receiving the message; paid for on the end user’s phone bill. Often
called premium messages, you may use these for billing purposes such as paying for digital content
or services. Premium messages are not available in all countries; please contact your customer
representative for more information. In some countries, there are different payment models as well.
In Norway, you will have to use the CPA model for paying for digital services whilst the GAS model is
for billing physical goods and services. The difference between CPA and GAS is that GAS offers a
better profit for you as a customer, but each service that is to use GAS needs to be approved by the
mobile network operators. GAS and CPA requires different short numbers, meaning that you cannot
alternate between GAS and CPA messages using the same short number/ service. Using GAS you also
need to specify a service code and category as defined by the mobile network operators for each
message. You can find the listing of the Mobile Network Operator service codes in a separate
document as an attachment to this document.SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
In Norway, the supported premium rates are from 1,- to 200,- in steps of 1 NOK. Additionally it is
possible to use 1,50NOK and 6,50NOK. For GAS messages the rates are from 1,- to 500,- in steps of 1
NOK.
The price parameter uses the lowest monetary unit available, for example to send to Norwegian
recipients Norwegian “øre” is used.
Example: To send a billing message with a price of 2kr NOK to a Norwegian recipient set the price
parameter to the value 200.
Most operators use this flow when billing messages (CPA and GAS):
1) The specified amount is debited from subscriber when the operator accepts the message
(SMSC ACK) regardless of the delivery status of the message.
2) If the message could not be delivered (negative delivery status), the operator credits the
amount to the subscriber.
However Telenor by default does not credit the billing amount if the message is not successfullly
delivered to the subscriber. It is possible for Intelecom to enable automatic credit towards Telenor
subscribers for specific services.
Please also note that by default Telenor rejects GAS messages sent to Telenor prepaid customers. It
is possible for Intelecom to enable this functionality for specific services, but be aware that the
operator’s cut is higher on these messages.
Please contact your customer representative for more information about CPA and GAS, and enabling
Telenor crediting / GAS for prepaid.
3.2 Originator
When sending SMS messages the originator of the messages shows at the end users handset upon
receiving the message. Three different types of originator settings exist:
International Number – if the originator is to be an international phone number, in E164
format e.g. +4799999999
Alphanumeric Text – if the originator is to be alphanumeric text, for example “Intelecom”.
The max length of an alphanumeric originator is 11 characters and only a-z, 0-9 and the chars
‘ ‘ (space), '%', '&', '-', '+', '.' , ',' may be used as content.
Network specific – if the originator is to be shortnumber, e.g. 1960.
You must set the correct originator and originatortype parameter values according to the table in
chapter 3.7.3.1 if you want to override the default originator for your service. For example, if you
want the originator to be ‘Intelecom’, you need to set the originator parameter to “Intelecom” and
the originatortype parameter to “ALPHANUMERIC”.
Note that is not possible for an end user to reply to a message sent with alphanumeric originator.
Some phones may be able to reply to alphanumeric originators if you set alphanumeric originator
with only numbers in the content parameter. As not all phones will accept this, we recommend thatSMS GW – API Description Date: 02.03.2014 Rev: 2.1.0 you use the types for international or national numbers if you are to send a numeric string as originator. Also note that it is only possible to specify originator for messages that are received by the end user free of charge (price = 0). The reason for this is that it needs to be easy to identify who sent specific billing messages to the end user. 3.3 Validity Period It is possible to define the validity period of each message when sending SMS messages. The validity period is the period of time that delivery attempts occurs for a SMS message. Meaning that if you specify a validity time of 5 minutes, the Intelecom platform and the Mobile Network Operations will try to deliver the message for 5 minutes using the respective retry schemes. If the message cannot be delivered to the handset in this timeframe (handset turned off etc.), the message is discarded, resulting in a delivery report with a timeout status. This feature is handy if you have messages that only are valid in a certain period, such as one-time passwords or special offers with a time limitation. When specifying the validity parameter please refer to the table below: Value Validity period 0 to 143 (Value + 1) x 5 minutes 144 to 167 12h + (Value-143) x 30 minutes 168 to 173 (Value-166) x 1 day Table 1 - Valid TTL (time validity of SMS) 3.4 Message Content You can specify the content of the SMS message using the “content” parameter. For text messages, the max length of a single message is 160 characters. If you provide text that is longer than 160 characters the SMSGW will automatically split the message into concatenated text messages. When SMS messages are concatenated, some of the SMS payload is needed for the UDH, resulting in the max message length for each concatenated message being 153 characters. The Intelecom platform allows a maximum of six concatenated messages, meaning that the maximum character length of the content field is 918 characters (153*6). The GSM specification allows for a much higher number of concatenated messages but because of restrictions in the MNO SMSCs, the max limit of six concatenated messages had to be included. SMS default encoding uses 7 bits to handle a character. The GSM 03.38 specification defines the valid character sets, this being the “Basic Character Set” and the corresponding extension table as depicted below:
SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
Figure 2: Valid 7-bit GSM characters
If you use characters from the extension table, for example the EUR character (€), an escape
character is needed in addition to the character from the extension table. This means that the EUR
character counts as two characters and you will have less space available in the message.
3.5 Sessions
The Intelecom SMS platform has introduced a session mechanism that allows for two-way dialog
between a system and end-user without the need for keywords. Keywords in SMS are short text
identifiers for services on a shared short number. Example: To order weather information on the
short code 1881 you can send “WEATHER OSLO”. In this example “WEATHER” is the keyword
identifying the service, whilst “OSLO” is a parameter. Using keywords to have a SMS dialog with an
end user is often not a very user-friendly solution session. For each message, the end user will have
to provide the keyword before entering the text.
Example not using sessions: Your service desk needs to update email information for your customers.
You want to send them a SMS message requiring them to reply to the SMS with their correct email
address.
The following is an illustration of the interaction without and with the use of session.SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
Without use of sessions With use of sessions
Using session, you can also continue a conversation by providing the unique sessionid as a parameter
when sending a message, for example like this:
Currently use of sessions is only available for Norwegian
subscribers, meaning that you can only send messages with
session to end users with Norwegian subscriptions.
For the implementation of the session logic in Norway, we
have utilized a feature from the Mobile Network Operators
named subnumbering, also sometimes named recipient
range routing. With this feature, a string of numbers uniquely
identifying the session is added to the last part of the short
number resulting in a fourteen-digit originator.
As the identifier will be generated when sending the
message, it is only possible to start a session with a message
sent to the end user.
As mentioned earlier, there are two ways to access the
session for MT messages, request a new session or reuse a
previous used session.
When using a session the originatortype must be set to the
value 3 (Network specific / short number). It is not possible
to use alphanumeric or international number types as originator when using sessions.SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0 The synchronous response from the gateway will contain a session identifier, which must be stored in your system if you want to be able to identify the response from the end user when replying to the message. Figure 3: SMS Gateway high level overview 3.5.1 Start a new session Add the parameter newSession=true. This flag will tell the Gateway to start a session and you will receive a sessionid in the response. 3.5.2 Continue a session To continue an existing session the use the sessionid parameter in the request, using the sessionid previously returned in the response. Note: If you want to continue the session do not set the new session flag, if you set both the new session flag and the sessionid a new session will be generated. 3.6 Send Window If you want to schedule one or more message to be sent at some point in the future or you are about to send a very large number of messages and want to control when messages are sent to end users then you can specify the send window. The send window composite objects consists of four parameters, where the start date is the only mandatory field in the object.
SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
The start date defines when the message sending will start and the stop date defines when to stop. If
there are remaining messages in the queue after the stop date / time they are discarded. The start
and stop time can be used to create a window of time during the day where messages will be sent.
For example, if you are to send a large batch of messages that you need to send out between 2nd of
August and 4th of August 2013 and you want the end user to only receive messages in the day time,
between 09:00 and 15:00. For this example the values need to be populated as follows:
Startdate: 2013-08-02
Stopdate: 2013-08-04
Starttime: 09:00:00
Stoptime: 15:00:00
If the batch is so large that it is not possible to send all messages in one day, then the message
sending will stop at 15:00 and continue the next day at 09:00. This will continue until reaching the
stop date.
The next chapter will explain the different parameters that are available when sending messages,
chapter 3.9 will describe in more detail the different interfaces with examples.SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
3.7 Message Parameters
3.7.1 Common parameters
Serviceid Integer.
Required Identifies the service. Provided by Intelecom service desk.
username String.
required For authentication. Provided by Intelecom service desk.
password String.
required For authentication. Provided by Intelecom service desk.
batchReference String.
optional Reference ID that will be returned in the response.
message List with composite objects.
required At least one message.
3.7.2 Basic message parameters
recipient String.
required The MSISDN of the recipient. The format should follow the ITU-
T E.164 standard with a + prefix.
Example: +4792000001.
Note: This must be a valid MSISDN, that is Mobile phone
number. E.g. for Norway these numbers start with 4, 9, 58 or
59.
content String. The message payload to send, typically the message text.
required See chapter 3.4 for more details
price Integer.
optional The cost for the recipient to receive the message. In lowest
monetary unit. See chapter 3.1 for details
Example: 200 (2,- NOK)
clientReference String.
optional Arbitrary client reference ID that will be returned in the
message response.
settings Composite object.
optional For advanced message settings, see chapter 3.7.3.
3.7.3 Message settings parameters
priority Integer. Uses service value unless specified.
optional Used to prioritize between messages sent from the same
service.
1: low (slower)
2: medium
3: high (faster)
Example: 2
validity Integer. Uses service value unless specified.
optional Specifies the TTL (time to live) for the message, i.e. how long
before the message times out in cases where it cannot beSMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
delivered to a handset.
See chapter 3.3 for valid values.
Example: 173
differentiator String.
optional Arbitrary string set by the client to enable grouping messages in
certain statistic reports.
Example: pincode_messages
age Integer. Only relevant for CPA/GAS messages.
optional Defines an age limit for message content. The mobile network
operators enforces this.
IMPORTANT: If the service is a subscription service all CPA/GAS
messages must have age set to 18.
0
16
18
Example: 18
newSession Boolean.
optional Used to start a new session. See chapter 3.5 for details.
Example: true
sessionId String.
optional Used to continue an existing session. See chapter 3.5 for
details.
Example: 01bxmt7f8b8h3zkwe2vg
invoiceNode String.
optional Arbitrary string set by the client to enable grouping messages
on the service invoice.
Example: market_department
autoDetectEncoding Boolean. Default value is false.
optional Currently not in use.
Example: true
safeRemoveNonGsmCharacters Boolean. Default value is false.
optional If set to true the SMSGW will remove or safely substitute invalid
characters in the message content instead of rejecting the
message. See chapter 3.4 for details.
Example: true
originatorSettings Composite object. Uses service value unless specified.
optional Used to specify the originator. See chapter 3.7.3.1.
gasSettings Composite object. Uses service value unless specified.
optional Used if the message is a CPA Good and Services transaction. See
chapter 3.7.3.2.
sendWindow Composite object.
optional Used if the message should be queued and sent in the future
instead of immediately. See chapter 3.7.3.3.
parameter Composite object.
optional Used to specify special settings including settings for binary
message.SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
3.7.3.1 Originator settings
originatorType String.
required Specifies the type of originator. See chapter 3.2
INTERNATIONAL
ALPHANUMERIC
NETWORK
Originator String.
Required Depends on the originatorType.
Example: +4799999999, Intelecom, 1960
3.7.3.2 GAS settings
serviceCode String.
required Identifier for the category of Goods and services. See chapter
3.1 for more information. See separate attachment to this
document for valid parameter values for service codes.
Example: 05008
Description String.
Optional Further details of the Goods and services. The description may
occur on the end-user invoice (together with category) for
certain Mobile Network Operators.
Example: Aftenposten
3.7.3.3 Send window
startDate Date.
required The date to send the message. See chapter 3.6 for more info.
Example: 2013-12-24
startTime Time.
optional The time of day to start sending the messages. See chapter 3.6
for more info.
Example: 13:00:00
stopDate Date.
The date to stop sending the message if the message is still in
enqueued. See chapter 3.6 for more info.
Example: 2013-12-25
stopTime Time.
optional The time to stop sending the message if the message is still
enqueued. See chapter 3.6 for more info.
Example:12:00:00
3.7.3.4 Parameter
key String.
required Example: dcs
value String.
required Example: F5
Valid parametersSMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
businessModel
DataCodingScheme Used to specify the message encoding to be used.
This property is searched for if {@link
GwMessage#isAutoDetectEncodingEnabled()} returns false.
Dcs Data coding scheme for message
Specify what data coding scheme is used for this message.
Defined in 3GPP TS 23.038 ch. 4.
Should be one octet (2 hex digits). For example '15' or 'F5'.
Udh User Data Header
If non-empty will set the TP-User Data Header Indicator (UDHI)
for the message.
Defined in 3GPP TS 23.040 ch. 9.2.3.24 TP-User Data (TP-UD).
Pid Protocol Identifier – replace short message feature
A message containing a PID will replace an existing message
having the same PID. Valid values are 65 – 71.
Note: It will only be replaced if the service center address and
originating address match the previous message.
3.8 Message Response
All interfaces except SMTP will return a synchronous response with at least the fields for status code,
status message and message identifier populated per message. All available fields in the response are
described in table 4 below.
3.8.1 Message Response
Parameter Description
batchReference Reference ID for the request. Either the value provided by the client in
the request or an automatically generated ID if no such value is set.
messageStatus List of composite objects. At least one element.
Table 2 – Message Response
3.8.2 Message status
Parameter Description
Statuscode See table 4 belowSMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
statusmessage Textual information about status, e.g. which parameter failed
clientReference The client reference ID if specified in the request
Recipient The recipient. NOTE: The SMSGW runs all numbers through a number
parser and so the recipient in the response may be in same format than
in the request, i.e. “+47 41 00 00 00” will be “+4741000000” in the
response. Use the clientReference if you need to match messages in the
request and response.
messageId Message ID (used as reference for delivery reports).
sessionId Sessionid for a session, see chapter 3.5. Only returned if newSession
parameter is set to true, or if you are specifying a sessionid.
sequenceIndex The messages in the response will always be in the same order as in the
request. The sequence index is a convenience counter starting at 1.
Table 3 – Message Status
3.8.3 Status codes
Statuscode Value Description
MESSAGE_DELIVERED_OK 1 OK.
ACCESS_ERROR 2 No access. Authentication failed.
ILLEGAL_ACTION 3 An illegal operation was tried.
ILLEGAL_SERVICE 4 An illegal service was tried.
SYNTAX_ERROR 5 The request contained syntax errors.
INTERNAL_ERROR 6 An internal error occurred in the gateway.
Table 4 – Status codes
3.9 Interfaces for sending SMS messages
3.9.1 Web service (SOAP)
3.9.1.1 How to connect
The web service interface is defined by the WSDL and can be retrieved from:
https://smsgw.intele.com/gw/ws/SMSGatewayV10?wsdlSMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
3.9.1.2 Request Example
1000
intelecom
xdyf3bf2
+4741000000
This is a message from Intelecom.
0
Intelecom
Alphanumeric
3.9.1.3 Response Example
1
Message enqueued for sending
+4741000000
7a0081hfe800
1
3.9.2 REST
3.9.2.1 How to connect
The REST interface supports both XML and JSON over HTTP POST on the following URL:
https://smsgw.intele.com/gw/rs/sendMessagesSMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
3.9.2.2 Regarding content types
The REST endpoint for sending messages supports both JSON and XML. To specify the content type of
the request you must specify the “Content-Type” header and to specify the content type of the
response you must specify the “Accept” header. Valid values are “application/json” or
“application/xml”.
3.9.2.3 Encoding
The content encoding should be UTF-8
3.9.2.4 XML Schema definition
The XML request and response uses the same schema used in the WSDL definition for the SOAP
interface:
https://smsgw.intele.com/smsgw/SMSGateway?wsdl
3.9.2.5 XML Request Example
1000
intelecom
xdyf3bf2
+4741000000
This is a message from Intelecom.
0
Intelecom
Alphanumeric
true
3.9.2.6 XML Response Example
1
Message enqueued for sending
+4741000000
760081j04w00
1SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
3.9.2.7 JSON Request Example
{
"serviceId":1000,
"username":"intelecom",
"password":"xdyf3bf2",
"message":[
{
"recipient":"+4741000000",
"content":"This is a message from Intelecom.",
"price":0,
"settings":{
"originatorSettings":{
"originator":"Intelecom",
"originatorType":"ALPHANUMERIC"
},
}
}
]
}
JSON Response Example
{
"messageStatus":[
{
"statusCode":1,
"statusMessage":"Message enqueued for sending",
"clientReference":null,
"recipient":"+4741000000",
"messageId":"760081j1ll00",
"sessionId":null,
"sequenceIndex":1
}
]
}
Important note for consuming responses
The REST interface supports both XML and JSON so you will need to specify what kind of request you
are sending by using the “Content-Type”-header (application/xml or application/json). Most
framework handles this correctly without any configuration.
More importantly, the SMSGW will not know what format to respond with and it is important that
you specify this. This is done by setting the “Accept”-header. Many frameworks handles this
correctly, but for some you need to explicitly configure this.
3.9.3 HTTP GET
The content provider may invoke the SMS Gateway (Gateway) using HTTP GET queries. Though not
as flexible as its SOAP / REST counterparts, it is a very easy protocol to integrate and to send simple
test messages from for example your browser. If you need to integrate a third party product to SMS
this protocol is often the only option. However, as mentioned earlier we recommend that you
integrate using SOAP or REST if you have the possibility to do so.SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
3.9.3.1 How to connect
The web address for the production system is smsgw.carrot.no and the Gateway servlet is accepting
GET requests on the URL:
http://smsgw.intele.com/smsgw/rs/sendMessages?type=1&serviceid=...
3.9.3.2 Parameters
Parameter names are case sensitive. For example for the Service ID parameter the correct spelling is
“serviceId“. Incorrect examples are “serviceid”, “serviceID”, “SERVICEID”, “serViceID”, etc.
Common parameters (see section 3.7.1 above) do not need any prefix, e.g., “username” and
“serviceId”.
A dot (“.”) notation is used to specify nested properties, such as message[0].settings.priority.
Similar to the other interfaces the HTTP GET interface supports sending multiple messages. Message
parameters must therefore be prefixed with message[n] (n is a zero-based index for the message).
The first message is therefore message[0]. For example to set the message content for the first
message the query parameter key name would be message[0].content. Similarly, setting the
recipient becomes message[0].recipient.
3.9.3.3 Encoding
The request URI must be percent encoded, following RFC2396 (“Uniform Resource Identifiers (URI):
Generic Syntax”), and use UTF-8.
For example, a message with the content “Dette er en melding med ÆØÅ I seg” should be encoded
as:
Dette%20er%20en%20melding%20med%20%C3%A6%C3%B8%C3%A5%20i%20seg.
3.9.3.4 Request Example
Simple message:
http://smsgw.intele.com/smsgw/rs/sendMessages?serviceId=99999&
message[0].recipient=%2B4799999999&message[0].content=Dette+er+en+ny+test.&
username=test&password=test
Note that +47 becomes %2B47 when URL encoded.
Message with originator setting:
http://smsgw.intele.com/smsgw/rs/sendMessages?serviceId=999899&username=test&password=te
st&message[0].recipient=+4799999999&message[0].content=Test&message[0].settings.originatorSe
ttings.originatorType=ALPHANUMERIC&message[0].settings.originatorSettings.originator=IntelecomSMS GW – API Description Date: 02.03.2014 Rev: 2.1.0 Message with PID parameter setting: http://smsgw.intele.com/smsgw/rs/sendMessages?serviceId=99999& username=test&password=test&message[0].recipient=%2B4799999999&message[0].content=Dette +er+en+ny+test.&message[0].settings.parameter[0].key=pid&message[0].settings.parameter[0].valu e=68 3.9.3.5 Response Example The response format is the same as for the REST interface described above. 3.9.4 SMTP – Sending SMS using email The SMS gateway also provides email as an alternative channel for sending / receiving sms messages. This channel is limited in what kind of messages it can send. The recipients in the mail message are the receivers of the message in the format: -@smsmail.intele.com The subject field is ignored (however, it may be configured to be appended to the message). The body of the email is used as the sms content. There is a maximum limit of 918 characters of the sms, and sms’ that extend one sms (160 characters) are concatenated and sent as single message to the phone (with many fragments).
SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
4 Receiving messages using the SMS Gateway
If you want to enable end users to send SMS messages to your solution you will need to set up a
service able of receiving HTTP GET requests or HTTP POST requests through a REST API with either
JSON or XML formatting. Whilst the HTTP GET API will one request for each message, the REST API
will accumulate batches of messages and only send 1 request pr second.
The SMSGW will invoke your HTTP service when MO- and DR-messages are slated for delivery to your
server. The URL of your service must be provided to Intelecom Service Desk (support@intele.com)
for proper configuration of the service. You also need to provide information about which API you
prefer for incoming (MO) messages. (HTTP GET, HTTP POST with JSON or HTTP POST with XML).
4.1 Request parameters for incoming (MO - Mobile Originating) messages
The input parameters available in the request are:
CP parameter name Description
Messageid Unique messageid generated by the platform for this message. The
messageid is generated by the channel container.
Sno The shortnumber associated with this message.
Command The pattern that causing the routing to the service. Usually a keyword e.g.
“TLF”
Content The content of the SMS message. For regular text SMS messages this is a
plain text, for binary messages this will be hex content.
strippedcontent Same as content, but keyword is stripped from beginning of content.
Timestamp This parameter indicates when the message entered the Intelecom SMS
platform.
Note: Format:
yyyyMMdd HH:mm:ss
Sctimestamp Service Center time stamp represents the time the operator SMSC received
the message.
Note: Format:
yyyyMMdd HH:mm:ss
Serviceid This parameter identifies the service that has been identified for this service.
Servicename The name of the service
originator The originator of the SMS message (in international format).
Mcc The Mobile Country Code for originator MSISDN (e.g. 242 – Norway). See
table 6
Mnc The Mobile Network Code for originator MSISDN (e.g. 2 – NetCom). See table
6
Sessionid This contains the session identifier that this message is a reply to, this
parameter allows you to bind an outgoing and incoming message together.
This field will be empty if the message does not belong to a session
Type Always=1 (parameter used to distinguish between MO and DR). Note that
this parameter is only available on the HTTP GET interface.
Table 5: Input parameters for MO messagesSMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
Operator MCC MNC
Telenor 242 1
NetCom 242 2
Teletopia 242 3
Network Norway 242 5
Ventelo 242 7
TDC Norway 242 8
Tele2 Norway 240 7
Table 6: List over MCC / MNC Values
4.1.1 HTTP GET example of a valid MO URL:
http://mogw.example.com/incomingaction?messageid=[messageid]&sno=[sno]&comm
andtype=[commandtype]&command=[command]&content=[content]×tamp=[timest
amp]&sctimestamp=[sctimestamp]&serviceid=[serviceid]&originator=[originator
]&mcc=[mcc]&mnc=[mnc]&sessionid=[sessionId]&type=[type]&servicename=[servic
ename]
The attributes in the SMS-MO message will substitute the corresponding part of the template.
4.1.2 HTTP POST example with JSON formatted data:
{
"mo":[
{
"messageid":"7a02c0000f00",
"serviceid":123,
"servicename":"Testtjeneste",
"sno":"1960",
"originator":"+4799999999",
"mcc":242,
"mnc":1,
"content":"Kodeord Testmelding 1",
"command":"Kodeord",
"strippedcontent":"Testmelding 1",
"type":1,
"timestamp":"20140206 11:45:33",
"sctimestamp":"20140206 11:45:33",
"sessionid":"1234567890"
},
{
"messageid":"7a02c0000g00",
"serviceid":123,
"servicename":"Testtjeneste",
"sno":"1960",
"originator":"+4744444444",SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
"mcc":242,
"mnc":1,
"content":"Kodeord Testmelding 2",
"command":"Kodeord",
"strippedcontent":"Testmelding 2",
"type":1,
"timestamp":"20140206 11:47:33",
"sctimestamp":"20140206 11:47:33",
"sessionid":"1234567890"
}
]
}
4.1.3 HTTP POST example with XML formatted data:
7a02c0000f00
123
Testtjeneste
1960
+4799999999
242
1
Kodeord Testmelding 1
Kodeord
Testmelding 1
1
20140206 12:41:13
20140206 12:41:13
7a02c0000g00
123
Testtjeneste
1960
+4744444444
242
1
Kodeord Testmelding 2
Kodeord
Testmelding 2
1
20140206 12:43:15
20140206 12:43:15
Note that the HTTP POST version of the MO Gateway will trigger every second and send any
messages (MO / DR), present in the queue. This means that you can expect that you sometimes will
get XML or JSON messages that contain more than one message / delivery report.SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
4.2 Value-added services for MO messages
For Toolbox customers it is possible to enable automatic retrieval of customer data through Toolbox
services. Currently the services offers integration for directory inquiries and network lookup.
It is a requirement that the toolbox service is registered in the same service group as the SMS
Gateway service. In addition, VAS must be enabled in the SMS gateway service parameters.
This integration extends the set of input parameters available in the HTTP GET request given above
with the following:
VAS type CP parameter name Description
Record type. See the table below for mapping the code to
types.
Code Type Description
0 Unset No result received from the directory
inquiry service provider
di_recordtype 1 Person Personal record
2 Business Business / company / organizational
record
3 Hybrid Mixed result data
4 Unknown Type is unknown
di_firstname First name, if person
di_middlename Middle name
di_lastname Last name, or company name if record type is Business
Gender type. See the table below for mapping the code to
types.
Code Type Description
0 Unset No result received from the directory
Directory inquiry service provider
Inquiry di_gender 1 Male
2 Female
3 Hybrid
4 Unknown
di_birthdate Person - Birth date
di_streetname Address - Street name
di_house_number Address - House number
di_entrance Address - House entrance
di_zip Address - Post zip number
di_zip_location Address - Post zip location
di_municipiality Address - Municipality
di_country Address - Country
di_orgnr Business – Organization number
di_boxtext Postbox – Name on postbox
di_boxnumber Postbox – Number
di_boxoffice Postbox - Office
di_boxzip Postbox – Post zip code
di_boxcity Postbox – Post zip location / citySMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
VAS type CP parameter name Description
di_boxcountry Postbox - Country
di_coord_matchtype Coordinate – match type
di_coord_xpos Coordinate – X Position
di_coord_ypos Coordinate – Y Position
msisdn_errorcode Error code
msisdn_errortext Error description
MSISDN msisdn_mnc Mobile network code
Network msisdn_mcc Mobile country code
lookup msisdn_spid Service provider ID
msisdn_spname Service provider name
msisdn_cc Country code
Table 7: Extra input parameters for VAS MO messages
4.2.1 HTTP GET example of a valid MO URL with VAS parameters:
http://mogw.example.com/incomingaction?messageid=[messageid]
&originator=[originator]&streetname=[di_streetname]&date_of_birth=[di_birth
date]&mnc=[msisdn_mnc]&mcc=[msisdn_mcc]
The attributes in the SMS-MO message will substitute the corresponding part of the template.
4.3 HTTP response for MO messages
Your server must respond to the HTTP request with a HTTP 200 header response, any other response
code will by default cause a retry of delivery.
If the gateway does not receive a HTTP 200 acknowledge it will try resending the message to the CP.
The MessageId will be the same as the previous attempt. Normally the mo-request will wait 60
seconds for the HTTP 200 response. If the your server does not respond within the time limit the
message is marked as undelivered and the gateway will try to resend the message later.
IMPORTANT: Respond as fast as possible on the request before you start doing heavy business logic.
It is strongly recommended to use an asynchronous model where you acknowledge the message and
add it to an internal queue for example database. Do not use a synchronous model where you do all
the business logic and then send a response message. Our experience is that customers that fail to
respond within the time limit of the request often experience that their messages are queued. This is
because the system will use some of its resources to resubmit messages that your server has
received earlier but failed to acknowledge. The higher the traffic peaks, the more significant this
problem will be.
4.4 SMTP MO - Receiving email (from SMS)
It is also possible to configure the SMSGW to format and send an incoming SMS message as an email
message.SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
The email address to send incoming SMS messages to will need to be provided to Intelecom service
desk. The end user mobile number as well as the incoming serviceid is by default set as the originator
of the message (this is highly configurable though), so it is fully supported to reply to a email to
respond immediately.
The SMS message content will come in the email body, but is also highly configurable.
By saying highly configurable, we mean that ANY field in the message (see 4.1) can be substituted in
any of the fields in the email.
IE:
Sender: [originator]-[serviceid]@sms.carrot.no
Subject: SMS message from Intelecom: [originator]
Message: This is a message from Intelecom SMS platform. User sent: [content]
5 Receiving Delivery Report messages
If you need to know whether a specific message is received by the end users handset or not you will
need to implement a server side service able of receiving HTTP GET requests or HTTP POST requests
through a REST API with either JSON or XML formatted content.
This is an asynchronous operation and you will need to implement a mechanism for storing
messageid and/ or batchReference and/ or clientReference from sent (MT) messages in order to
associate an incoming delivery report to the correct MT message.
The input parameters available in the HTTP GET request for delivery reports are:
CP parameter name Description
Messageid The messageid of the original message this report is for.
customerbatchreference The batchReference of the MT message. A system batch reference is
generated if you do not specify one when sending the MT message. See
also chapter 3.7.1
customermessagereference The clientReference you specified in the MT message. See also chapter
3.7.2
Serviceid This parameter identifies the service that has been identified for this
service.
servicename The name of the service
Mcc The Mobile Country Code for originator MSISDN (e.g. 242 – Norway).
See table 6
Mnc The Mobile Network Code for originator MSISDN (e.g. 2 – NetCom). See
table 6
Statuscode Internal statuscode. See table 11
statusdescription Brief description of the internal statuscode (primarily used for logging).
extstatuscode External statuscode (from mobile network operator)
extstatusdescription Brief description of the external statuscode (primarily used for logging).
Type Always=6 (parameter used to distinguish between MO and DR). Note
that this parameter is only available on the HTTP GET interface.
Table 8: Input parameters for DR messagesSMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
Value Description Use
0 Operation successful Operation successful.
350 Invalid network provider Non-existing or invalid network provider
354 Illegal bulk message The account cannot send bulk messages
355 Illegal tariff Undefined or illegal tariff for account
360 Syntax error in message When a message contains a syntax error reported
by operator (SMSC)
361 Validity period expired Validity period expired without recipient receiving
the message
362 Message timed out The message timed out before recipient received
message
363 SMSC operation failed The message contains errors and the SMSC is
unable to process the message.
370 Unspecified error
371 Transmit error The message was cancelled due to transmit errors
towards the SMSC.
380 Invalid Login Invalid or client identifier Illegal login towards operator.
368 Not connected to SMSC Not connected/not logged in to SMSC.
369 SMSC Specific error Some error condition occurred on the SMSC side.
351 Unknown recipient number Recipient unknown (do not belong to current
network operator) or illegal recipient.
356 Customer temporary barred Customer is barred for an unspecified for an
unspecified amount of time
357 Customer permanently barred
358 Subscription barred for overcharged The subscriber has explicit chosen to be
messages. permanently barred from receiving premium rate
messages. The recipient is only allowed to receive
messages that are free of charge.
359 Age limit exceeded The subscriber is not old enough to receive the
CPA / GAS message. Should only occur when an
ageLimit is set for a message.SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
364 Subscription temporary not reachable For some reason, the subscription number cannot
be reached for the moment.
390 Message sent but not billed The message was sent successfully, but not billed
(either it was not supposed to, or billing failed)
385 Illegal function The message is stopped because of trying to use a
function that requires a special agreement.
386 Message billed but not sent The recipient did not receive the message, but
was billed for the message.
650 Database error Database problems, error connecting to Database
or other database related problems
652 Missing system data Crucial system data not found cannot perform
task without this data.
651 No route found MT route not found.
653 Unexpected error Unknown unexpected data. Please see error
message in the message object
654 Invalid MSISDN MSISDN is not recognized as a valid number
655 Inactive service Mt router barred message, service is inactive.
Discontinue routing procedure.
Table 9: Internal status codes
5.1.1 HTTP GET example of a valid URL for receiving delivery reports:
http://drgw.xx.no/reportaction?messageid=[messageid]&statuscode=[statuscode]&statusdescription
=[statusdescription]&extstatuscode=[extstatuscode]&extstatusdescription=[extstatusdescription]&c
ustomerMessageReference=[customermessagereference]&customerBatchReference=[customerbatc
hreference]&serviceid=[serviceid]&servicename=[servicename]&mcc=[mcc]&mnc=[mnc]&type=[typ
e]
The attributes in the SMS-MO message will substitute the corresponding part of the template.
5.1.2 HTTP POST example with JSON formatted data:
{"dr":[
{
"messageid":"6y034000cy00",
"customerbatchreference":"MyBatch001",
"customermessagereference":"MyRef123",
"serviceid":123,
"servicename":"Testtjeneste",
"mcc":242,SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
"mnc":1,
"type":6,
"statuscode":0,
"statusdescription":"OK. Message processed successfully.",
"extstatuscode":"0",
"extstatusdescription":"Delivered"
},
{
"messageid":"6y034000dy00",
"customerbatchreference":"MyBatch001",
"customermessagereference":"MyRef124",
"serviceid":123,
"servicename":"Testtjeneste",
"mcc":242,
"mnc":1,
"type":6,
"statuscode":0,
"statusdescription":"OK. Message processed successfully.",
"extstatuscode":"0",
"extstatusdescription":"Delivered"
}
]}
5.1.3 HTTP POST example with XML formatted data:
6y034000cy00
MyBatch001
MyRef123
123
Testtjeneste
242
1
6
0
OK. Message processed successfully.
0
Delivered
6y034000dy00
MyBatch001
MyRef124
123
Testtjeneste
242
1
6
0
OK. Message processed successfully.
0SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
Delivered
5.2 Response for DR messages
The CP must respond to the HTTP request with a HTTP 200 header response, or any other header
responses to cause a retry of delivery.SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
6 Contact info
Content providers may contact Intelecom’s Customer Support for access to the test system from
Internet and initial service setup for production. Intelecom’s Customer Support will also contact point
first line service.
Contact info is:
Email: support@intele.com
Phone: +47 03050, IVR choice 1
Required parameters from Content Provider are:
HTTP and WebService access from CP to Intelecom SMS Gateway:
IP address of calling CP system
HTTP access from Intelecom SMS Gateway to CP:
URL with template for SMS-MO messages
URL with template for SMS-DR messages
TCP/IP Connection Timeout towards CP in seconds (default 10)SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
7 Appendix A : Gateway Management API
This API provides functionality to manage messages and receive status from the Gateway.
Functionality is divided into functional groups described below.
The API is available from web service and REST interfaces, similar to the SMS sending API. It also uses
the same triplet of service identifisers (service id, username and password) as explained in chapter
2.1 above.
7.1 Interfaces for using the management API
The management API is available as a web service and REST service.
7.1.1 Web service (SOAP over HTTP)
The web service interface is defined by the WSDL and can be retrieved from:
https://smsgw.intele.com/mgmt/ws/GatewayManagementV10?wsdl
7.1.1.1 Error codes
Value Description
1000 No batch found matching the given customer batch reference for this service
In addition the status codes for the SMS Gateway API are also used, e.g., for authorization errors.
7.1.2 REST
The REST interface supports both XML and JSON over HTTP with the following base URI:
https://smsgw.intele.com/mgmt/rs/service/{serviceid}
Parameter definition
Type Name Mandatory Description
Path {serviced} Y Identifies the service to be managed.
Example
https://smsgw.intele.com/mgmt/rs/service/100
Each API documented below defines the URIs used for the request based on this base URI.
Use the HTTP Accept header to specify what Content-Type your client prefers for the response. XML
(MIME-type: text/xml) and JSON (MIME-type: application/json) are supported.
Note that HTTP Basic authentication (IETF RFC 2617) is used for authentication.
7.2 Message batch management
These APIs allow managing batches of messages sent that have been throttled (queued for sending in
the Intelecom platform). .SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
Base URI path: /batch/
7.2.1 Stop batch
Stop messages that previously have been sent that are throttled. If sending has started for the batch
only those messages still throttled will be stopped.
Request URI path: /batch/{batch-reference}
Request method: DELETE
Request parameters
Type Name Mandatory Description
Path {batch- Y Identifies the batch to be managed. Set as the
reference} batchReference parameter when sending messages (see
chapter 3.7.1 above).
Example
https://smsgw.intele.com/mgmt/rs/service/100/batch/
my-batch
A request that references batch “my-batch” of
service with id 100.
Response parameters
Type Name Mandatory Description
Entity StopBatchResponse Y Response entity
StopBatchResponse Y Service id for the response.
#ServiceId Same as provided in the
request.
StopBatchResponse Y Client batch reference for the
#ClientBatchReference response. Same as provided in
the request.
StopBatchResponse Y List of messages that were
#StoppedMessages stopped. Other messages in
the batch may have been
sent.
StopBatchResponse Y Unique messageid generated
#StoppedMessages by the platform for this
#MessageId message. The messageid is
generated by the channel
container.SMS GW – API Description Date: 02.03.2014 Rev: 2.1.0
StopBatchResponse N Customer’s message
#StoppedMessages reference for the message, if
#CustomerMessageReference
given.
Status codes
Statu Status description Description
s
code
200 OK Request executed successfully. See response
entity for detailed results.
401 Unauthorized The pair of username and password given is
not authorized to manage the provided
service id.
Note that username and password must be
provided per the HTTP Basic authentication
standard (IETF RFC2617).
404 Not Found The requested batch cannot be found.
Ensure that the batch reference is correct for
the given service.
500 Internal Server Error An unexpected error has occurred. For
example invalid request uri.
7.2.1.1 Examples
7.2.1.1.1 Web service
Request
1000
intelecom
xdyf3bf2
my-batch-reference
ResponseYou can also read
