Hi, welcome to the documentation for the Spryng PHP API Library. This guide contains practical information on how to use the library. Full PHPDOC can be found this repository.
Installation and initialization
Using Composer
The easiest way to install the libary is using composer:
composer require spryng/spryng-api-http-php
When the installation is complete, you can initialize Spryng as follows:
require ( 'vendor/autoload.php' ); use SpryngApiHttpPhp\Client; $spryng = new Client('username', 'password', 'My Company');
Without Composer
If you’re not yet using composer, you can use the autoloader:
$ git clone https://github.com/spryng/SpryngApiHttpPhp.git
require ( 'SpryngApiHttpPhp/src/Spryng/Api/Autoloader.php' ); use SpryngApiHttpPhp\Client; $spryng = new Client( 'username', 'password', 'My Company' );
Sending SMS
To send an SMS, you should use the $spryng->sms->send()
method. This method uses the following parameters:
$recipient
Phone number you’re sending the sms to.$body
Body of the SMS.$options
Additional parameters like allowlong and route.
Options
There are a number of options you can specify with your request. The requirements for these options are available in the general documentation.
-
route
Enter your assigned route.reference
An optional reference for delivery reports.allowlong
Whether you want to allow Long SMS or not. Should be true or false.
Full example
require ( 'vendor/autoload.php' ); use SpryngApiHttpPhp\Client; use SpryngApiHttpPhp\Exception\InvalidRequestException; $spryng = new Client('username', 'password', 'My Company'); try { $spryng->sms->send('33612345678', 'A sample message!', array( 'route' => 'business', 'allowlong' => true, 'reference' => 'ABC123456789') ); } catch (InvalidRequestException $e) { echo $e->getMessage(); }
Requesting credit balance
Alongside the ability to send SMS messages, it’s also possible to request your current credit balance. This method does not require any parameters and can be used as follows:
require ( 'SpryngApiHttpPhp/src/Spryng/Api/Autoloader.php' ); use SpryngApiHttpPhp\Client; $spryng = new Client( 'username', 'password', 'My Company' ); echo 'Huidige balans: ' . $spryng->sms->checkBalance();
API
The Spryng SMS-MT HTTP API supports HTTP POST with a Content-Type of ‘application/x-www-form-urlencoded’ via HTTPS. For more information on the Spryng SMS-MT HTTP API please send an email to our support department at info@spryng.fr.
Connecting to the gateway
To submit a SMS a HTTP POST call can be performed to the following address: https://api.spryngsms.com/api/send.php
Parameters
Parameter | |
USERNAME | Chosen by user when signing up on http://www.spryng.fr |
SECRET | To be generated by user on his profile page on https://login.spryngsms.com/portal/account |
REFERENCE | Unique reference for delivery reports |
DESTINATION | Destination number(s) |
SENDER | Originator address |
BODY | Content of SMS |
SERVICE | Reference tag to be added to differentiate between end users |
ROUTE | To select the Spryng Business, Spryng Economy route or special route |
ALLOWLONG | If you wish to send Long SMS |
Username
Chosen by user when signing up on http://www.spryng.fr
Option | |
Required | yes |
Type | Alphanumeric, Case sensitive |
Min length | 2 |
Max length | 32 |
Min value | <na> |
Max value | <na> |
Values | <na> |
Default value | <none> |
Example | USERNAME=username |
Secret
To be generated by user on his profile page on https://login.spryngsms.com/portal/account
Option | |
Required | yes |
Type | Numeric and alphanumeric, Case sensitive |
Length | 50 |
Min value | <na> |
Max value | <na> |
Values | <na> |
Default value | <none> |
Example | SECRET=secret |
Reference
Option | |
Required | Only if you want to receive delivery reports |
Type | Alphanumeric |
Min length | 1 |
Max length | 256 |
Values | <na> |
Default value | <none> |
Example | REFERENCE=abc123 |
Remarks | Must be unique |
Destination
Destination number(s)
Option | |
Required | yes |
Type | MSISDN-numeric (international format without leading “00” or “+”) |
Min length | 1 MSISDN |
Max length | 1.000 MSISDN |
Min value | <na> |
Max value | <na> |
Values | <na> |
Default value | <none> |
Example | DESTINATION=33641041106,33612345678 |
Remarks | More details on error handling see “Return Values” at the bottom |
Sender
Originator address
Option | |
Required | yes |
Type | Numeric or Alphanumeric |
Min length | 3 |
Max length | 14 for Numeric or 11 for Alphanumeric |
Min value | <na> |
Max value | <na> |
Values | <na> |
Default value | <none> |
Example | SENDER=0033641041106 |
Remarks | More details on error handling see “Return Values” at the bottom |
Body
Content of SMS
Option | |
Required | yes |
Type | GSM 7-bit alphabet for text message |
Min length | 1 |
Max length | 160 chars for text message (default : ALLOWLONG=0) 612 chars (ALLOWLONG=1) When using Long SMS the system will automatically divide your message into 153 characters per SMS. |
Min value | <na> |
Max value | <na> |
Values | <na> |
Default value | <none> |
Example | BODY=This%20is%20a%20test%20SMS |
Remarks | More details on characters see “Field types” at the bottom |
Service
Reference tag can be used to create a filter in statistics
Option | |
Required | no |
Type | Alphanumeric |
Min length | 1 |
Max length | 10 |
Min value | <na> |
Max value | <na> |
Values | <na> |
Default value | <none> |
Example | SERVICE=Client1 |
Route
To select the Spryng Business, Spryng Economy or Specific User route.
Option | |
Required | yes |
Type | Predefined |
Min length | <na> |
Max length | <na> |
Min value | <na> |
Max value | <na> |
Values | BUSINESS, ECONOMY, 0-9 (Specific User route) |
Default value | BUSINESS |
Example | ROUTE=BUSINESS |
Allowlong
If you wish to send Long SMS
Option | |
Required | Only if you wish to send Long SMS |
Type | Predefined |
Min length | <na> |
Max length | <na> |
Min value | <na> |
Max value | <na> |
Values | 0,1 |
Default value | 0 |
Example | ALLOWLONG=1 |
Remarks | When using Long SMS the system will automatically divide your message into 153 characters per SMS. |
Return Values
Return Value | |
1 | Successfully received |
100 | Missing parameter |
101 | Username too short |
102 | Username too long |
103 | Password too short |
104 | Password too long |
105 | Destination too short |
106 | Destination too long |
107 | Sender too long |
108 | Sender too short |
109 | Body too short |
110 | Body too long |
200 | Security error |
201 | Unknown route |
202 | Route access violation |
203 | Insufficient credits |
301 | Insufficient credits on the main account |
800 | Technical error |
Delivery Reports
You can set your delivery reports by logging on to your account on http://www.spryng.fr and selecting the menu item ‘Settings’ in your SMS dashboard. Here you can enter the url of your script (servlet, php script, perl, etc…) on which you wish to receive your delivery reports. This script should expect two parameters, this will be sent via an HTTP GET. When you require a delivery reports you should not specify more than 1 DESTINATION in the request. The following status values will be sent:
Status value | |
10 | Delivered |
20 | Not delivered |
30 | Sent |
Example: REFERENCE=abc123&STATUS=10
The HTTP request conducted by Spryng must be answered by your server with a status code of 200 which means that the message was successfully accepted by your system. If either the HTTP server cannot be reached, if it returns e.g. 500 internal server error Spryng assumes that the message was not successfully accepted by your system and the request will be retried once every minute. The message will not be retried forever, the current setting is 24 hours.
Field types
Numeric: characters 0 to 9 Alphanumeric: character from ISO-8859-1 MSISDN-numeric characters 0 to 9 GSM 7-bit alphabet (allowed characters in text messages): The characters ‘a‘ through ‘z‘, ‘A‘ through ‘Z‘,
‘0‘ through ‘9‘, linefeed, carriage return and @£$¥èéùìòÇØøÅå_€ÆæßÉ!”#¤%&'()*+,-./:;<=>?¡ÄÖÑܧ¿äöñüà
To use the € sign please use %80.
If you are using the euro sign, this will count as 2 characters:
€ = 2 characters
E = 1 character
Credit amount API
POST
https://api.spryngsms.com/api/check.php
Installation & Initialization
The easiest way to implement our API in your C#/.NET environment is by using our C# library, which is available here. You can use NuGet to easily install the library:
Install-Package SpryngApiHttpDotNet
To use the Spryng HTTP Api you must first create a new instance of the SpryngHttpClient
:
SpryngHttpClient client = new SpryngHttpClient(username, password);
Sending a SMS
To send a SMS, you must create a SmsRequest
object. You can create one as follows:
SmsRequest request = new SmsRequest() { Destinations = new string[] { "33612345678", "33698765421" }, Sender = "Spryng", Body = "This is a Test SMS." };
You can now send the SMS using the client:
try { client.ExecuteSmsRequest(request); Console.WriteLine("SMS has been send!"); } catch (SpryngHttpClientException ex) { Console.WriteLine("An Exception occured!\n{0}", ex.Message); }
The API also provides an Async implementation which can be used in the same fashion as the synchronous api:
await client.ExecuteSmsRequestAsync(request);
SmsRequest Options
There are multiple properties available in the SmsRequest
that can be changed.
Destinations
A string array of phone numbers you’re sending the sms to.Body
Body of the sms.Sender
Originator address, like your company name.Route
Whether to use Spryng Business, Spryng Economy or a custom route. Defaults tobusiness
.Reference
An optional reference for delivery reports.AllowLong
Whether you want to allow long SMS or not. Defaults toFalse
.
Request Credit Balance
It’s also possible to request the accounts credit balance using the client. This method is available sycnhronously and asynchronously.
// Synchronous double remainingCredits = client.GetCreditAmount(); // Asynchronous double remainingCredits = await client.GetCreditAmountAsync();
API
The Spryng SMS-MT HTTP API supports HTTP POST with a Content-Type of ‘application/x-www-form-urlencoded’ via HTTPS. For more information on the Spryng SMS-MT HTTP API please send an email to our support department at info@spryng.fr.
Connecting to the gateway
To submit a SMS a HTTP POST call can be performed to the following address: https://api.spryngsms.com/api/send.php
Parameters
Parameter | |
USERNAME | Chosen by user when signing up on http://www.spryng.fr |
SECRET | To be generated by user on his profile page on https://login.spryngsms.com/portal/account |
REFERENCE | Unique reference for delivery reports |
DESTINATION | Destination Number(s) |
SENDER | Originator address |
BODY | Content of SMS |
SERVICE | Reference tag to be added to differentiate between end users |
ROUTE | To select the Spryng Business, Spryng Economy route or special route |
ALLOWLONG | If you wish to send Long SMS |
Username
Chosen by user when signing up on http://www.spryng.fr
Option | |
Required | yes |
Type | Alphanumeric, Case sensitive |
Min length | 2 |
Max length | 32 |
Min value | <na> |
Max value | <na> |
Values | <na> |
Default value | <none> |
Example | USERNAME=username |
Secret
To be generated by user on his profile page on https://login.spryngsms.com/portal/account
Option | |
Required | yes |
Type | Numeric and alphanumeric, Case sensitive |
Length | 50 |
Min value | <na> |
Max value | <na> |
Values | <na> |
Default value | <none> |
Example | SECRET=secret |
Reference
Option | |
Required | Only if you want to receive delivery reports |
Type | Alphanumeric |
Min length | 1 |
Max length | 256 |
Values | <na> |
Default value | <none> |
Example | REFERENCE=abc123 |
Remarks | Must be unique |
Destination
Destination Number(s)
Option | |
Required | yes |
Type | MSISDN-numeric (international format without leading “00” or “+”) |
Min length | 1 MSISDN |
Max length | 1.000 MSISDN |
Min value | <na> |
Max value | <na> |
Values | <na> |
Default value | <none> |
Example | DESTINATION=33641041106,33612345678 |
Remarks | More details on error handling see “Return Values” at the bottom |
Sender
Originator address
Option | |
Required | yes |
Type | Numeric or Alphanumeric |
Min length | 3 |
Max length | 14 for Numeric or 11 for Alphanumeric |
Min value | <na> |
Max value | <na> |
Values | <na> |
Default value | <none> |
Example | SENDER=0033641041106 |
Remarks | More details on error handling see “Return Values” at the bottom |
Body
Content of SMS
Option | |
Required | yes |
Type | GSM 7-bit alphabet for text message |
Min length | 1 |
Max length | 160 chars for text message (default : ALLOWLONG=0) 612 chars (ALLOWLONG=1) When using Long SMS the system will automatically divide your message into 153 characters per SMS. |
Min value | <na> |
Max value | <na> |
Values | <na> |
Default value | <none> |
Example | BODY=This%20is%20a%20test%20SMS |
Remarks | More details on characters see “Field types” at the bottom. |
Service
Reference tag can be used to create a filter in statistics
Option | |
Required | no |
Type | Alphanumeric |
Min length | 1 |
Max length | 10 |
Min value | <na> |
Max value | <na> |
Values | <na> |
Default value | <none> |
Example | SERVICE=Client1 |
Route
To select the Spryng Business, Spryng Economy or Specific User route.
Option | |
Required | yes |
Type | Predefined |
Min length | <na> |
Max length | <na> |
Min value | <na> |
Max value | <na> |
Values | BUSINESS, ECONOMY, 0-9 (Specific User route) |
Default value | BUSINESS |
Example | ROUTE=BUSINESS |
Allowlong
If you wish to send Long SMS
Option | |
Required | Only if you wish to send Long SMS |
Type | Predefined |
Min length | <na> |
Max length | <na> |
Min value | <na> |
Max value | <na> |
Values | 0,1 |
Default value | 0 |
Example | ALLOWLONG=1 |
Remarks | When using Long SMS the system will automatically divide your message into 153 characters per SMS. |
Return Values
Return Value | |
1 | Successfully received |
100 | Missing parameter |
101 | Username too short |
102 | Username too long |
103 | Password too short |
104 | Password too long |
105 | Destination too short |
106 | Destination too long |
107 | Sender too long |
108 | Sender too short |
109 | Body too short |
110 | Body too long |
200 | Security error |
201 | Unknown route |
202 | Route access violation |
203 | Insufficient credits |
301 | Insufficient credits on the main account |
800 | Technical error |
Delivery Reports
You can set your delivery reports by logging on to your account on http://www.spryng.fr and selecting the menu item ‘Instellingen’ in your SMS dashboard. Here you can enter the url of your script (servlet, php script, perl, etc…) on which you wish to receive your delivery reports. This script should expect two parameters, this will be sent via an HTTP GET. When you require a delivery reports you should not specify more than 1 DESTINATION in the request. The following status values will be sent:
Status value | |
10 | Delivered |
20 | Not delivered |
30 | Sent |
Example: REFERENCE=abc123&STATUS=10
The HTTP request conducted by Spryng must be answered by your server with a status code of 200 which means that the message was successfully accepted by your system. If either the HTTP server cannot be reached, if it returns e.g. 500 internal server error Spryng assumes that the message was not successfully accepted by your system and the request will be retried once every minute. The message will not be retried forever, the current setting is 24 hours.
Field types
Numeric: characters 0 to 9 Alphanumeric: character from ISO-8859-1 MSISDN-numeric characters 0 to 9 GSM 7-bit alphabet (allowed characters in text messages): The characters ‘a‘ through ‘z‘, ‘A‘ through ‘Z‘,
‘0‘ through ‘9‘, linefeed, carriage return and @£$¥èéùìòÇØøÅå_€ÆæßÉ!”#¤%&'()*+,-./:;<=>?¡ÄÖÑܧ¿äöñüà
To use the € sign please use %80. If you are using the euro sign, this will count as 2 characters:
€ = 2 characters
E = 1 character
Credit amount API
POST
https://api.spryngsms.com/api/check.php