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=050003FF020105 = 5 bytes follow00 = indicator for concatenated message03 = three bytes followFF= message identification. Each part has the same value02 = the concatenated message has 2 parts01 = 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 characters1 = 8 bit binary (8 bit) | 140 octets2 = UCS-2 (16 bit) | 70 charactersSee 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 = Delivered2 = Pending3 = Failed4 = Timeout |
Text |
String |
DELIVEREDPENDINGFAILEDFAILED_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 |