Skip to content

Interface description

Introduction

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.

Web service interface

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.

SOAP functions

SendMessage()

This function sends a SMS to one or more recipients.

Parameters
Name Mandatory Type Description Example
User Yes String Username of client. "myuser"
Pass Yes String Password of client. "mypassword"
To Yes String Recipients 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”
Msg Yes String The actual message. "hello-world"
From No String Sender of message. If not specified this parameter defaults to client preset name or number. “+46701234567”
"MyCompanyAB"
ExtId No String External 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
Name Type Description Example
TransactionIds Array(String) A list of transaction ids for the sent messages. [“6ef63afc-6e8e-4c7d-9427-58e030df0347”,” 6ef63afc-6e8e-4c7d-9427-58e030df0348”]
SOAP faults
Response Description
1 Internal Error Something unexpected happened. Contact the System Administrator.
2 Incorrect username or password Invalid credentials
3 Too many numbers in to-list Maximum number of recipient phone numbers are 10
4 Incorrect phone number in to-list One or more of the recipient phone numbers are malformed
5 Rate limit exceeded The rate limit has been exceeded. The client must slow down their request rate.

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
Name Mandatory Description Examples
User Yes Username of client. "User=myuser"
Pass Yes Password of client. "Pass=mypassword"
To Yes Recipient of the message, specified as MSISDN number in International format with preceding + character.

Multiple recipients can be given in a single request. Multiple recipients must be separated by ;.

Maximum number of recipients that can be listed in a single request is 50.
"To=+46701234567"

"To=+46701234567;+46701234568;+46701234569"
From No Sender 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’.
"From=+46701234567"

"From=MyCompanyAB"
FromType No Format of the From-parameter. Defaults to I=International.

Available formats are N=National, I=International, S=Short and A=Alphanumeric.
"I"
Msg Yes The actual message. If message type is binary this parameter should be given in hexadecimal form. "Msg=Hello+world
MsgType No Message type. 0=Text , 1=Flash, 3=Binary. Defaults to 0. Additional messages types will be available in later release. MsgType=0
DLR No Delivery Report requested. 0=NO, 1=YES. Defaults to 0. DLR=1
ExtId No External 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. ExtId=MyId
VP No Validity Period. Number of minutes that message is valid. Defaults to 4320 minutes (3 days). Maximum value is 20160 minutes. VP=1440
FDA No First Delivery Attempt. The preferred time when message delivery should first be attempted. The parameter is given in absolute time. FDA=2009-12-01+12%3a00%3a00
TZ No Time Zone. Specifies in which time zone the FDAparameter time is given. Defaults to Europe/Stockholm. See appendix 4.4 for a list of available time zones. TZ=Europe%2FLondon
UDH No User Data Header. This parameter is given in hexadecimal form. For advanced users.

Will be prepended to Msg. Message split and concatenation will be handled automatically for nonbinary messages.

For example:
UDH=050003FF0201
05 = 5 bytes follow
00 = indicator for concatenated message
03 = three bytes follow
FF= message identification. Each part has the same value
02 = the concatenated message has 2 parts
01 = this is part 1
UDH=050003FF0201
DCS No Data Coding Scheme. The parameter is used when message type is binary. Acceptable values are 0-255. DCS=0
ER No Enable reply. 0 = NO, 1 = YES. Defaults to 0. For future use. ER=1
Prio No Message priority, ranging from 0 (lowest) to 3 (highest). Defaults to 2. This parameter is copied to SMPP parameter priority_flag when the SMS is forwarded to the GSM network operator. GSM networks only differ between priority_flag=0 (non-priority) and priority_flag>0 (priority). Prio=1
Coding No Character encoding of the SMS payload when it arrives on the target handset. Defaults to GSM 7bit character encoding.

The following character encodings are supported:

Coding | max characters/SMS

0 = GSM 7bit (default) | 160 characters
1 = 8 bit binary (8 bit) | 140 octets
2 = UCS-2 (16 bit) | 70 characters

See chapter 3.1.5 for an example on how to send a Unicode SMS.
Coding=2
Concat No Concatenate 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. Concat=0
MaxMsgs No Maximum 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=1. MaxMsgs=3
Return values
Name Type Description Example
TransactionIds Array(String) A list of transaction IDs for the sent messages. [“6ef63afc-6e8e-4c7d-9427-58e030df0347”,” 6ef63afc-6e8e-4c7d-9427-58e030df0348”]
SOAP faults
Response Description
1 Internal Error Something unexpected happened. Contact the System Administrator.
2 Incorrect username or password Invalid credentials.
3 Too many numbers in to list Maximum number of recipient phone numbers are 10.
4 Incorrect phone number in to list One or more of the recipient phone numbers are malformed.
5 Rate limit exceeded The rate limit has been exceeded. The client must slow down their request rate.

GetMessageStatus()

This function returns the current status of a sent message.

Parameters
Name Mandatory Type Description Example
User Yes String Username of client. “myuser”
Pass Yes String Password of client. “mypassword”
TransactionId Yes String Transaction id for a sent message. “6ef63afc-6e8e-4c7d-9427-58e030df0347”

Return values

Name Type Description
MessageStatus Object (
Code Integer 1 = Delivered
2 = Pending
3 = Failed
4 = Timeout
Text String DELIVERED
PENDING
FAILED
FAILED_TIMEOUT
)

SOAP faults

Response Description
1 Internal Error Something unexpected happened. Contact the System Administrator.
2 Incorrect username or password Invalid credentials.
3 Unknown transaction id The specified Transaction ID does not exist.

Delivery reports

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

WSDL

This table defines which URL to use for retrieving 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 URL
Web Service http://web.spiricom.spirius.com:56000/v1_0/.wsdl
Web Service using TLS https://web.spiricom.spirius.com:56001/v1_0/.wsdl