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. 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('31612345678', '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.nl.

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 https://www.spryng.nl
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 https://www.spryng.nl

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=31641041106,31612345678
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=0031641041106
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
800 Technical error

Delivery Reports

You can set your delivery reports by logging on to your account on https://www.spryng.nl 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[] { "31612345678", "31698765421" },
    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 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.nl.

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 https://www.spryng.nl
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 https://www.spryng.nl

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=31641041106,31612345678
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=0031641041106
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
800 Technical error

Delivery Reports

You can set your delivery reports by logging on to your account on https://www.spryng.nl 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