Nederlands

Application Programming Interface (SMS API)

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,
    "countrycode":"DE",
    "prefix":"+49",
    "timestamp":"2013-04-02T22:27:22-07:00",
    "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 Indicates the sender id used for the sent message. string
senderidenabled 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
countrycode Indicates to which country the SMS was sent to (ISO Code) string
prefix Indicates the prefix of the country to which the SMS was sent to string
timestamp Timestamp of when the SMS was accepted (using the time zone you were on when you logged in to the web portal the last time or UTC if unknown). Given in DATE_ATOM Format (e.g. 2013-04-02T22:27:22-07:00). string
callbackurl Callback URL waar status updates en afleveringsrapporten voor dit bericht naartoe werden verstuurd. string || NULL

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 inbound 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

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)
virtualnumber The virtual number for which sms text messages should be fetched. If no virtual number is provided inbound texts for all virtual numbers will be returned. string
unreadsmstosyncids This parameter is useful if you want to sync the read/unread status of your inbound SMS pipe on several devices. Provide the ids of the messages that are marked as unread on your device to receive a list of ids of messages that have been marked as read on a different device. You can use those ids to update the read/unread status on your device. If no messages were marked as read the list will be empty. array[int]

Voorbeeld van een gelukte respons

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "minid":177,
   "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",
         "unixtimestamp":"1316531343.9",
         "numchars":16,
         "escapechars":0,
         "smscount":1,
         "charge":"0.015",
         "senderidcountrycode":"TW",
         "virtualnumbercountrycode":"HK"
      }
   ]
}

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
minid The lowest sms id found for this user. Can be used for client side reference. 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
242 No virtual numbers found.
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: getDeliveryReports

Returns delivery reports for a list of messages.

JSON Voorbeeld

{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReports",
    "ids":[
        "ce184cc0a6d1714d1ac763f4fe89f521",
        "d1ac763f4fe89f521ce184cc0a6d1714"
    ]
}

Verplichte Parameters

Parameter Beschrijving Type
ids An array of sms ids to perform the delivery status lookup for. array[]

Voorbeeld van een gelukte respons:

{
    "success":true,
    "reports": [
        {
            "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
            "status":"SMS_STATUS_DELIVERED"
        },
        {
            "smsid":"d1ac763f4fe89f521ce184cc0a6d1714",
            "status":"SMS_STATUS_DELIVERED"
        }
    ]
}

Gelukte Respons Gegevens:

Key Beschrijving Type
success Toond aan of het verzoek met succes kon worden verwerkt of niet boolean
reports[] Contains an array with delivery report objects. Each object contains the reference id (smsid) and the corresponding delivery status (status). array
reports[n].smsid Contains the reference sms id for this delivery report string
reports[n].status Contains the delivery status for this SMS. Possible states are: SMS_STATUS_QUEUED, SMS_STATUS_AT_CARRIER, SMS_STATUS_DELIVERY_DELAYED, SMS_STATUS_DELIVERED, SMS_STATUS_BOUNCED, SMS_STATUS_EXPIRED, SMS_STATUS_ERROR or UNKNOWN_ID. string
Tip: Zie hier voor meer informatie over de status codes.

Functie Specifieke API Fouten

Foutcode Fout Beschrijving
240 The input for the "ids" parameter seems invalid. Please make sure to provide an array with valid sms ids.
241 The maximum number of delivery reports per request is 100.
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.

Functie: getOutboundSms

This function is useful if you want to sync the outbound SMS streams in your account for different devices. It queries the server for outbound sms data and returns and array delivery statuses and additional information on the messages, such as content and timestamps.

POST/GET Voorbeeld

username=xxx&password=yyy&function=getOutboundSms

JSON Voorbeeld

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

Verplichte Parameters

Parameter Beschrijving Type

Optionele Parameters

Parameter Beschrijving Type
thresholdid Use this parameter to specify the particular message for which you would like to check if messages were sent before or after. Combine with the thresholdoperator parameter to specify if you need messages with lower or greater ids. string(32)
limit The maximum amount of messages to be returned. Defaults to 25. integer
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
order Specifies the order in which the results should be returned. Can be "ASC" or "DESC". Defaults to "DESC" string

Voorbeeld van een gelukte respons

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "minid":177,
   "messages":[
      {
        "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
        "body":"Have a nice day!",
        "bodyucs2":"0048006100760065002000610020006E00690063006500200064",
        "bodygsm7":"486176652061206E6963652064617921",
        "number":"+491234567890"
        "senderid":"+449876543210",
        "senderidenabled":"+449876543210",
        "unicode":false,
        "numchars":321,
        "escapenumchars":0,
        "smscount":3,
        "charge":0.112,
        "countrycode":"DE",
        "prefix":"+49",
        "timestamp":"2013-04-02T22:27:22-07:00",
        "callbackurl":"http://www.my-server.com/callback.php",
        "status":"SMS_STATUS_DELIVERED"
      }
   ]
}

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 SMS sent on this account. integer
fetched The total number of SMS returned by this query. integer
maxid Indicates the newest sms returned by this query. Can be used as new thresholdoperator parameter in a subsequent API call. integer
minid Indicates the oldest sms returned by this query. Can be used as new thresholdoperator parameter in a subsequent API call. integer
messages An array containing objects with the outbound SMS returned by this query. The SMS object attributes correspond to the return values of the sendSms function (please see that section for details). array

Functie Specifieke API Fouten

Foutcode Fout Beschrijving
234 The provided thresholdid is invalid
235 Ongeldige limiet parameter
236 Invalid order parameter
Tip: Zie ook de sectie over generieke fouten

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.
HLR_STATUS_AWAITING_RESPONSE Awaiting response from HLR.

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

Functie: normalizeNumber

Normalizes a cell phone number in loose format into international standard MSISDN format. For example from +1(712)543-2321 into +17125432321

POST/GET Voorbeeld

username=xxx&password=yyyy&function=normalizeNumber&number=001(712)736-3423

JSON Voorbeeld

{
    "username":"xxx",
    "password":"yyy",
    "function":"normalizeNumber",
    "number":"001(712)736-3423"
}

Verplichte Parameters

Parameter Beschrijving Type
number The phone number to normalize. Loose format, e.g. 00491787654321, 0049(178)765-4321 etc. string

Voorbeeld van een gelukte respons

{
    "success":true,
    "number":"+17127363423",
    "countrycode":"US"
}

Gelukte Respons Gegevens

Key Beschrijving Type
success Toond aan of het verzoek met succes kon worden verwerkt of niet boolean
number The normalized number in international MSISDN standard format. string
countrycode The corresponding country code (international two-character ISO format) string(2)

Functie Specifieke API Fouten

Foutcode Fout Beschrijving
237 The number could not be normalized.

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!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Español
Français
Polski
Português
Руccкий
繁体中文