SMS Gateway
Interface Description
WEB SERVICE v1.0
| Document name | WEB SERVICE v1.0 |
|---|---|
| Document number | EAL10003SIS |
| Revision | 1.08 |
| Author | Martin Kristell |
| Date | 2016-05-10 |
| Information class | Open Information |
| Reviewer | Jonas Rexeke |
| Review date | 2016-05-10 |
| Company | SPIRIUS AB |
| VAT/REG number | 556788-4183 |
| Postal address | Box 67 371 21 KARLSKRONA |
| Telephone number | +46 (455) 65 55 00 |
| Fax number | +46 (455) 65 55 19 |
| Home page | www.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
| 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. |
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
| 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 ‘+’ character. Maximum number of MSISDN numbers in the list are 10. | “+46701234567, +46707654321” |
| Msg | Yes | String | The actual message. If message type is binary this parameter should be given in hexadecimal form. | “Hello+world” |
| MsgType | No | String | Message type. ‘0’=Text , ‘1’=Flash, ´3´=Binary. Defaults to ‘0’. Additional messages types will be available in later release. | “0” |
| From | No | String | 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’. | “+46701234567” “MyCompanyAB” |
| FromType | No | String | Format of the ‘From’-parameter. Defaults to ‘I’=International. Available formats are ‘N’=National, ‘I‘=International, ‘S’=Short and ‘A‘=Alphanumeric. | “I” |
| 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” |
| DLR | No | String | Delivery Report requested. ‘0’=NO, ‘1’=YES. Defaults to ‘0’. | “1” |
| RouteType | No | String | Route Type. Specifies routing rule. Currently only ‘Standard’ is available. | “Standard” |
| VP | No | String | Validity Period. Number of minutes that message is valid. Defaults to 4320 minutes (3 days). Maximum value is 20160 minutes. | “1440” |
| FDA | No | String | First 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” |
| TZ | No | String | Time 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” |
| UDH | No | String | User Data Header. This parameter is given in hexadecimal form. For advanced users. For future use. | “050003FF0201” |
| DCS | No | String | Data Coding Scheme. The parameter is used when message type is binary. Acceptable values are 0-255. | “0” |
| ER | No | String | Enable reply. ‘0’=NO, ‘1’=YES. Defaults to ‘0’. For future use. | “1” |
| Prio | No | String | Message priority, ranging from 1 (highest) to 3 (lowest). Defaults to ‘2’. For future use. | “1” |
| CharSet | No | String | Characters 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” |
| Concat | No | String | 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’. | “0” |
| MaxMsgs | No | String | 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 to ’1’. | “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. |
2.2.3 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 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 Service | http://web.spiricom.spirius.com:56000/v1_0/.wsdl |
| Web Service using SSL | https://web.spiricom.spirius.com:56001/v1_0/.wsdl |
3. APPENDIX
3.1 Document History
| Revision | Date | Signature | Comments |
|---|---|---|---|
| 1.07 | 2011-05-09 | JR | Change default VP (Validity Period) parameter in 2.1.12. |
| 1.00 | 2010-09-07 | AL | First revision 1.00. |
| 1.01 | 2010-09-14 | KJ | Reviewed first draft. |
| 1.02 | 2011-02-08 | KJ | Updated WSDL URL. |
| 1.03 | 2011-02-18 | KJ | Updated External Id. For future use. |
| 1.04 | 2011-05-09 | JR | Change default VP (Validity Period) parameter in 2.1.12. |
| 1.05 | 2012-11-01 | JR | Server hostname in 2.4 is change. |
| 1.06 | 2012-12-10 | BU | 2.2.1 & 2.2.2 Minimum length of each number is 9 digits. |
| 1.07 | 2014-09-01 | MK | Add explanation to ExtId in 2.2.2. |
| 1.08 | 2016-05-10 | MK | Removed obsolete information about CA cert. |