SMS Gateway
Interface Description
WEB SERVICE v1.0

Document nameWEB SERVICE v1.0
Document numberEAL10003SIS
Revision1.08
AuthorMartin Kristell
Date2016-05-10
Information classOpen Information
ReviewerJonas Rexeke
Review date2016-05-10
CompanySPIRIUS AB
VAT/REG number556788-4183
Postal addressBox 67
371 21 KARLSKRONA
Telephone number+46 (455) 65 55 00
Fax number+46 (455) 65 55 19
Home pagewww.spirius.com

© Copyright SPIRIUS AB 2018

The contents of this document are subject to revision without notice due to continued progress in methodology, design and manufacturing. SPIRIUS AB shall have no liability for any error or damages of any kind resulting from use of this document.

1. INTRODUCTION

1.1 scope

This document describes the SMS Gateway Web Service Interface. It describes the basics of how to use the SOAP-based Web Service Interface (from now on referred to as ‘Interface’) and provides a list of available functions with their parameters and return values.

This document is intended for application developers and/or integrators. Basic knowledge of the SOAP and WSDL protocols are assumed.

2. WEB SERVICE INTERFACE

2.1 Usage

To send a message using the Interface, the client creates and sends a SOAP request containing both login credentials and the actual message and its recipients. The fact that login credentials are used in every single request eliminates the need of separate login and logout requests to setup and tear down sessions.

Upon reception of the SOAP-request, SMS Gateway validates the credentials and the rest of the parameters. If all checks are passed SMS Gateway sends the message to all numbers specified and responds with a SOAP-response containing a list of transaction id:s, one for each sent message. Should there be anything wrong with the request, it will be rejected and a SOAP-fault is sent back to the client indicating the nature of the error.

If a delivery report is requested, the client can either poll for the status by making a SOAP-request to SMS Gateway, or SMS Gateway can send a HTTP GET-request to the client indicating the outcome of the message (see document “SMS Gateway Interface Description HTTP v1.0”).

It is recommended that the client uses SSL-encryption to secure the connection.

2.2 SOAP Functions

2.2.1 SendMessage()

This function sends a SMS to one or more recipients.

Parameters

NameMandatoryTypeDescriptionExample
UserYesStringUsername of client.“myuser”
PassYesStringPassword of client.“mypassword”
ToYesStringRecipients of the message, specified as a comma separated list of MSISDN numbers in International format with preceding ‘+’ characters. Maximum number of MSISDN numbers in the list are 10.“+46701234567, +46707654321”
MsgYesStringThe actual message.“Hello+world”
FromNoStringSender of message. If not specified this parameter defaults to client preset name or number.“+46701234567”
“MyCompanyAB”
ExtIdNoStringExternal Id. To be able to tag each SMS with a reference string of your choice, e.g. a project name. You can then get a monthly report with the number of SMS sent per project. Max 20 characters us-ascii only.“MyId”

Return Values

NameTypeDescriptionExample
TransactionIdsArray(String)A list of transaction ids for the sent messages.[“6ef63afc-6e8e-4c7d-9427-58e030df0347”,” 6ef63afc-6e8e-4c7d-9427-58e030df0348”]

SOAP Faults

ResponseDescription
1 Internal ErrorSomething unexpected happened. Contact the System Administrator.
2 Incorrect username or passwordInvalid credentials.
3 Too many numbers in 'to'-listMaximum number of recipient phone numbers are 10
4 Incorrect phone number in 'to'-listOne or more of the recipient phone numbers are malformed
5 Rate limit exceededThe rate limit has been exceeded. The client must slow down their request rate.

2.2.2 SendMessageAdvanced()

This function sends a SMS to one or more recipients with the possibility to specify details about how the message will be sent.

Parameters

NameMandatoryTypeDescriptionExample
UserYesStringUsername of client.“myuser”
PassYesStringPassword of client.“mypassword”
ToYesStringRecipients of the message, specified as a comma separated list of MSISDN numbers in International format with preceding ‘+’ character. Maximum number of MSISDN numbers in the list are 10.“+46701234567, +46707654321”
MsgYesStringThe actual message. If message type is binary this parameter should be given in hexadecimal form.“Hello+world”
MsgTypeNoStringMessage type. ‘0’=Text , ‘1’=Flash, ´3´=Binary. Defaults to ‘0’. Additional messages types will be available in later release.“0”
FromNoStringSender of message. If not specified this parameter defaults to client preset name or number.
Maximum of characters accepted depending FromType:
’N’ = 15 characters
’I’ = 15 characters
’S’ = 6 characters
’A’ = 11 characters
Only characters 0-9 and ‘+’ is allow for FromType ‘N’, ‘I’ and ‘S’. Characters 0-9, A-Z, a-z and whitespace are allowed for FromType ‘A’.
“+46701234567”
“MyCompanyAB”
FromTypeNoStringFormat of the ‘From’-parameter. Defaults to ‘I’=International.
Available formats are ‘N’=National, ‘I‘=International, ‘S’=Short and ‘A‘=Alphanumeric.
“I”
ExtIdNoStringExternal Id. To be able to tag each SMS with a reference string of your choice, e.g. a project name. You can then get a monthly report with the number of SMS sent per project. Max 20 characters us-ascii only.“MyId”
DLRNoStringDelivery Report requested. ‘0’=NO, ‘1’=YES. Defaults to ‘0’.“1”
RouteTypeNoStringRoute Type. Specifies routing rule. Currently only ‘Standard’ is available.“Standard”
VPNoStringValidity Period. Number of minutes that message is valid. Defaults to 4320 minutes (3 days). Maximum value is 20160 minutes.“1440”
FDANoStringFirst Delivery Attempt. The preferred time when message delivery should first be attempted. The parameter is given in absolute time.“2009-12-01+12 %3a00%3a00”
TZNoStringTime Zone. Specifies in which time zone the FDA-parameter time is given. Defaults to Europe/Stockholm. See appendix 4.4 for a list of available time zones“Europe%2FLondon”
UDHNoStringUser Data Header. This parameter is given in hexadecimal form. For advanced users. For future use.“050003FF0201”
DCSNoStringData Coding Scheme. The parameter is used when message type is binary. Acceptable values are 0-255.“0”
ERNoStringEnable reply. ‘0’=NO, ‘1’=YES. Defaults to ‘0’. For future use.“1”
PrioNoStringMessage priority, ranging from 1 (highest) to 3 (lowest). Defaults to ‘2’. For future use.“1”
CharSetNoStringCharacters Set. Specifies the character set for the message of the request. Defaults to ‘ISO-8859-1’. See appendix A for supported character sets.“ISO-8859-1”
ConcatNoStringConcatenate ‘0’=NO, ‘1’=YES. Set to ‘1’ if message that results in more than one SMS should be concatenated by the end user terminal. Defaults to ‘1’.“0”
MaxMsgsNoStringMaximum number of concatenated SMS used to carry the message. Defaults to ‘10’ which is also the maximum limit imposed by mobile networks. If the value is set to ‘0’ no length check is performed by SPIRIcom but mobile network limitations are still in place. This parameter should be set to a value in the range 0..10 by users who wants to cap the maximum cost for a single message. This parameter only applies if Concat to ’1’.“3”

Return Values

NameTypeDescriptionExample
TransactionIdsArray(String)A list of transaction ids for the sent messages.[“6ef63afc-6e8e-4c7d-9427-58e030df0347”,” 6ef63afc-6e8e-4c7d-9427-58e030df0348”]

SOAP Faults

ResponseDescription
1 Internal ErrorSomething unexpected happened. Contact the System Administrator.
2 Incorrect username or passwordInvalid credentials.
3 Too many numbers in 'to'-listMaximum number of recipient phone numbers are 10
4 Incorrect phone number in 'to'-listOne or more of the recipient phone numbers are malformed
5 Rate limit exceededThe rate limit has been exceeded. The client must slow down their request rate.

2.2.3 GetMessageStatus()

This function returns the current status of a sent message.

Parameters

NameMandatoryTypeDescriptionExample
UserYesStringUsername of client.“myuser”
PassYesStringPassword of client.“mypassword”
TransactionIdYesStringTransaction id for a sent message.“6ef63afc-6e8e-4c7d-9427-58e030df0347”

Return Values

NameTypeDescription
MessageStatusObject (
CodeInteger1=Delivered, 2=Pending, 3=Failed, 4=Timeout
TextStringDELIVERED, PENDING, FAILED, FAILED_TIMEOUT
)

SOAP Faults

ResponseDescription
1 Internal ErrorSomething unexpected happened. Contact the System Administrator.
2 Incorrect username or passwordInvalid credentials.
3 Unknown transaction idThe specified Transaction Id doesn’t exist.

2.3 Delivery Reports

As an alternative to polling for the delivery status of a message, SMS Gateway can make a HTTP request to the client’s server. For more information, see document “SMS Gateway Interface Description HTTP v1.0”.

2.4 WSDL

This table defines which URL to use to retrieve a WSDL-file for the Web Service. Please note that this information may be subject to change and that different information may have been provided along with your account details.

Service (Mandatory)URL
Web Servicehttp://web.spiricom.spirius.com:56000/v1_0/.wsdl
Web Service using SSLhttps://web.spiricom.spirius.com:56001/v1_0/.wsdl

3. APPENDIX

3.1 Document History

RevisionDateSignatureComments
1.072011-05-09JRChange default VP (Validity Period) parameter in 2.1.12.
1.002010-09-07ALFirst revision 1.00.
1.012010-09-14KJReviewed first draft.
1.022011-02-08KJUpdated WSDL URL.
1.032011-02-18KJUpdated External Id. For future use.
1.042011-05-09JRChange default VP (Validity Period) parameter in 2.1.12.
1.052012-11-01JRServer hostname in 2.4 is change.
1.062012-12-10BU2.2.1 & 2.2.2 Minimum length of each number is 9 digits.
1.072014-09-01MKAdd explanation to ExtId in 2.2.2.
1.082016-05-10MKRemoved obsolete information about CA cert.