Developers

Use our Api to easily integrate and develop

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 like so:

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. t takes 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 Weither 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('44612345678', '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 like this:

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 GET and HTTP POST with a Content-Type of ‘application/x-www-form-urlencoded’ via both HTTP and HTTPS. For more information on the Spryng SMS-MT HTTP API please send an email to our support department at info@spryng.co.uk.

Connecting to the gateway

To submit a SMS a HTTP GET or 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.co.uk
PASSWORD Chosen by user when signing up on http://www.spryng.co.uk
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.co.uk

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

Password

Chosen by user when signing up on http://www.spryng.co.uk

Option
Required  yes
Type  Alphanumeric, Case sensitive
Min length  6
Max length  32
Min value  <na>
Max value  <na>
Values  <na>
Default value  <none>
Example  PASSWORD=password

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=44741041106,44712345678
Remarks More details on error handling see “Return Values” at the bottom

Sender

Originator address

Option
Required  yes
Type  Numeric or Alphanumeric
Min length  1
Max length  14 for Numeric or 11 for Alphanumeric
Min value  <na>
Max value  <na>
Values  <na>
Default value  <none>
Example  SENDER=0044741041106
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
message up to 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
message up to 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 long
110  Body too short
200  Security error
201  Unknown route
202  Route access violation
203  Insufficient credits
800  Technical error

Delivery Reports

You can set your delivery reports by logging on to your
account on http://www.spryng.co.uk 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 and body with TRUE 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 or if it returns the body FALSE 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

Credit amount API

https://api.spryngsms.com/api/check.php?username=********&password=********

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 like this:

SmsRequest request = new SmsRequest()
{
    Destinations = new string[] { "44712345678", "44798765421" },
    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 to business.
  • Reference An optional reference for delivery reports.
  • AllowLong Whether you want to allow long SMS or not. Defaults to False.

 

Request Credit Balance

It’s also possible to request the accounts credit balance using the client. This method is available synchronously and asynchronously.

// Synchronous
double remainingCredits = client.GetCreditAmount();

// Asynchronous
double remainingCredits = await client.GetCreditAmountAsync();

 

API

The Spryng SMS-MT HTTP API supports GET and HTTP POST with a Content-Type of ‘application/x-www-form-urlencoded’ via both HTTP and HTTPS. For more information on the Spryng SMS-MT HTTP API please send an email to our support department at info@spryng.nl.

Connecting to the gateway

To submit a SMS a HTTP GET or 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.co.uk
PASSWORD Chosen by user when signing up on http://www.spryng.co.uk
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.co.uk

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

Password

Chosen by user when signing up on http://www.spryng.co.uk

Option
Required  yes
Type  Alphanumeric, Case sensitive
Min length  6
Max length  32
Min value  <na>
Max value  <na>
Values  <na>
Default value  <none>
Example  PASSWORD=password

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=44741041106,44712345678
Remarks More details on error handling see “Return Values” at the bottom

Sender

Originator address

Option
Required  yes
Type  Numeric or Alphanumeric
Min length  1
Max length  14 for Numeric or 11 for Alphanumeric
Min value  <na>
Max value  <na>
Values  <na>
Default value  <none>
Example  SENDER=0044741041106
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
message up to 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
message up to 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 long
110  Body too short
200  Security error
201  Unknown route
202  Route access violation
203  Insufficient credits
800  Technical error

Delivery Reports

You can set your delivery reports by logging on to your
account on http://www.spryng.co.uk 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 and body with TRUE 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 or if it returns the body FALSE 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

Credit amount API

https://api.spryngsms.com/api/check.php?username=********&password=********