Français

Application Programming Interface (SMS API)

Veuillez vérifier le Comment Faire avant d'aller plus loin. Merci !

Envoyer un SMS API

Fonction: sendSms

Envoie GSM et Unicode messages textes SMS. Concatène les long messages automatiquement jusqu'à cinq (765 caractères).
Renvoie un objet JSON confirmant la requête (ou statuant une erreur).

Exemple de POST/GET

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

Exemple de JSON

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

Paramètres obligatoires

Paramètre Description Type
number Le numéro de mobile est en format international. Par exemple : 49123456789 ou +49123456789 ou 0049123456789 string
message Corps du message. My-Cool-SMS détecte automatiquement l'input d'encodage et délivre le message de manière appropriée comme GSM ou Unicode.
Vous pouvez utiliser le paramètre optionnel d'Unicode pour choisir un encodage particulier. Si Unicode est réglé sur vrai le SMS sera envoyé comme Unicode et le paramètre de message doit être fourni en notation Unicode UCS2. Si Unicode est réglé sur faux le SMS sera envoyéen GSM et le paramètre de message devra contenir seulement des caractères de l'alphabet GSM7.
Les long messages sont automatiquement concaténés. Le maximum est de 765 caractères pour GSM ou de 335 pour Unicode.
Veuillez noter que vous devez toujours utiliser le paramètre Unicode en envoyant des requêtes GET.
string
A stuce: Découvrez-en plus sur GSM, Unicode and UCS2.

Paramètres optionnels

Paramètre Description Type
unicode Permet d'utiliser l'encodage Unicode ou GSM sur le message. S'il est réglé sur vrai, le paramètre de message doit être soumis à la notation UCS2. S'il est réglé sur faux, le paramètre de message doit contenir uniquement de caractères de l'alpahabet GSM7.
S'il n'est pas réglé sur NULL, My-Cool-SMS détectera automatiquement l'input d'encodage.
boolean
senderid Numéro de mobile en format international, par exemple : +44123456789 ou identifiant émetteur alphanumérique jusqu'à 11 caractères, par exemple : Entreprise string
scheduletime Envoie le message a un moment spécifique. Utiliser le format ATOM et la zone de temps, i.e. : "2011-04-17T17:59:36.67+08" ou "2011-04-17 17:59:36-02" timestamp with timezone
callbackurl URL fonction de rappel pour recevoir des mises à jour de statut et des rapports d'envoi pour ce message. Par exemple : http://www.myserver.com/callback.php string
A stuce: Découvrez-en plus sur fonction de rappel de rapport d'envoi.

Exemple de réponses de réussite

{
    "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"
}

Valeurs des réponses de réussite

Clé Description Type
success Indique si la requête à été menée à bien ou non boolean
smsid Identifiant unique pour ce SMS. Doit être conservée par le poste client et utilisé comme référence pour les rapports d'envoi string(32)
body Le corps du message en Unicode string
bodyucs2 Le corps du message en UCS2 notation bytecode string
bodygsm7 Le corps du message en GSM7 notation bytecode (ou NULL si le message a été envoyé en Unicode) string || NULL
senderid Indicates the sender id used for the sent message. string
senderidenabled Indique si le numéro de destination accepte l'identifiant émetteur dynamique. boolean
unicode Indique si le message a été envoyé en Unicode ou en GSM boolean
numchars Indique combien de caractères le message contient integer
escapenumchars Indique combien de caractères doivent être échappés (et comptés comme deux caractères GSM) integer
smscount Indique si le message a été concaténé en long SMS et fournit le numéro du SMS utilisé integer
charge Indique de combien votre compte a été facturé pour ce message float
balance Solde restant sur votre compte 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 L'URL de fonction de rappel à laquelle les mises à jour de statut et les rapports d'envoi pour ce message seront envoyés. string || NULL

Erreur de fonction de l'API spécifique

Erreur de code Erreur de description
210 Le numéro semble invalide
211 Le paramètre de message est vide
212 Le paramètre de message est trop long
213 Le paramètre Unicode est réglé pour faire accepter Unicode mais le paramètre de message n'a pas été délivré en notation USC2.
214 Le paramètre Unicode est réglé pour faire accepter GSM mais le paramètre de message a été délivré en notation USC2.
215 Le paramètre Unicode est réglé pour faire accepter GSM mais le paramètre de message contient des caractères étrangers à l'alphabet GSM7
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 Les identifiants émetteurs en Shortcode ne sont pas autorisés
218 Le paramètre de fonctions de rappel URL semble invalide
219 L'horaire programmé semble invalide. Utiliser le format ATOM et la zone de temps. "2011-04-17T17:59:36.67+08" ou "2011-04-17 17:59:36-02"
A stuce: Voyez aussi la section sur les erreurs génériques

SMS API entrant

Fonction de réponse: pushIncomingSms

My-Cool-SMS pousse automatiquement les données SMS vers votre serveur si une URL de fonction de rappel pour votre numéro est définie dans vos paramètres de boîte de réception. Vous pouvez éditer votre URL de fonction de rappel dans vos paramètres de boîte de réception dans l'interface web My-Cool-SMS.

Exemple de fonction de rappel

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"
}
A stuce: Regardez here pour plus d'information sur comment gérer les fonctions de rappel JSON.

Valeurs de fonction de rappel

Clé Description Type
from L'identifiant émetteur avec laquelle ce message a été envoyé. Cela peut être un numéro au format international ou un identifiant émetteur au format alphanumérique. string
fromcountrycode Contient le code ISO à deux caractères de l'émetteur si le paramètre de est un numéro. Contient NULL si le paramètre de est alphanumérique. string(2) || NULL
to Le numéro du message a été envoyé vers (votre numéro de téléphone virtuel). string
unicode Indique si le message a été envoyé en Unicode ou en GSM. boolean
smscount Indique si le message a été concaténé en long SMS et fournit le numéro du SMS utilisé integer
body Le corps du message en Unicode string
bodyucs2 Le corps du message en UCS2 notation bytecode string
bodygsm7 Le corps du message en GSM7 notation bytecode (ou NULL si le message a été envoyé en Unicode) string
numchars Indique combien de caractères le message contient integer
escapenumchars Indique combien de caractères doivent être échappés (et comptés comme deux caractères GSM) integer
cost Indique de combien votre compte a été facturé pour ce message float

Fonction: 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.

Exemple de POST/GET

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

Exemple de JSON

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

Paramètres obligatoires

Paramètre Description Type

Paramètres optionnels

Paramètre Description 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]

Exemple de réponses de réussite

{
   "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"
      }
   ]
}

Valeurs des réponses de réussite

Clé Description Type
success Indique si la requête à été menée à bien ou non 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

Erreur de fonction de l'API spécifique

Erreur de code Erreur de description
232 Le numéro semble invalide
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 Invalid limit parameter
236 Invalid order parameter
242 No virtual numbers found.
A stuce: Voyez aussi la section sur les erreurs génériques

Vérifier le solde API

Fonction: getBalance

Renvoie un objet JSON contenant le solde restant sur votre compte (ou déclarant une erreur)

Exemple de POST/GET

username=xxx&password=yyyy&function=getBalance

Exemple de JSON

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

Exemple de réponses de réussite

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

Valeurs des réponses de réussite

Clé Description Type
success Indique si la requête à été menée à bien ou non boolean
balance Solde restant en Euros float

Rapport d'envoi API

Il y a deux manières de recevoir des raport d'envoi de My-Cool-SMS. Vous pouvez poller le serveur de rom My-Cool-SMS via obtenir un rapport d'envoi ou recevoir des fonctions de rappel HTTP sur une URL de votre serveur avec pousser un rapport d'envoi. Veuillez noter que les rapports d'envoi pour les mails sont seulement disponibles via obtenir un rapport d'envoi.

Fonction: getDeliveryReport

Renvoie un rapport d'envoi pour chaque SMS (renvoyé via envoi de SMS) ou message de groupe (renvoyé via envoi de message). Si un rapport d'envoi pour message de groupe est requis (en réglant le paramètre de clé de groupe optionnel sur vrai), l'objet de retour doit contenir un résumé (par défaut) ou des rapports d'envoi individuels pour chaque destinataire unique (en réglant le paramètre optionnel de détails message sur vrai)

Exemple de POST/GET

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

Exemple de JSON

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

Paramètres obligatoires

Paramètre Description Type
id Identifiant de référence. Soit un identifiant SMS (renvoyé via envoi de SMS) ou une clé d'envoi groupé (renvoyé via envoi de message)
Si une clé de groupe est utilisée, la clé de groupe de paramètre optionnel doit être réglée sur vrai.
string

Paramètres optionnels

Paramètre Description Type
groupkey Régler sur vrai si une clé de groupe a été fournie dans le paramètre identifiant et si vous voulez qu'un rapport d'envoi pour le message (à la place d'un simple SMS) soit renvoyé. Par défaut c'est réglé sur faux. string
mailingdetails Régler sur vrai si vous voulez un rapport d'envoi séparé pour chaque récepteur de message en plus du résumé. Par défaut c'est sur faux. string

Exemple de réponses de réussite: groupkey=false (Par défaut)

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

Valeurs des réponses de réussite: groupkey=false (Par défaut)

Clé Description Type
success Indique si la requête à été menée à bien ou non boolean
smsid L"identifiant SMS dans le rapport d'envoi est associé avec string
status Indique le statut de ce SMS string
A stuce: Have a look here for more information on status codes.

Exemple de réponses de réussite: 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
}
A stuce: Have a look here for more information on status codes.

Exemple de réponses de réussite: 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"
        }, 
        (...)
    ]
}
A stuce: Have a look here for more information on status codes.

Erreur de fonction de l'API spécifique

Erreur de code Erreur de description
223 Unknown SMS ID
224 Unknown Group Key
A stuce: Voyez aussi la section sur les erreurs génériques

Fonction: getDeliveryReports

Returns delivery reports for a list of messages.

Exemple de JSON

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

Paramètres obligatoires

Paramètre Description Type
ids An array of sms ids to perform the delivery status lookup for. array[]

Exemple de réponses de réussite:

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

Valeurs des réponses de réussite:

Clé Description Type
success Indique si la requête à été menée à bien ou non 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
A stuce: Have a look here for more information on status codes.

Erreur de fonction de l'API spécifique

Erreur de code Erreur de description
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.
A stuce: Voyez aussi la section sur les erreurs génériques

Fonction: getRecentReports

Returns a JSON object with delivery reports for the most recently sent messages.

Exemple de POST/GET

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

Exemple de JSON

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

Paramètres obligatoires

Paramètre Description Type
limit Indicates how many reports should be returned integer

Exemple de réponses de réussite

{
   "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"
      },
      (...)
   ]
}

Valeurs des réponses de réussite

Clé Description Type
success Indique si la requête à été menée à bien ou non boolean
number The destination number string
senderid The sender id the message was sent with string
body Le corps du message en Unicode string
bodyucs2 Le corps du message en UCS2 notation bytecode string
bodygsm7 Le corps du message en GSM7 notation bytecode (ou NULL si le message a été envoyé en Unicode) string
unicode Indique si le message a été envoyé en Unicode ou en GSM boolean
timesent Time at which the message was sent timestamp with time zone
status Indique le statut de ce SMS string
A stuce: Have a look here for more information on status codes.

Erreur de fonction de l'API spécifique

Erreur de code Erreur de description
225 Invalid limit parameter
A stuce: Voyez aussi la section sur les erreurs génériques

Fonction de réponse: pushDeliveryReport

My-Cool-SMS pousse automatiquement un rapport d'envoi vers votre serveur si le paramètre fonction de rappel de l'URL est réglé lors de l'envoi via la fonction envoi de SMS. La fonction de rappel est réglée comme requête JSON de données brutes.

Exemple de fonction de rappel

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"
}
A stuce: Regardez here pour plus d'information sur comment gérer les fonctions de rappel JSON.

Valeurs de fonction de rappel

Clé Description Type
smsid identifiant unique et référence pour le SMS. L'identifiant de SMS a été retourné dans la réponse de succès sur la fonction envoyer SMS. string(32)
status Indique le statut de ce SMS string

Référence de statut

Status Description
SMS_STATUS_QUEUED Mis à la suite - Le message est actuellement placé à la suite et n'a pas encore été envoyé.
SMS_STATUS_AT_CARRIER Vers opérateur - Le message a été envoyé au fournisseur d'accès et devrait apparaître comme 'envoyé' dès qu'il arrivera au destinataire.
Veuillez noter que parfois les opérateurs ne fournissent pas de rapport d'envoi. Le message restera affiché en tant que "vers opérateur" même s'il a été envoyé avec succès.
SMS_STATUS_DELIVERY_DELAYED Envoi retardé - The message delivery was delayed
SMS_STATUS_DELIVERED Envoyé - The message was succesfully delivered to the target number
SMS_STATUS_BOUNCED Renvoyé - Le message a été renvoyé par le réseau destinataire. Les raisons possibles sont l'invalidité du numéro de portable ou de l'identité de l'émetteur, le téléphone destinataire étant hors de portée de réseau depuis trop longtemps ou une congestion réseau au niveau de l'opérateur.
SMS_STATUS_EXPIRED Expiration - Le message a expiré et n'a pas pu être envoyé.
Ce problème apparaît habituellement lorsque le téléphone destinataire est désactivé ou hors de portée de réseau depuis trop longtemps.
SMS_STATUS_ERROR Echec - L'envoi a échoué (ce message n'a pas été facturé).
Les raisons possibles pour l'échec de l'envoi sont que My-Cool-SMS ne sait pas à quel réseau le numéro de téléphone appartient (veuillez contacter l'assistance si vous êtes certain que le numéro de téléphone est correct) ou une erreur de réseau temporaire.

Fonction: 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.

Exemple de POST/GET

username=xxx&password=yyy&function=getOutboundSms

Exemple de JSON

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

Paramètres obligatoires

Paramètre Description Type

Paramètres optionnels

Paramètre Description 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

Exemple de réponses de réussite

{
   "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"
      }
   ]
}

Valeurs des réponses de réussite

Clé Description Type
success Indique si la requête à été menée à bien ou non 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

Erreur de fonction de l'API spécifique

Erreur de code Erreur de description
234 The provided thresholdid is invalid
235 Invalid limit parameter
236 Invalid order parameter
A stuce: Voyez aussi la section sur les erreurs génériques

Liste de diffusion API

Fonction: sendMailing

Envoie un SMS vers votre liste de diffusion complète. Vuus pouvez créer et gérer les listes de diffusion sur l'interface web de My-Cool-SMS.
Retourne un objet JSON confirmant la requête (ou déclarant une erreur)

Exemple de POST/GET

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

Exemple de JSON

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

Paramètres obligatoires

Paramètre Description Type
uniqueid L'identifiant unique de la liste de diffusion. Vous pouvez trouver votre identifiant unique dans l'interface gestion de votre liste de diffusion sur le site internet. string
message Corps du message. My-Cool-SMS détecte automatiquement l'input d'encodage et délivre le message de manière appropriée comme GSM ou Unicode.
Vous pouvez utiliser le paramètre optionnel d'Unicode pour choisir un encodage particulier. Si Unicode est réglé sur vrai le SMS sera envoyé comme Unicode et le paramètre de message doit être fourni en notation Unicode UCS2. Si Unicode est réglé sur faux le SMS sera envoyéen GSM et le paramètre de message devra contenir seulement des caractères de l'alphabet GSM7.
Les long messages sont automatiquement concaténés. Le maximum est de 765 caractères pour GSM ou de 335 pour Unicode.
Veuillez noter que vous devez toujours utiliser le paramètre Unicode en envoyant des requêtes GET.
string
A stuce: Découvrez-en plus sur GSM, Unicode and UCS2.

Paramètres optionnels

Paramètre Description Type
unicode Permet d'utiliser l'encodage Unicode ou GSM sur le message. S'il est réglé sur vrai, le paramètre de message doit être soumis à la notation UCS2. S'il est réglé sur faux, le paramètre de message doit contenir uniquement de caractères de l'alpahabet GSM7.
S'il n'est pas réglé sur NULL, My-Cool-SMS détectera automatiquement l'input d'encodage.
boolean
senderid Numéro de mobile en format international, par exemple : +44123456789 ou identifiant émetteur alphanumérique jusqu'à 11 caractères, par exemple : Entreprise string
scheduletime Envoie le message a un moment spécifique. Utiliser le format ATOM et la zone de temps, i.e. : "2011-04-17T17:59:36.67+08" ou "2011-04-17 17:59:36-02" timestamp with time zone
A stuce: Découvrez-en plus sur fonction de rappel de rapport d'envoi.

Exemple de réponses de réussite

{
    "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
}

Valeurs des réponses de réussite

Clé Description Type
success Indique si la requête à été menée à bien ou non boolean
groupkey Clé de référence unique pour cet envoi. Doit être conservée par le poste client et utilisée comme référence pour les rapports d'envoi. string(32)
body Le corps du message en Unicode string
bodyucs2 Le corps du message en UCS2 notation bytecode string
bodygsm7 Le corps du message en GSM7 notation bytecode (ou NULL si le message a été envoyé en Unicode) string || NULL
uniqueid string(7)
senderid Indique si le numéro de destination accepte l'identifiant émetteur dynamique. boolean
unicode Indique si le message a été envoyé en Unicode ou en GSM boolean
numchars Indique combien de caractères le message contient integer
escapenumchars Indique combien de caractères doivent être échappés (et comptés comme deux caractères GSM) integer
smscount Indique si le message a été concaténé en long SMS et fournit le numéro du SMS utilisé integer
subscribers Nombre d'inscrits auxquels ce message a été envoyé. integer
charge Indique de combien votre compte a été facturé pour ce message float
balance Solde restant sur votre compte float

Erreur de fonction de l'API spécifique

Erreur de code Erreur de description
220 L'identifiant unique n'est associé avec aucune de vos listes de diffusion
A stuce: Voyez aussi la section sur les erreurs génériques

Fonction: addSubscriber

Insère un nouvel inscrit à la liste de diffusion. Met à jour un inscrit si le nombre soumis existe déjà dans la liste de diffusion récéptrice.
Retourne un objet JSON conformant la requête (ou déclarant une erreur)

Exemple de POST/GET

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

Exemple de JSON

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

Paramètres obligatoires

Paramètre Description Type
number Le numéro de l'inscrit en format international. Par exemple : 49123456789 ou +49123456789 ou 0049123456789 string
uniqueid L'identifiant unique de la liste de diffusion. Vous pouvez trouver votre identifiant unique dans l'interface gestion de votre liste de diffusion sur le site internet. string

Paramètres optionnels

Paramètre Description Type
title Le titre de l'inscrit varchar(16)
firstname Le prénom de l'inscrit varchar(32)
lastname Le nom de l'inscrit varchar(32)
company L'entreprise de l'inscrit varchar(64)

Exemple de réponses de réussite

{
    "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
}

Valeurs des réponses de réussite

Clé Description Type
success Indique si la requête à été menée à bien ou non boolean
number Numéro de téléphone normalisé du nouvel inscrit string
title Titre du nouvel inscrit string
firstname Prénom du nouvel inscrit string
lastname Nom de famille du nouvel inscrit string
company Entreprise du nouvel inscrit string
subscribercost Coût par message pour cet inscrit float
senderidenabled Indique si l'inscrit accepte l'identifiant émetteur boolean
maxcharsgsm Indique combien de caractères l'inscrit accepte pour les messages GSM integer
maxcharsunicode Indique combien de caractères l'inscrit accepte pour les messages Unicode integer
countrycode Le code pays de l'inscrit (deux lettres format standard ISO) string(2)
mailinglistcost Le nouveau coût total pour les envois vers cette liste float
mailinglistsubscribers Le nouveau numéro des inscrits sur cette liste de diffusion integer

Erreur de fonction de l'API spécifique

Erreur de code Erreur de description
221 L'entrée pour {field} est trop longue.
A stuce: Voyez aussi la section sur les erreurs génériques

Fonction: updateSubscriber

Voir Function: addSubscriber

Fonction: deleteSubscriber

Enlève un inscrit de la liste de diffusion (en utilisant le numéro de téléphone comme référence).
Renvoie un objet JSON confirmant la requête (ou déclarant une erreur)

Exemple de POST/GET

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

Exemple de JSON

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

Paramètres obligatoires

Paramètre Description Type
uniqueid L'identifiant unique de la liste de diffusion. Vous pouvez trouver votre identifiant unique dans l'interface gestion de votre liste de diffusion sur le site internet. string
number Le numéro de l'inscrit à supprimer de la liste de diffusion string

Exemple de réponses de réussite

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

Valeurs des réponses de réussite

Clé Description Type
success Indique si la requête à été menée à bien ou non boolean
number Le numéro de téléphone normalisé de l'inscrit enlevé. string
mailinglistcost Le nouveau coût total pour les envois vers cette liste float
mailinglistsubscribers Le nouveau numéro des inscrits sur cette liste de diffusion integer

Erreur de fonction de l'API spécifique

Erreur de code Erreur de description
220 L'identifiant unique n'est associé avec aucune de vos listes de diffusion
222 Il n'a aucun inscrit avec ce numéro de téléphone sur cette liste de diffusion.
A stuce: Voyez aussi la section sur les erreurs génériques

Utilités API

Fonction: doHlrLookup

Réalise une requête Home Location Register (HLR) lookup et renvoie les MSC, MCC, MNC, INSI du numéro aussi bien que toute information sur le nom du réseau, si le numéro est actuellement en itinérance et s'il a été transféré vers un autre réseau.
A stuce: En savoir plus sur HLR, IMSI, MCC, MNC et MSC.

Exemple de JSON

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

Paramètres obligatoires

Paramètre Description Type
number Le numéro pour réaliser la requête HLR lookup pour un format international. PAr exemple : 49123456789 or +49123456789 or 0049123456789 string

Exemple de réponses de réussite

{
    "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
}

Valeurs des réponses de réussite

Clé Description Type
success Indique si la requête à été menée à bien ou non boolean
status Indique le statut de la requête lookup. Veuillez vous référer à la table de référence de statut HLR pour les détails. string
number Le numéro pour lequel la requête HLR lookup a été réalisée. string
imsi International Mobile Subscriber Identity (IMSI). Identification unique associée au numéro récepteur. string
mcc Le Mobile Country Code (MCC) string
mnc Le Mobile Network Code (MNC), qui peut être à deux chiffres (standard Européen) ou à trois chiffres (standard Nord Américain) string
msin Le Mobile Subscription Identification Number (MSIN) dans la base client du réseau. string
servingmsc Le Mobile Switching Center (MSC), responsable du routage du SMS. string
servinghlr Le Home Location Register (HLR) auquel le numéro récepteur est associé. string
originalnetworkname Le réseau de téléphonie mobile auquel ce numéro appartient (ou appartenait si ce numéro à été transféré) string
originalnetworkprefix Le préfixe du réseau de téléphonie mobile auquel ce numéro appartient (ou appartenait si ce numéro à été transféré) string
originalcountryname Le pays auquel ce numéro appartient string
originalcountrycode Le code pays ISO à deux chiffres auquel ce numéro appartient string
originalcountryprefix Le préfixe du pays auquel ce numéro appartient string
roamingcountryname Le pays dans lequel ce numéro est actuellement en itinérance string
roamingcountrycode Le code pays ISO à deux chiffres du pays dans lequel ce numéro est en itinérance string
roamingcountryprefix Le préfixe du pays dans lequel ce numéro est en itinérance string
roamingnetworkname The network the cell phone is currently roaming with string
portednetworkname The network the number has been ported to string
isported Indique s'il s'agit d'un numéro transféré boolean
iscorrect Indique s'il s'agit d'un numéro valide boolean
isroaming Indique si ce numéro est actuellement en itinérance (dans un autre pays) boolean
charge La facturation s'applique pour la requête HLR lookup (0,01 EUR) numeric
A stuce: En savoir plus sur HLR, IMSI, MCC, MNC et MSC.

Erreur de fonction de l'API spécifique

Erreur de code Erreur de description
210 Le numéro semble invalide
226 Echec de la requête HLR lookup. Aucune facturation.
A stuce: Voyez aussi la section sur les erreurs génériques

HLR Référence de statut

Status Description
HLR_STATUS_UNKNOWN_NUMBER Ce numéro n'existe pas ou n'a pu être localisé dans le moindre HLR. Le SMS n'arrivera pas à destination.
HLR_STATUS_OK Le numéro existe et la requête HLR lookup est un succès. Le SMS arrivera à destination.
HLR_STATUS_NOT_OK Le numéro est hors réseau pendant très longtemps ou a été mis hors service par l'opérateur de téléphonie mobile. Le SMS n'arrivera pas à destination.
HLR_STATUS_FAILED La requête HLR lookup a échoué. Aucune facturation réalisée.
HLR_STATUS_AWAITING_RESPONSE Awaiting response from HLR.

Fonction: toUCS2

UCS2 encode un chaîne de caractères Unicode donnée
Important: toUCS2 nécessite une requête JSON.

Exemple de JSON

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

Paramètres obligatoires

Paramètre Description Type
number Le numéro pour réaliser la requête HLR lookup pour un format international. PAr exemple : 49123456789 or +49123456789 or 0049123456789 string

Paramètres optionnels

Paramètre Description Type

Exemple de réponses de réussite

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

Valeurs des réponses de réussite

Clé Description Type
success Indique si la requête à été menée à bien ou non boolean
ucs2 Chaîne de caractères soumise en notation UCS2 string

Erreur de fonction de l'API spécifique

Aucun
A stuce: Voyez aussi la section sur les erreurs génériques

Fonction: fromUCS2

Décode une chaîne de caractères UCS2 spécifique

Exemple de POST/GET

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

Exemple de JSON

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

Paramètres obligatoires

Paramètre Description Type
str Chaîne de caractères UCS2 à décoder string

Exemple de réponses de réussite

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

Valeurs des réponses de réussite

Clé Description Type
success Indique si la requête à été menée à bien ou non boolean
decoded Chaîne de caractères UCS2 décodée en Unicode string

Erreur de fonction de l'API spécifique

Erreur de code Erreur de description
201 Entrée UCS2 invalide
A stuce: Voyez aussi la section sur les erreurs génériques

Fonction: normalizeNumber

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

Exemple de POST/GET

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

Exemple de JSON

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

Paramètres obligatoires

Paramètre Description Type
number The phone number to normalize. Loose format, e.g. 00491787654321, 0049(178)765-4321 etc. string

Exemple de réponses de réussite

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

Valeurs des réponses de réussite

Clé Description Type
success Indique si la requête à été menée à bien ou non boolean
number The normalized number in international MSISDN standard format. string
countrycode The corresponding country code (international two-character ISO format) string(2)

Erreur de fonction de l'API spécifique

Erreur de code Erreur de description
237 The number could not be normalized.

Erreur de réponses

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

Exemple d'erreur de réponse

{
    "success":false,
    "errorcode":103,
    "errordescription":"Paramètre obligatoire manquant: senderid"
}

Valeurs d'erreur de réponse

Clé Description Type
success Indique si la requête à été menée à bien ou non boolean
errorcode Erreur de code à trois chiffres string(3)
errordescription Description de l'erreur string

Erreur de fonction de l'API spécifique

Certaines fonctions ont des codes d'erreur d'API spécifiques, uniques pour cette fonction particulière. Les codes d'erreur sont de format 2xx dans ce cas. Veuillez vous référer à la fonction documentation pour les codes d'erreur individuels.

Erreur générique de l'API

En plus des erreurs spécifiques de fonction, toute requête vers l'API peut aboutir à une erreur générique d'API avec un code erreur format 1xx.

Erreur générique de codes

Erreur de code Erreur de description
101 Echec de connexion. Nom d'utilisateur ou mot de passe erroné.
102 Le compte n'a pas encore été activé.
103 Paramètre obligatoire manquant
104 Requête invalide. Aucun GET, POST, ou donnée brute JSON. Si vous essayez d'envoyer un JSON, veuillez vérifier qu'il est correctement encodé.
105 Fonction inconnue
106 Permission refusée
107 Erreur générique de l'API
108 Invalid request structure
109 Pas assez de crédits
Avons-nous manqué quelque chose ? Avez-vous des questions ? Vous avez des conseils ou quelque chose que vous voulez ajouter ici ? Dans ce cas, faites nous savoir!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Español
Nederlands
Polski
Português
Руccкий
繁体中文