Kijk even a.u.b. naar Hoe voordat je met alles voor goed begint. Bedankt!

SMS API versturen

Functie: sendSms

Verstuurt GSM en Unicode SMS berichten. Voegt lange berichten samen Automatisch t/m vijf (765 characters).

Geeft een JSON object welk de aanvraag bevestigt (of een fout aangeeft).

POST/GET Voorbeeld

username=xxx&password=yyyy&function=sendSms &number=+491234567890&message=Have%20a%20nice%20day! &senderid=+44987654321&callbackurl=http://www.my-server.com/callback.php

JSON Voorbeeld

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendSms",
    "number":"+491234567890",
    "message":"Have a nice day!",
    "senderid":"+449876543210",
    "callbackurl":"http://www.my-server.com/callback.php"
}

Verplichte Parameters

Parameter	Beschrijving	Type

number	Het mobiel telefoonnummer in internationaal formaat. Bijvoorbeeld: 49123456789 of +49123456789 of 0049123456789	string

message	De berichttekst. Mijn-Cool-SMS ontdekt automatisch de input codering en verwerkt de SMS dienovereenkomstig als GSM of Unicode.. Je kunt gebruik maken van de optionele Unicode parameter om een bepaalde codering in kracht te zetten. Als Unicode op true ingesteld is, wordt de SMS als Unicode verstuurd en de bericht parameter moet worden voorzien in Unicode UCS2 notatie. Als Unicode op false ingesteld is, wordt de SMS verstuurd als GSM en het bericht parameter moet tekens bevatten uit de GSM7 alfabet alleen. Lange berichten worden automatisch samengevoegd. Maximum 765 lettertekens voor GSM berichten of 335 voor Unicode. Let op dat je altijd de unicode parameter moet gebruiken bij het verzenden van GET-verzoeken.	string

Tip: Meer informatie over GSM, Unicode en UCS2.

Optionele Parameters

Parameter	Beschrijving	Type

unicode	Dwingt een Unicode of GSM codering op het bericht. Als op true ingezet, moet het bericht parameter worden ingediend in UCS2 notatie. Als false ingezet, moet het bericht parameter lettertekens uit de GSM7 alfabet alleen bevatten. Indien niet ingesteld of ingesteld op NULL, gaat My-Cool-SMS automatisch de input-codering ontdekken.	boolean

senderid	Mobiel telefoonnummer in internationaal formaat, bijvoorbeeld: +44123456789 of alfanumerieke afzende id t/m 11 lettertekens, biijvoorbeeld: Bedrijf	string

scheduletime	Verstuurd het bericht in een bepaalde tijd. Gebruik ATOM formaat en tijdzone, bijv.: "2011-04-17T17:59:36.67+08" of "2011-04-17 17:59:36-02"	timestamp with timezone

callbackurl	Callback URL om status updates en afleveringsrapporten voor dit bericht te ontvangen. Bijvoorbeeld: http://www.myserver.com/callback.php	string

Tip: Meer informatie over afleveringsrapporten callbacks.

Voorbeeld van een gelukte respons

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "body":"Have a nice day!",
    "bodyucs2":"0048006100760065002000610020006E00690063006500200064",
    "bodygsm7":"486176652061206E6963652064617921",
    "number":"+491234567890"
    "senderid":"+449876543210",
    "senderidenabled":true,
    "unicode":false,
    "numchars":321,
    "escapenumchars":0,
    "smscount":3,
    "charge":0.112,
    "balance":752.121,
    "callbackurl":"http://www.my-server.com/callback.php"
}

Gelukte Respons Gegevens

Key	Beschrijving	Type

success	Toond aan of het verzoek met succes kon worden verwerkt of niet	boolean

smsid	Uniek ID voor deze SMS. Dient te worden opgeslagen door de klantenkant en worden gebruikt als referentie voor afleveringsrapporten	string(32)

body	De berichttekst in Unicode	string

bodyucs2	De berichttekst in UCS2 bytecode notatie	string

bodygsm7	De berichttekst in GSM7 bytecode notatie (of NULL als het bericht als Unicode verzonden werd)	string \|\| NULL

senderid	Geeft aan of het doelnummer dynamische afzender id ondersteunt	boolean

unicode	Geeft aan of het bericht is verzonden als Unicode of GSM	boolean

numchars	Geeft aan hoeveel lettertekens het bericht bevatte	integer

escapenumchars	Geeft aan hoeveel lettertekens moesten worden ontsnapt (en geteld als twee lettertekens in GSM)	integer

smscount	Geeft of het bericht samengevoegd in een lange SMS is en het aantal van gebruikte SMS aan	integer

charge	Geeft aan hoeveel jouw account voor dit bericht in rekening gebracht werd	float

balance	Resterende saldo in jouw account	float

callbackurl	Callback URL waar status updates en afleveringsrapporten voor dit bericht naartoe werden verstuurd.	string

Functie Specifieke API Fouten

Foutcode	Fout Beschrijving

210	Het nummer schijnt ongeldig te zijn

211	De bericht parameter is leeg

212	De bericht parameter is te lang

213	De unicode parameter is ingesteld Unicode te forceren, maar de bericht parameter werd niet ingediend in UCS2 notatie.

214	De unicode parameter is ingesteld GSM te forceren, maar de bericht parameter werd ingediend in UCS2 notatie

215	De unicode parameter is ingesteld GSM te forceren, maar de bericht parameter bevat lettertekens niet uit de GSM7 alfabet

216	The input for Sender ID is invalid. You may use a phone number or an alphanumeric text with up to eleven characters (A-Z, a-z, 0-9 and the dash symbol).

217	Shortcode Afzender IDs zijn niet toegelaten

218	De callbackurl parameter schijnt ongeldig te zijn

219	De plan tijd schijnt ongeldig. Gebruik ATOM formaat en tijdzone, bijv.: "2011-04-17T17:59:36.67+08" of "2011-04-17 17:59:36-02"

Tip: Zie ook de sectie over generieke fouten

Inkomende SMS API

Callback: pushIncomingSms

My-Cool-SMS stuurt de SMS gegevens automatisch naar jouw server door als een callback URL voor jouw nummer in jouw inbox instellingen gedefinieerd is. Je kunt jouw callback URL in jouw inbox instellingen via de My-Cool-SMS web interface bewerken.

Callback Voorbeeld

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Incoming SMS Callback
Content-Length: n
Cache-Control: no-cache
Connection: close

{
   "from":"+1230987654321",
   "fromcountrycode":"US",
   "to":"+440987654321",
   "unicode":false,
   "smscount":1,
   "body":"Have a nice day with incoming SMS!",
   "bodyucs2":"0048006100760065002000610020006e00690063006500200064",
   "bodygsm7":"5374616666206D6565746925",
   "numchars":54,
   "escapenumchars":0,
   "cost":"0.010"
}

Tip: Zie here voor meer informatie over het gebruiken van JSON callbacks.

Callback Gegevens

Key	Beschrijving	Type

from	De afzender ID waar het bericht mee werd verstuurd. Het kan een nummer in internationaal formaat of een alfanumerieke afzender id zijn.	string

fromcountrycode	Bevat de twee lettertekens code ISO landnummer van de afzender indien de van parameter een nummer is. Bevat NULL als de van parameter alfanumeriek is.	string(2) \|\| NULL

to	Het nummer waar het bericht naartoe werd verstuurd (jouw virtueel telefoonnummer).	string

unicode	Geeft aan of het bericht in Unicode of GSM werd verstuurd.	boolean

smscount	Geeft of het bericht samengevoegd in een lange SMS is en het aantal van gebruikte SMS aan	integer

body	De berichttekst in Unicode	string

bodyucs2	De berichttekst in UCS2 bytecode notatie	string

bodygsm7	De berichttekst in GSM7 bytecode notatie (of NULL als het bericht als Unicode verzonden werd)	string

numchars	Geeft aan hoeveel lettertekens het bericht bevatte	integer

escapenumchars	Geeft aan hoeveel lettertekens moesten worden ontsnapt (en geteld als twee lettertekens in GSM)	integer

cost	Geeft aan hoeveel jouw account voor dit bericht in rekening gebracht werd	float

Functie: getIncomingSms

Queries the server for received SMS text messages. Returns a status summary for the selected virtual number and an array containing incoming SMS. Can be customized by using the optional parameters.

POST/GET Voorbeeld

username=xxx&password=yyy&function=getIncomingSms&virtualnumber=+449876543201

JSON Voorbeeld

{
    "username":"xxx",
    "password":"yyy",
    "function":"getIncomingSms",
    "virtualnumber":"+449876543201"
}

Verplichte Parameters

Parameter	Beschrijving	Type

virtualnumber	The virtual number for which sms text messages should be fetched	string

Optionele Parameters

Parameter	Beschrijving	Type

thresholdid	Only messages with a higher id should be returned. This parameter is required to only receive messages that have been received after the ones that were fetched already. Every message fetched with the getIncomingSms function contains a unique id, which should be stored on client side in order to use it here. Defaults to 0.	integer

limit	The maximum amount of messages to be returned. Defaults to 25. If set to 0, no limit will be applied.	integer

order	Specifies the order in which the results should be returned. Can be "ASC" or "DESC". Defaults to "DESC"	string

thresholdoperator	Specifies whether the returned messages should have higher or lower ids as compared to the id provided in thresholdid. Can be either "gt" (greater than) or "lt" (lower than). Defaults to "gt"	string(2)

Voorbeeld van een gelukte respons

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "messages":[
      {
         "id":201,
         "virtualnumber":"+449876543201",
         "senderid":"+886983029751",
         "body":"Have a nice day!",
         "bodyucs2":"AAAA",
         "bodygsm7":"AA",
         "unicode":false,
         "timestamp":"2011-08-10 00:08:37.488+08",
         "numchars":16,
         "escapechars":0,
         "smscount":1
      }
   ]
}

Gelukte Respons Gegevens

Key	Beschrijving	Type

success	Toond aan of het verzoek met succes kon worden verwerkt of niet	boolean
total	The total number of messages on this virtual number	integer
fetched	The number of messages that were fetched	integer
maxid	The "maxid" parameter indicates the highest unique id (last message) on this virtual number. This value should be stored and use for future queries as "thresholdid" parameter in order to just fetch new messages.	integer
messages	Contains an array of SMS text objects (with self-explaining attribute names, see example).	array

Functie Specifieke API Fouten

Foutcode	Fout Beschrijving

232	Het nummer schijnt ongeldig te zijn

233	The virtual number is either invalid or not registered with this user account. Please contact service@my-cool-sms.com for assistance.

234	The provided thresholdid is invalid

235	Ongeldige limiet parameter

236	Invalid order parameter

Tip: Zie ook de sectie over generieke fouten

Saldo Lookup API

Functie: getBalance

Retourneert een JSON object welk de resterende saldo op jouw rekening bevat (of een fout aangeeft).

POST/GET Voorbeeld

username=xxx&password=yyyy&function=getBalance

JSON Voorbeeld

{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

Voorbeeld van een gelukte respons

{
    "success":true,
    "balance":752.210
}

Gelukte Respons Gegevens

Key	Beschrijving	Type

success	Toond aan of het verzoek met succes kon worden verwerkt of niet	boolean

balance	Resterende saldo in Euro	float

Afleveringsrapport API

Er bestaan twee mogelijkheden om afleveringsrapporten van My-Cool-SMS te ontvangen. Je kunt de My-Cool-SMS server met getDeliveryReport pollen of HTTP callbacks op een URL op jouw server met pushDeliveryReport ontvangen. Weet wel dat afleveringsrapporten voor mailings alleen maar via getDeliveryReport te ontvangen zijn.

Functie: getDeliveryReport

Retourneert een afleveringsrapport voor een enkele SMS (vertuurd met sensSms) of een groepmailing (verstuurd mer sendMailing). Als een groepmailing afleveringsrapport verzoekt is (door de optioneel groepkey parameter op true te zetten), kan het geretourneerde object een samenvatting (default) of individuele afleveringsrapporten voor elke enkele ontvanger bevatten (door de optionele parameter mailingdetails op true te zetten)

POST/GET Voorbeeld

username=xxx&password=yyyy&function=getDeliveryReport &id=ce184cc0a6d1714d1ac763f4fe89f521

JSON Voorbeeld

{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

Verplichte Parameters

Parameter	Beschrijving	Type

id	Referentie ID. Of een sms id (als geretourneerd door sendSms) of een mailinggroep key (als geretourneerd door sendMailing). Indien een groep key is gebruikt, moet de optionele parameter groepkey op true gezet zijn.	string

Optionele Parameters

Parameter	Beschrijving	Type

groupkey	Stel op true als de id parameter van een groep key was voorzien en je wil dat het afleveringsrapport voor een mailing (in plaats van een enkele SMS) wordt geretourneerd. Defaults op false.	string

mailingdetails	Stel op true als je een afzonderlijke afleveringsrapport voor iedere ontvanger van een mailing wilt in aanvulling op de samenvatting. Defaults op false.	string

Voorbeeld van een gelukte respons: groupkey=false (Default)

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}

Gelukte Respons Gegevens: groupkey=false (Default)

Key	Beschrijving	Type

success	Toond aan of het verzoek met succes kon worden verwerkt of niet	boolean

smsid	De sms id waar het afleveringsrapport mee wordt geassocieerd.	string

status	Geeft de status van deze SMS aan	string

Tip: Zie hier voor meer informatie over de status codes.

Voorbeeld van een gelukte respons: groupkey=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0
}

Tip: Zie hier voor meer informatie over de status codes.

Voorbeeld van een gelukte respons: groupkey=true&mailingdetails=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0,
    "details":[
        {
            "recipient":"+1230987654321",
            "status":"SMS_STATUS_DELIVERED"
        },
        {
            "recipient":"+1230987654322",
            "status":"SMS_STATUS_DELIVERED"
        }, 
        (...)
    ]
}

Tip: Zie hier voor meer informatie over de status codes.

Functie Specifieke API Fouten

Foutcode	Fout Beschrijving

223	Onbekende SMS ID

224	Onbekende Groep Key

Tip: Zie ook de sectie over generieke fouten

Functie: getRecentReports

Retourneert een JSON object met afleveringsrapporten voor de meest recent verzonden berichten.

POST/GET Voorbeeld

username=xxx&password=yyyy&function=getRecentReports&limit=10

JSON Voorbeeld

{
    "username":"xxx",
    "password":"yyy",
    "function":"getRecentReports",
    "limit":10
}

Verplichte Parameters

Parameter	Beschrijving	Type

limit	Geeft aan hoeveel rapporten moeten worden ingeleverd	integer

Voorbeeld van een gelukte respons

{
   "success":true,
   "reports":[
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:08:37.233+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:01:03.338+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day with long Unicode messages! \u7e41",
         "bodyucs2":"0048006100760065002000610020006e00690063006500",
         "bodygsm7":"",
         "unicode":true,
         "timesent":"2011-04-18 21:53:24.787+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      (...)
   ]
}

Gelukte Respons Gegevens

Key	Beschrijving	Type

success	Toond aan of het verzoek met succes kon worden verwerkt of niet	boolean

number	Het doelnummer	string

senderid	De afzender id waar het bericht mee werd verstuurd	string

body	De berichttekst in Unicode	string

bodyucs2	De berichttekst in UCS2 bytecode notatie	string

bodygsm7	De berichttekst in GSM7 bytecode notatie (of NULL als het bericht als Unicode verzonden werd)	string

unicode	Geeft aan of het bericht is verzonden als Unicode of GSM	boolean

timesent	Tijd wanneer het bericht werd verstuurd	timestamp with time zone

status	Geeft de status van deze SMS aan	string

Tip: Zie hier voor meer informatie over de status codes.

Functie Specifieke API Fouten

Foutcode	Fout Beschrijving

225	Ongeldige limiet parameter

Tip: Zie ook de sectie over generieke fouten

Callback: pushDeliveryReport

My-Cool-SMS stuurt een afleveringsrapport automatisch naar jouw server door als de callbackurl parameter angezet bij het afzenden via sendSms functie is. De callback werd als ruwe gegevens JSON verzoek verstuurd.

Callback Voorbeeld

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Delivery Report
Content-Length: n
Cache-Control: no-cache
Connection: close

{
    "smsid":"498673a1f58df975ab95da33884d9e14",
    "status":"SMS_STATUS_DELIVERED"
}

Tip: Zie here voor meer informatie over het gebruiken van JSON callbacks.

Callback Gegevens

Key	Beschrijving	Type

smsid	Uniek ID en referentie voor de SMS. De smsid werd in het gelukte respons op de sendSms functie geretourneerd	string(32)

status	Geeft de status van deze SMS aan	string

Status Referentie

Status	Beschrijving

SMS_STATUS_QUEUED	Wachtrij - Het bericht staat in de rij te wachten en werd nog niet verstuurd.

SMS_STATUS_AT_CARRIER	Bij de Carrier - Het bericht werd naar de netwerkprovider verstuurd en wordt als 'geleverd' getoond zodra het bij het ontvangende mobieltje aangekomen is. Weet wel dat in sommige gevallen de carriers geen afleveringsrapport leveren. Het bericht blijft getoond als 'bij de carrier' hoewel het met succes werd geleverd.

SMS_STATUS_DELIVERY_DELAYED	Aflevering Vertraagd - De berichtaflevering werd vertraagd

SMS_STATUS_DELIVERED	Geleverd - Het bericht werd met succes naar het doelnummer geleverd

SMS_STATUS_BOUNCED	Afgestoten - Het bericht werd afgestoten door het doelnetwerk. Mogelijke redenen zijn een ongeldig mobiel nummer of afzender id, het doelmobieltje is te lang buiten het netwerk of netwerkopstoppingen bij de carrier.

SMS_STATUS_EXPIRED	Verlopen - Dit bericht is verstreken en kon niet worden afgeleverd. Dit probleem ontstaat gewoonlijk als het doel telefoonnummer af of voor een lange tijd buiten het netwerkbereik is.

SMS_STATUS_ERROR	Mislukt - Aflevering is mislukt (je werd voor dit bericht niet in rekening gebracht). Mogeljike redenen voor mislukte aflevering zijn, dat My-Cool-SMS niet weet tot welk netwerk het telefoonnummer behoord (a.u.b. support contacteren als je zeker ervan bent dat het telefoonnummer correct iis) of een voorlopig netwerkfout.

Mailinglijst API

Functie: sendMailing

Verstuurt een SMS naar de hele mailinglijst. Tip: Je kunt mailinglijsten in jouw My-Cool-SMS web interface maken en beheren.

Retourneert een JSON object welk het verzoek bevestigt (of een fout aangeeft).

POST/GET Voorbeeld

username=xxx&password=yyyy&function=sendMailing &uniqueid=75F3FAB&message=Staff%20meeting%20in%2020%20minutes. &senderid=MyCompany

JSON Voorbeeld

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendMailing",
    "uniqueid":"75F3FAB",
    "message":"Staff meeting in 20 minutes. Balcony meeting room.",
    "senderid":"MyCompany"
}

Verplichte Parameters

Parameter	Beschrijving	Type

uniqueid	De unieke id van de mailinglijst. Je kunt jouw unieke ids in jouw mailinglijst management interfaces op de webpagina vinden.	string

message	De berichttekst. Mijn-Cool-SMS ontdekt automatisch de input codering en verwerkt de SMS dienovereenkomstig als GSM of Unicode.. Je kunt gebruik maken van de optionele Unicode parameter om een bepaalde codering in kracht te zetten. Als Unicode op true ingesteld is, wordt de SMS als Unicode verstuurd en de bericht parameter moet worden voorzien in Unicode UCS2 notatie. Als Unicode op false ingesteld is, wordt de SMS verstuurd als GSM en het bericht parameter moet tekens bevatten uit de GSM7 alfabet alleen. Lange berichten worden automatisch samengevoegd. Maximum 765 lettertekens voor GSM berichten of 335 voor Unicode. Let op dat je altijd de unicode parameter moet gebruiken bij het verzenden van GET-verzoeken.	string

Tip: Meer informatie over GSM, Unicode en UCS2.

Optionele Parameters

Parameter	Beschrijving	Type

unicode	Dwingt een Unicode of GSM codering op het bericht. Als op true ingezet, moet het bericht parameter worden ingediend in UCS2 notatie. Als false ingezet, moet het bericht parameter lettertekens uit de GSM7 alfabet alleen bevatten. Indien niet ingesteld of ingesteld op NULL, gaat My-Cool-SMS automatisch de input-codering ontdekken.	boolean

senderid	Mobiel telefoonnummer in internationaal formaat, bijvoorbeeld: +44123456789 of alfanumerieke afzende id t/m 11 lettertekens, biijvoorbeeld: Bedrijf	string

scheduletime	Verstuurd het bericht in een bepaalde tijd. Gebruik ATOM formaat en tijdzone, bijv.: "2011-04-17T17:59:36.67+08" of "2011-04-17 17:59:36-02"	timestamp with time zone

Tip: Meer informatie over afleveringsrapporten callbacks.

Voorbeeld van een gelukte respons

{
    "success":true,
    "groupkey":"041d3b026a50669481695dcf9e1985e4",
    "body":"Staff meeting in 20 minutes. Balcony meeting room.",
    "bodyucs2":"005300740061006600660020006D0065006500740069",
    "bodygsm7":"5374616666206D656574696E672069",
    "uniqueid":"75F3FAB"
    "senderid":"MyCompany",
    "senderidenabled":true,
    "unicode":false,
    "numchars":62,
    "escapenumchars":0,
    "smscount":1,
    "subscribers":79,
    "charge":3.212,
    "balance":752.121
}

Gelukte Respons Gegevens

Key	Beschrijving	Type

success	Toond aan of het verzoek met succes kon worden verwerkt of niet	boolean

groupkey	Unieke referentie key voor dit mailing. Dient door de klantenkant opgeslagen en als referentie voor afleveringsrapporten gebruikt worden.	string(32)

body	De berichttekst in Unicode	string

bodyucs2	De berichttekst in UCS2 bytecode notatie	string

bodygsm7	De berichttekst in GSM7 bytecode notatie (of NULL als het bericht als Unicode verzonden werd)	string \|\| NULL

uniqueid		string(7)

senderid	Geeft aan of het doelnummer dynamische afzender id ondersteunt	boolean

unicode	Geeft aan of het bericht is verzonden als Unicode of GSM	boolean

numchars	Geeft aan hoeveel lettertekens het bericht bevatte	integer

escapenumchars	Geeft aan hoeveel lettertekens moesten worden ontsnapt (en geteld als twee lettertekens in GSM)	integer

smscount	Geeft of het bericht samengevoegd in een lange SMS is en het aantal van gebruikte SMS aan	integer

subscribers	Aantal abonnees naar wie het bericht werd verstuurd	integer

charge	Geeft aan hoeveel jouw account voor dit bericht in rekening gebracht werd	float

balance	Resterende saldo in jouw account	float

Functie Specifieke API Fouten

Foutcode	Fout Beschrijving

220	De unieke id wordt met geen van uw mailing lijsten geassocieerd

Tip: Zie ook de sectie over generieke fouten

Functie: addSubscriber

Voert een nieuwe abonnee naar de mailing lijst toe. Updates een abonnee, indien het ingediende nummer al in de doel mailing lijst bestaat.

Retourneert een JSON object welk het verzoek bevestigt (of een fout aangeeft).

POST/GET Voorbeeld

username=xxx&password=yyyy&function=addSubscriber &uniqueid=75F3FAB&number=+1230987654321&title=Ms&firstname=Marylin &lastname=Monroe&company=Hollywood

JSON Voorbeeld

{
    "username":"xxx",
    "password":"yyy",
    "function":"addSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321",
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood"
}

Verplichte Parameters

Parameter	Beschrijving	Type

number	Het nummer van de abonne in internationaal formaat. Bijvoorbeeld: 49123456789 of +49123456789 of 0049123456789	string

uniqueid	De unieke id van de mailinglijst. Je kunt jouw unieke ids in jouw mailinglijst management interfaces op de webpagina vinden.	string

Optionele Parameters

Parameter	Beschrijving	Type

title	De titel van de abonnee	varchar(16)

firstname	Voornaam van de abonnee	varchar(32)

lastname	Achternaam van de abonnee	varchar(32)

company	Bedrijf van de abonnee	varchar(64)

Voorbeeld van een gelukte respons

{
    "success":true,
    "number":"+1230987654321"
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood",
    "subscribercost":0.019,
    "senderidenabled":true,
    "maxcharsgsm":765,
    "maxcharsunicode":335,
    "countrycode":"US",
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

Gelukte Respons Gegevens

Key	Beschrijving	Type

success	Toond aan of het verzoek met succes kon worden verwerkt of niet	boolean

number	Genormaliseerd telefoonnummer van de nieuwe abonnee	string

title	Titel van de nieuwe abonnee	string

firstname	Voornaam van de nieuwe abonnee	string

lastname	Achternaam van de nieuwe abonnee	string

company	Bedrijf van de nieuwe abonnee	string

subscribercost	Kosten per bericht naar deze abonnee	float

senderidenabled	Geeft aan of de abonnee de afzender id ondersteunt	boolean

maxcharsgsm	Geeft aan hoeveel lettertekens voor GSM berichten de abonnee ondersteunt	integer

maxcharsunicode	Geeft aan hoeveel lettertekens voor Unicode berichten de abonnee ondersteunt	integer

countrycode	De landnummer van de abonnee (Twee lettertekens ISO standaard formaat)	string(2)

mailinglistcost	De nieuwe totale kosten voor mailings aan deze lijst	float

mailinglistsubscribers	Het nieuwe aantal abonnees op deze mailinglijst	integer

Functie Specifieke API Fouten

Foutcode	Fout Beschrijving

221	Input voor {field} is te lang.

Tip: Zie ook de sectie over generieke fouten

Functie: updateSubscriber

Zie Functie: addSubscriber

Functie: deleteSubscriber

Verwijdert een abonee van de mailinglijst (gebruikt het telefoonnummer als referentie).

Retourneert een JSON object welk het verzoek bevestigt (of een fout aangeeft).

POST/GET Voorbeeld

username=xxx&password=yyyy&function=deleteSubscriber &uniqueid=75F3FAB&number=+1230987654321

JSON Voorbeeld

{
    "username":"xxx",
    "password":"yyy",
    "function":"deleteSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321"
}

Verplichte Parameters

Parameter	Beschrijving	Type

uniqueid	De unieke id van de mailinglijst. Je kunt jouw unieke ids in jouw mailinglijst management interfaces op de webpagina vinden.	string

number	Het nummer van de abonnee die van de mailinglijst te verwijderen is.	string

Voorbeeld van een gelukte respons

{
    "success":true,
    "number":"+1230987654321"
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

Gelukte Respons Gegevens

Key	Beschrijving	Type

success	Toond aan of het verzoek met succes kon worden verwerkt of niet	boolean

number	De genormaliseerde telefoonnummer van de verwijderde abonnee	string

mailinglistcost	De nieuwe totale kosten voor mailings aan deze lijst	float

mailinglistsubscribers	Het nieuwe aantal abonnees op deze mailinglijst	integer

Functie Specifieke API Fouten

Foutcode	Fout Beschrijving

220	De unieke id wordt met geen van uw mailing lijsten geassocieerd

222	Er bestaat geen abonnee met dit telefoonnummer op deze mailinglijst

Tip: Zie ook de sectie over generieke fouten

Utils API

Functie: doHlrLookup

Voert een Home Location Register (HLR) lookup uit en retourneert de MSC, MCC, MNC, INSI van het nummer alsmede informatie over de naam van het netwerk, of het nummer is momenteel roaming en of het is geporteerd naar een ander netwerk.

Tip: Meer informatie over HLR, IMSI, MCC, MNC en MSC.

JSON Voorbeeld

{
    "username":"xxx",
    "password":"yyy",
    "function":"doHlrLookup",
    "number":"+491234567890"
}

Verplichte Parameters

Parameter	Beschrijving	Type

number	Het nummer waar het HLR Lookup voor uit te voeren is in internationaal formaat. Bijvoorbeeld: 49123456789 of +49123456789 of 0049123456789	string

Voorbeeld van een gelukte respons

{
    "success":true,
    "status":"HLR_STATUS_OK",
    "number":"+49178873xxxxx",
    "imsi":"262031350393955",
    "mcc":"262",
    "mnc":"03",
    "msin":"1350393955",
    "servingmsc":"88693542",
    "servinghlr":"491770112000",
    "originalnetworkname":"E-Plus",
    "originalnetworkprefix":"178",
    "originalcountryname":"Germany",
    "originalcountrycode":"DE",
    "originalcountryprefix":"+49",
    "roamingcountryname":"Taiwan",
    "roamingcountrycode":"TW",
    "roamingcountryprefix":"+886",
    "roamingnetworkname":"Taiwan Mobile",
    "portednetworkname": null,
    "isported":false,
    "iscorrect":true,
    "isroaming":true,
    "charge":0.010
}

Gelukte Respons Gegevens

Key	Beschrijving	Type

success	Toond aan of het verzoek met succes kon worden verwerkt of niet	boolean

status	Geeft de status van het lookup aan. Zie de HLR status referentie tabel voor meer informatie.	string

number	Het nummer waar het HLR lookup voor werd uitgevoerd.	string

imsi	International Mobile Subscriber Identity (IMSI). Unieke identificatie geasocieerd met het doelnummer.	string

mcc	Het Mobile Country Code (MCC)	string

mnc	Het Mobile Network Code (MNC), dit kunnen ofwel 2 cijfers (Europese norm) ofwel 3 cijfers (Noord-Americaanse norm) zijn.	string

msin	Het Mobile Subscription Identification Number (MSIN) binnen de klantenbasis van het netwerk.	string

servingmsc	Het Mobile Switching Center (MSC), die verantwoordelijk is voor de routering van de SMS.	string

servinghlr	Het Home Location Register (HLR) waar het doelnummer mee geasocieerd is.	string

originalnetworkname	Het mobiele netwerk waar het nummer toe behoort (of oorspronkelijk toe behoorde als dit een ported nummer is)	string

originalnetworkprefix	Het mobiele netwerk prefix waar dit nummer toe behoort (of oorspronkelijk toe behoorde als dit een ported nummer is)	string

originalcountryname	Het land waar dit nummer toe behoort.	string

originalcountrycode	Het twee lettertekens ISO landnummer waar dit nummer toe behoort	string

originalcountryprefix	Het prefix van het land waar dit nummer toe behoort	string

roamingcountryname	Het land waar dit nummer momenteel in dwaalt	string

roamingcountrycode	Het twee lettertekens ISO landnummer waar dit nummer momenteel in dwaalt	string

roamingcountryprefix	Het prefix van het land waar dit nummer momenteel in dwaalt	string

roamingnetworkname	The network the cell phone is currently roaming with	string

portednetworkname	The network the number has been ported to	string

isported	Geeft aan of dit een ported nummer is	boolean

iscorrect	Geeft aan of dit nummer geldig is	boolean

isroaming	Geeft aan of dit nummer momenteel (in een ander land) dwaalt	boolean

charge	De prijs van het HLR lookup (0.01 EUR)	numeric

Tip: Meer informatie over HLR, IMSI, MCC, MNC en MSC.

Functie Specifieke API Fouten

Foutcode	Fout Beschrijving

210	Het nummer schijnt ongeldig te zijn

226	HLR lookup mislukt. Wordt niet in rekening gebracht.

Tip: Zie ook de sectie over generieke fouten

HLR Status Referentie

Status	Beschrijving

HLR_STATUS_UNKNOWN_NUMBER	Dit nummer bestaat niet of het konde in geen HLR worden gelocaliseerd. SMS gaat niet aankomen.

HLR_STATUS_OK	Dit nummer bestaat en het HLR lookup verliep met succes. SMS gaat aankomen.

HLR_STATUS_NOT_OK	Dit nummer is buiten het netwerk voor een zeer lange tijd of is uitgeschakeld door de mobiele netwerkaanbieder. SMS gaat niet aankomen.

HLR_STATUS_FAILED	HLR lookup mislukt. Wordt niet in rekening gebracht.

Functie: toUCS2

UCS2 codeert een bepaalde Unicode-tekenreeks

Belangrijk: toUCS2 vereist een JSON verzoek.

JSON Voorbeeld

{
    "username":"xxx",
    "password":"yyy",
    "function":"toUCS2",
    "str":"繁体中文"
}

Verplichte Parameters

Parameter	Beschrijving	Type

number	Het nummer waar het HLR Lookup voor uit te voeren is in internationaal formaat. Bijvoorbeeld: 49123456789 of +49123456789 of 0049123456789	string

Optionele Parameters

Parameter	Beschrijving	Type

Voorbeeld van een gelukte respons

{
    "success":true,
    "ucs2":"7E414F534E2D6587"
}

Gelukte Respons Gegevens

Key	Beschrijving	Type

success	Toond aan of het verzoek met succes kon worden verwerkt of niet	boolean

ucs2	De ingediende string in UCS2 notatie	string

Functie Specifieke API Fouten

Geen

Tip: Zie ook de sectie over generieke fouten

Functie: fromUCS2

Decodeert een gegeven UCS2 string

POST/GET Voorbeeld

username=xxx&password=yyyy&function=fromUCS2 &str=0048006100760065002000610020006E00690063006500200064

JSON Voorbeeld

{
    "username":"xxx",
    "password":"yyy",
    "function":"fromUCS2",
    "str":"7E414F534E2D6587"
}

Verplichte Parameters

Parameter	Beschrijving	Type

str	De UCS2 string te decoderen	string

Voorbeeld van een gelukte respons

{
    "success":true,
    "decoded":"繁体中文"
}

Gelukte Respons Gegevens

Key	Beschrijving	Type

success	Toond aan of het verzoek met succes kon worden verwerkt of niet	boolean

decoded	De gedecodeerde UCS2 string in Unicode	string

Functie Specifieke API Fouten

Foutcode	Fout Beschrijving

201	Ongeldig UCS2 Input

Tip: Zie ook de sectie over generieke fouten

Foutreacties

All API errors responses have a standardized JSON structure with a success, errorcode and errordescription attribute.

Voorbeeld van een mislukte respons

{
    "success":false,
    "errorcode":103,
    "errordescription":"Verplichte parameter ontbreekt: senderid"
}

Gelukte Respons Gegevens

Key	Beschrijving	Type

success	Toond aan of het verzoek met succes kon worden verwerkt of niet	boolean

errorcode	Een driecijferig foutcode	string(3)

errordescription	De fout beschrijving	string

Functie Specifieke API Fouten

Sommige functies hebben specifieke API foutcodes die uniek voor deze bijzondere functie zijn. In dit geval hebben de foutcodes de 2xx formaat. A.u.b. naar de functie documentatie voor individuele foutcodes kijken.

Generieke API Fouten

Functie specifieke fouten bijkomend, enig API verzoek kan in een generieke API fout met foutcode formaat 1xx resulteren.

Generieke Foutcodes

Foutcode	Fout Beschrijving

101	Inloggen niet gelukt. Foutief Gebruikersnaam of Wachtwoord.

102	Dit account wordt nog niet geactiveerd.

103	Verplichte parameter ontbreekt

104	Ongeldig Verzoek. Geen GET, POST en ruwe JSON gegevens gevonden. Als je probeert JSON te versturen, a.u.b. checken of het goed gecodeerd is.

105	Onbekende Functie

106	Geen Toestemming

107	Generieke API Fout

108	Ongeldige verzoek structuur

109	Te klein tegoed

Hebben we iets vergeten? Heb je vragen? Heb je een tip voor ons of zullen we hier iets toevoegen? Indien ja, laat ons weten!

		Deutsch

		English

		Español

		Français

		Polski

		Português

		Руccкий

		繁体中文

Application Programming Interface (SMS API)

Hulp nodig?

SMS API versturen

Functie: sendSms

POST/GET Voorbeeld

JSON Voorbeeld

Verplichte Parameters

Optionele Parameters

Voorbeeld van een gelukte respons

Gelukte Respons Gegevens

Functie Specifieke API Fouten

Inkomende SMS API

Callback: pushIncomingSms

Callback Voorbeeld

Callback Gegevens

Functie: getIncomingSms

POST/GET Voorbeeld

JSON Voorbeeld

Verplichte Parameters

Optionele Parameters

Voorbeeld van een gelukte respons

Gelukte Respons Gegevens

Functie Specifieke API Fouten

Saldo Lookup API

Functie: getBalance

POST/GET Voorbeeld

JSON Voorbeeld

Voorbeeld van een gelukte respons

Gelukte Respons Gegevens

Afleveringsrapport API

Functie: getDeliveryReport

POST/GET Voorbeeld

JSON Voorbeeld

Verplichte Parameters

Optionele Parameters

Voorbeeld van een gelukte respons: groupkey=false (Default)

Gelukte Respons Gegevens: groupkey=false (Default)

Voorbeeld van een gelukte respons: groupkey=true

Voorbeeld van een gelukte respons: groupkey=true&mailingdetails=true

Functie Specifieke API Fouten

Functie: getRecentReports

POST/GET Voorbeeld

JSON Voorbeeld

Verplichte Parameters

Voorbeeld van een gelukte respons

Gelukte Respons Gegevens

Functie Specifieke API Fouten

Callback: pushDeliveryReport

Callback Voorbeeld

Callback Gegevens

Status Referentie

Mailinglijst API

Functie: sendMailing

POST/GET Voorbeeld

JSON Voorbeeld

Verplichte Parameters

Optionele Parameters

Voorbeeld van een gelukte respons

Gelukte Respons Gegevens

Functie Specifieke API Fouten

Functie: addSubscriber

POST/GET Voorbeeld

JSON Voorbeeld

Verplichte Parameters

Optionele Parameters

Voorbeeld van een gelukte respons

Gelukte Respons Gegevens

Functie Specifieke API Fouten

Functie: updateSubscriber

Functie: deleteSubscriber

POST/GET Voorbeeld

JSON Voorbeeld

Verplichte Parameters

Voorbeeld van een gelukte respons

Gelukte Respons Gegevens

Functie Specifieke API Fouten

Utils API

Functie: doHlrLookup

JSON Voorbeeld

Verplichte Parameters