Hi, welkom bij de documentatie voor de Spryng PHP Api Library. Deze handleiding biedt praktische informatie over het integreren van de library. Voor meer informatie kunt u gebruik maken van de PHPDoc in deze repository.
Installatie en initialisatie
Met Composer
We raden u aan de library te installeren met Composer. Dit kan op de volgende manier:
composer require spryng/spryng-api-http-php
Zodra de installatie voltooid is, kunt u Spryng op de volgende manier initialiseren:
require ( 'vendor/autoload.php' ); use SpryngApiHttpPhp\Client; $spryng = new Client('gebruikersnaam', 'wachtwoord', 'Uw Bedrijf');
Zonder Composer
Installatie zonder Composer wordt niet aangeraden! De library maakt gebruik van enkele dependencies, zoals GuzzleHttp, die niet kunnen worden geïnstalleerd met een autoloader.
Als u geen gebruik maakt van Composer, bijvoorbeeld door technische beperkingen, kunt u gebruik maken van de autoloader om alle klassen in te laden.
$ git clone https://github.com/spryng/SpryngApiHttpPhp.git
require ( 'SpryngApiHttpPhp/src/Spryng/Api/Autoloader.php' ); use SpryngApiHttpPhp\Client; $spryng = new Client( 'gebruikersnaam', 'wachtwoord', 'Uw Bedrijf' );
Een SMS versturen
U kunt SMS berichten versturen met de methode Client $spryng->sms->send()
. Deze methode heeft de volgende argumenten:
$recipient
Het telefoonnummer waar u een SMS naar wilt versturen.$body
Het SMS bericht.$options
Verdere opties zoals allowlong en route.
Opties
Er zijn enkele opties die u kunt specificeren bij het versturen van een SMS bericht. De restricties voor deze opties zijn te vinden in de algemene beschrijving van de Spryng SMS Api.
-
route
De route die u wilt gebruiken. Deze wordt u aangeleverd.reference
Een optionele referentie voor uw bericht. Deze kunt u gebruiken om delivery reports te ontvangen.allowlong
Boolean waarde waarmee u aangeeft of berichten langer dan 160 tekens in verschillende berichten verzonden mogen worden.
Volledig voorbeeld
require ( 'vendor/autoload.php' ); use SpryngApiHttpPhp\Client; use SpryngApiHttpPhp\Exception\InvalidRequestException; $spryng = new Client('gebruikersnaam', 'wachtwoord', 'Uw Bedrijf' ); try { $spryng->sms->send('32612345678', 'Een voorbeeld bericht!', array( 'route' => 'business', 'allowlong' => true, 'reference' => 'ABC123456789') ); } catch (InvalidRequestException $e) { echo $e->getMessage(); }
Aanvragen credit balans
Naast het versturen van SMS berichten, is het ook mogelijk om uw credit balans op te vragen. Deze methode heeft geen extra argumenten nodig en kan als volgt worden geïmplementeerd:
require ( 'SpryngApiHttpPhp/src/Spryng/Api/Autoloader.php' ); use SpryngApiHttpPhp\Client; $spryng = new Client( 'gebruikersnaam', 'wachtwoord', 'Uw Bedrijf' ); echo 'Huidige balans: ' . $spryng->sms->checkBalance();
API
De Spryng SMS-MT HTTP API ondersteunt HTTP POST met een Content-Type ‘application/x-www-form-urlencoded’ via HTTPS. Bij vragen over de Spryng SMS-MT HTTP API kunt u een e-mail sturen naar onze support afdeling via info@spryng.nl.
Koppelen aan de gateway
Om een bericht te verzenden kan er een HTTP POST call uitgevoerd worden naar het volgende adres:
https://api.spryngsms.com/api/send.php
Parameters
Parameter | |
USERNAME | Gekozen door gebruiker bij aanmelding op https://www.spryng.nl |
SECRET | Door gebruiker te genereren in de profielpagina op https://login.spryngsms.com/portal/account |
REFERENCE | Unieke referentie voor delivery reports |
DESTINATION | Nummer(s) bestemming |
SENDER | Afzender van het bericht |
BODY | Inhoud van de SMS |
SERVICE | Referentie tag die toegevoegd kan worden om tussen eindgebruikers te differentiëren |
ROUTE | Om de Spryng Business, Spryng Economy route of een speciale route te gebruiken |
ALLOWLONG | Als u Long SMS wenst te versturen |
Username
Gekozen door gebruikers bij aanmelding op https://www.spryng.nl
Optie | |
Vereist | ja |
Type | Alfanumeriek, Case gevoelig |
Min lengte | 2 |
Max lengte | 32 |
Min waarde | <na> |
Max waarde | <na> |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | USERNAME=username |
Secret
Door gebruiker te genereren in de profielpagina op https://login.spryngsms.com/portal/account
Optie | |
Vereist | ja |
Type | Numeriek en alfanumeriek, Case gevoelig |
Lengte | 50 |
Min waarde | <na> |
Max waarde | <na> |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | SECRET=secret |
References
Optie | |
Vereist | Alleen wanneer u delivery reports wenst te ontvangen |
Type | Alfanumeriek |
Min lengte | 1 |
Max lengte | 256 |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | REFERENCE=abc123 |
Opmerkingen | Moet uniek zijn |
Destination
Nummer(s) bestemming
Optie | |
Vereist | ja |
Type | MSISDN-numeriek (internationaal format zonder “00” of “+”) |
Min lengte | 1 MSISDN |
Max lengte | 1.000 MSISDN |
Min waarde | <na> |
Max waarde | <na> |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | DESTINATION=32441041106,32412345678 |
Opmerkingen | Meer details over foutafhandeling zie “Return Values” onderaan de pagina |
Sender
Afzender van het bericht
Optie | |
Vereist | ja |
Type | Numeriek of Alfanumeriek |
Min lengte | 3 |
Max lengte | 14 voor numeriek of 11 voor alfanumeriek |
Min waarde | <na> |
Max waarde | <na> |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | SENDER=0032441041106 |
Opmerkingen | Meer details over foutafhandeling zie “Return Values” onderaan de pagina |
Body
Inhoud van de SMS
Optie | |
Vereist | ja |
Type | GSM 7-bit alfabet voor tekstberichten |
Min lengte | 1 |
Max lengte | 160 karakters voor tekst bericht (default : ALLOWLONG=0) 612 karakters (ALLOWLONG=1) Wanneer u Long SMS gebruikt, zal het systeem het bericht automatisch verdelen in 153 karakters per sms. |
Min waarde | <na> |
Max waarde | <na> |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | BODY=This%20is%20a%20test%20SMS |
Opmerkingen | Meer details over karakters zie “Field types” onderaan de pagina |
Service
Referentie tag kan gebruikt worden om een filter in statistieken te creëren.
Optie | |
Vereist | nee |
Type | Alfanumeriek |
Min lengte | 1 |
Max lengte | 10 |
Min waarde | <na> |
Max waarde | <na> |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | SERVICE=Client1 |
Route
Om de Spryng Business, Spryng Economy of Specific User route te selecteren.
Optie | |
Vereist | ja |
Type | Vooraf gedefinieerd |
Min lengte | <na> |
Max lengte | <na> |
Min waarde | <na> |
Max waarde | <na> |
Waardes | BUSINESS, ECONOMY, 0-9 (Specific User route) |
Default waarde | BUSINESS |
Voorbeeld | ROUTE=BUSINESS |
Allowlong
Als u Long SMS wenst te versturen
Optie | |
Vereist | Alleen als u Long SMS wenst te versturen |
Type | Vooraf gedefinieerd |
Min lengte | <na> |
Max lengte | <na> |
Min waarde | <na> |
Max waarde | <na> |
Waardes | 0,1 |
Default waardes | 0 |
Voorbeeld | ALLOWLONG=1 |
Opmerkingen | Wanneer u Long SMS gebruikt, zal het systeem het bericht automatisch verdelen in 153 karakters per sms. |
Return Values
Return Waarde | |
1 | Succesvol ontvangen |
100 | Missende parameter |
101 | Gebruikersnaam te lang |
102 | Gebruikersnaam te kort |
103 | Wachtwoord te kort |
104 | Wachtwoord te lang |
105 | Bestemming te kort |
106 | Bestemming te lang |
107 | Afzender te lang |
108 | Afzender te kort |
109 | Inhoud te kort |
110 | Inhoud te lang |
200 | Veiligheidsfout |
201 | Onbekende route |
202 | Route toegang overtreding |
203 | Onvoldoende credits |
301 | Hoofdaccount heeft onvoldoende credits |
800 | Technische fout |
Delivery Reports
U kunt uw delivery reports instellen door in te loggen op uw account op https://www.spryng.nl en door “instellingen” in uw SMS Dashboard te selecteren. Hier kunt u de URL van uw script (servlet, php script, perl, etc…) invoeren waar u uw delivery reports op wenst te ontvangen. Dit script zou 2 parameters moeten bevatten, welke verstuurd wordt via een HTTP GET. Wanneer u een delivery report aanvraagt, moet u niet meer dan 1 DESTINATION specificeren in het verzoek. De volgende status waardes zullen verzonden worden:
Status waarde | |
10 | Afgeleverd |
20 | Niet afgeleverd |
30 | Verzonden |
Voorbeeld: REFERENCE=abc123&STATUS=10
Het HTTP verzoek uitgevoerd door Spryng moet beantwoord worden door uw server met de status code 200, wat betekent dat het bericht succesvol is geaccepteerd door uw systeem. Wanneer de HTTP server niet bereikt kan worden en als het bijvoorbeeld terugkomt met 500 internal server error, neemt Spryng aan dat het bericht niet succesvol is geaccepteerd door uw systeem en het verzoek zal eenmaal per minuut opnieuw verzonden worden. Het bericht zal niet eeuwig opnieuw verzonden worden, de huidige instelling is 24 uur.
Field types
Numeriek: karakters 0 tot 9 Alfanumeriek: karakter van ISO-8859-1
MSISDN-numeriek karakters 0 tot 9 GSM 7-bit alfabet (toegestane karakters in tekst berichten): de karakters ‘a‘ tot en met ‘z‘, ‘A‘ tot en met ‘Z‘,
‘0‘ tot en met ‘9‘, linefeed, carriage return en
@£$¥èéùìòÇØøÅå_€ÆæßÉ!”#¤%&'()*+,-./:;<=>?¡ÄÖÑܧ¿äöñüà
Om het € teken te gebruiken, moet u %80 invoeren. Als u daadwerkelijk het euroteken gebruikt geldt deze als 2 karakters:
€ = 2 karakters
E = 1 karakter
Credit amount API
POST https://api.spryngsms.com/api/check.php
Installatie en initialisatie
Voor gebruik van onze API in uw C#/.NET omgeving kunt u onze C# library gebruiken. Deze is hier te downloaden. U kunt NuGet gebruiken om de bibliotheek te installeren:
Install-Package SpryngApiHttpDotNet
Om de Spryng HTTP APO te gebruiken, moet u gebruik maken van een nieuw exemplaar SpryngHttpClient
:
SpryngHttpClient client = new SpryngHttpClient(username, password);
SMS verzenden
Om een SMS te verzenden, moet u een SmsRequest
object creëren. U kunt er zoals volgt creëren:
SmsRequest request = new SmsRequest() { Destinations = new string[] { "324345678", "32498765421" }, Sender = "Spryng", Body = "This is a Test SMS." };
U kunt nu de SMS verzenden door gebruik te maken van de client:
try { client.ExecuteSmsRequest(request); Console.WriteLine("SMS has been send!"); } catch (SpryngHttpClientException ex) { Console.WriteLine("An Exception occured!\n{0}", ex.Message); }
De API levert een Async implementatie die op dezelfde manier gebruikt kan worden als de synchrone api:
await client.ExecuteSmsRequestAsync(request);
Sms verzoek opties
Er zijn verschillende eigendommen beschikbaar in het SmsRequest
die aangepast kan worden:
Destinations
Een matrix van de telefoonnummers waar u de SMS naar stuurt.Body
Inhoud van de sms.Sender
Afzender van het bericht, zoals de bedrijfsnaamRoute
Of u gebruik maakt van Spryng Business, Spryng Economy of een speciale route. Automatisch naarbusiness
.Reference
Een optionele referentie voor delivery reportsAllowLong
Wanneer u Long SMS wilt toestaan of niet. Automatisch naarFalse
.
Verzoek credit saldo
Naast de mogelijkheid om SMS berichten te versturen, is het ook mogelijk om uw huidige creditsaldo aan te vragen door middel van de client. Deze methode is synchroon en niet synchroon beschikbaar.
// Synchronous double remainingCredits = client.GetCreditAmount(); // Asynchronous double remainingCredits = await client.GetCreditAmountAsync();
API
De Spryng SMS-MT HTTP API ondersteunt HTTP POST met een Content-Type ‘application/x-www-form-urlencoded’ via HTTPS. Bij vragen over de Spryng SMS-MT HTTP API kunt u een e-mail sturen naar onze support afdeling via info@spryng.nl.
Koppelen aan de gateway
Om een bericht te verzenden kan er een HTTP POST call uitgevoerd worden naar het volgende adres: https://api.spryngsms.com/api/send.php
Parameters
Parameter | |
USERNAME | Gekozen door gebruiker bij aanmelding op https://www.spryng.nl |
SECRET | Door gebruiker te genereren in de profielpagina op https://login.spryngsms.com/portal/account |
REFERENCE | Unieke referentie voor delivery reports |
DESTINATION | Nummer(s) bestemming |
SENDER | Afzender van het bericht |
BODY | Inhoud van de SMS |
SERVICE | Referentie tag die toegevoegd kan worden om tussen eindgebruikers te differentiëren |
ROUTE | Om de Spryng Business, Spryng Economy route of een speciale route te gebruiken |
ALLOWLONG | Als u Long SMS wenst te versturen |
Username
Gekozen door gebruikers bij aanmelding op https://www.spryng.nl
Optie | |
Vereist | ja |
Type | Alfanumeriek, Case gevoelig |
Min lengte | 2 |
Max lengte | 32 |
Min waarde | <na> |
Max waarde | <na> |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | USERNAME=username |
Secret
Door gebruiker te genereren in de profielpagina op https://login.spryngsms.com/portal/account
Optie | |
Vereist | ja |
Type | Numeriek en alfanumeriek, Case gevoelig |
Lengte | 50 |
Min waarde | <na> |
Max waarde | <na> |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | SECRET=secret |
Reference
Optie | |
Vereist | Alleen wanneer u delivery reports wenst te ontvangen |
Type | Alfanumeriek |
Min lengte | 1 |
Max lengte | 256 |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | REFERENCE=abc123 |
Opmerkingen | Moet uniek zijn |
Destination
Nummer(s) bestemming
Optie | |
Vereist | ja |
Type | MSISDN-numeriek (internationaal format zonder “00” of “+”) |
Min lengte | 1 MSISDN |
Max lengte | 1.000 MSISDN |
Min waarde | <na> |
Max waarde | <na> |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | DESTINATION=32441041106,32412345678 |
Opmerkingen | Meer details over foutafhandeling zie “Return Values” onderaan de pagina. |
Sender
Afzender van het bericht
Optie | |
Vereist | ja |
Type | Numeriek of Alfanumeriek |
Min lengte | 3 |
Max lengte | 14 voor numeriek of 11 voor alfanumeriek |
Min waarde | <na> |
Max waarde | <na> |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | SENDER=0032441041106 |
Opmerkingen | Meer details over foutafhandeling zie “Return Values” onderaan de pagina. |
Body
Inhoud van de SMS
Optie | |
Vereist | ja |
Type | GSM 7-bit alfabet voor tekstberichten |
Min lengte | 1 |
Max lengte | 160 karakters voor tekst bericht (default : ALLOWLONG=0) 612 karakters (ALLOWLONG=1) Wanneer u Long SMS gebruikt, zal het systeem het bericht automatisch verdelen in 153 karakters per sms. |
Min waarde | <na> |
Max waarde | <na> |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | BODY=This%20is%20a%20test%20SMS |
Opmerkingen | Meer details over karakters zie “Field types” onderaan de pagina. |
Service
Referentie tag kan gebruikt worden om een filter in statistieken te creëren.
Optie | |
Vereist | nee |
Type | Alfanumeriek |
Min lengte | 1 |
Max lengte | 10 |
Min waarde | <na> |
Max waarde | <na> |
Waardes | <na> |
Default waarde | <none> |
Voorbeeld | SERVICE=Client1 |
Route
Om de Spryng Business, Spryng Economy of Specific User route te selecteren.
Optie | |
Vereist | ja |
Type | Vooraf gedefinieerd |
Min lengte | <na> |
Max lengte | <na> |
Min waarde | <na> |
Max waarde | <na> |
Waardes | BUSINESS, ECONOMY, 0-9 (Specific User route) |
Default waarde | BUSINESS |
Voorbeeld | ROUTE=BUSINESS |
Allowlong
Als u Long SMS wenst te versturen
Optie | |
Vereist | Alleen als u Long SMS wenst te versturen |
Type | Vooraf gedefinieerd |
Min lengte | <na> |
Max lengte | <na> |
Min waarde | <na> |
Max waarde | <na> |
Waardes | 0,1 |
Default waardes | 0 |
Voorbeeld | ALLOWLONG=1 |
Opmerkingen | Wanneer u Long SMS gebruikt, zal het systeem het bericht automatisch verdelen in 153 karakters per sms. |
Return values
Return Waarde | |
1 | Succesvol ontvangen |
100 | Missende parameter |
101 | Gebruikersnaam te lang |
102 | Gebruikersnaam te kort |
103 | Wachtwoord te kort |
104 | Wachtwoord te lang |
105 | Bestemming te kort |
106 | Bestemming te lang |
107 | Afzender te lang |
108 | Afzender te kort |
109 | Inhoud te kort |
110 | Inhoud te lang |
200 | Veiligheidsfout |
201 | Onbekende route |
202 | Route toegang overtreding |
203 | Onvoldoende credits |
301 | Hoofdaccount heeft onvoldoende credits |
800 | Technische fout |
Delivery Reports
U kunt uw delivery reports instellen door in te loggen op uw account op https://www.spryng.nl en door “instellingen” in uw SMS Dashboard te selecteren. Hier kunt u de URL van uw script (servlet, php script, perl, etc…) invoeren waar u uw delivery reports op wenst te ontvangen. Dit script zou 2 parameters moeten bevatten, welke verstuurd wordt via een HTTP GET. Wanneer u een delivery report aanvraagt, moet u niet meer dan 1 DESTINATION specificeren in het verzoek. De volgende status waardes zullen verzonden worden:
Status waarde | |
10 | Afgeleverd |
20 | Niet afgeleverd |
30 | Verzonden |
Voorbeeld: REFERENCE=abc123&STATUS=10
Het HTTP verzoek uitgevoerd door Spryng moet beantwoord worden door uw server met de status code 200, wat betekent dat het bericht succesvol is geaccepteerd door uw systeem. Wanneer de HTTP server niet bereikt kan worden en als het bijvoorbeeld terugkomt met 500 internal server error, neemt Spryng aan dat het bericht niet succesvol is geaccepteerd door uw systeem en het verzoek zal eenmaal per minuut opnieuw verzonden worden. Het bericht zal niet eeuwig opnieuw verzonden worden, de huidige instelling is 24 uur.
Field types
Numeriek: karakters 0 tot 9 Alfanumeriek: karakter van ISO-8859-1
MSISDN-numeriek karakters 0 tot 9 GSM 7-bit alfabet (toegestane karakters in tekst berichten): de karakters ‘a‘ tot en met ‘z‘, ‘A‘ tot en met ‘Z‘,
‘0‘ tot en met ‘9‘, linefeed, carriage return en
@£$¥èéùìòÇØøÅå_€ÆæßÉ!”#¤%&'()*+,-./:;<=>?¡ÄÖÑܧ¿äöñüà
Om het € teken te gebruiken, moet u %80 invoeren. Als u daadwerkelijk het euroteken gebruikt geldt deze als 2 karakters:
€ = 2 karakters
E = 1 karakter.
Credit amount API
POST
https://api.spryngsms.com/api/check.php