API pour l'envoi et la réception de SMS
Qu'est-ce que l'API websms ?
L'API vous permet d'envoyer des SMS à partir de votre propre application, en utilisant votre compte websms.lu
Vous pouvez également recevoir des SMS entrants sur l'url de votre choix.
Spécifications techniques
Toutes les requêtes doivent être soumises à l'url de base de l'API.
Les appels doivent être fait en POST en utilisant un encodage UTF-8.
Pour des raisons de sécurité, vous devez utiliser le protocole HTTPS.
Authentification
Tous les appels nécessitent les identifiant et mot de passe de votre compte
| Paramètre | Description |
|---|---|
| username | Obligatoire L'identifiant de votre compte websms |
| password | Obligatoire Le mot de passe de votre compte websms |
Paramètres du SMS
| Paramètre | Description |
|---|---|
| from | Obligatoire L'expéditeur de votre message. Vérifiez les expéditeurs autorisés dans votre compte sur le site |
| to | Obligatoire Le numéro de téléphone du destinataire au format international (par exemple 352661594860) |
| text | Obligatoire Le texte à envoyer dans votre message encodé en UTF-8 et URL encodé. Tous les caractères ne se trouvant pas dans l'alphabet GSM 03.38 7-bit seront supprimés (voir http://unicode.org/Public/MAPPINGS/ETSI/GSM0338.TXT). Par défaut, un SMS a une taille maximale de 160 caractères. Si vous autorisez les envois plus longs dans votre compte, cette limite est de 3200 caractères, et votre message sera envoyé en plusieurs parties. Le téléphone de votre destinataire se chargera de les concaténer. Le cout total de l'envoi sera alors égal au coup de l'envoi des différentes parties. |
| subject | Optionnel Une référence pour l'affichage dans votre compte websms - ne sera pas communiqué au destinataire de votre message |
Exemple
La requête suivante envoie le texte "Déjà Vu" au numéro 352661594860
Réponse
La réponse à votre requête se fait sous forme de message JSON.
| Clé | Valeur |
|---|---|
| statusCode | Le code de retour |
| statusText | La description du code retour |
| smsParts | Le nombre de SMS qui compose votre envoi (1 si votre message fait moins de 160 caractères). uniquement présent si le statusCode vaut 0 |
| messagePrice | Le prix de l'envoi uniquement présent si le statusCode vaut 0 |
| remainingBalance | Le solde restant sur votre compte après l'envoi uniquement présent si le statusCode vaut 0 |
| message_id | L'ID unique du message uniquement présent si le statusCode vaut 0 |
Code retour
| Code | Description | Explication |
|---|---|---|
| 0 | success | Le message a été correctement enregistré pour être envoyé |
| 1 | parameter is missing | Il manque un paramètre obligatoire |
| 2 | incorrect parameter encoding | Le paramètre spécifié n'est pas encodé en UTF-8 |
| 3 | incorrect parameter value | Le paramètre spécifié n'a pas la bonne valeur |
| 4 | incorrect credentials | Votre identifiant et/ou mot de passe sont incorrects |
| 5 | internal error | Erreur interne à la plate-forme lors du traitement de votre message |
| 6 | destination country not allowed | Vous n'avez pas le droit d'envoyer vers ce pays, veuillez nous contacter |
| 7 | account credit exceeded | Vous n'avez pas assez de crédit pour l'envoi, veuillez recharger dans votre compte |
| 8 | message too long (160 max) | Votre message ne doit pas excéder 160 caractères (si vous avez activez le blocage dans votre compte) |
Callback URL
Que vous utilisiez l'API ou l'interface websms.lu vous pouvez fournir dans votre compte une URL de callback qui sera appelée à chaque changement de statut de vos SMS. Les informations sont transmises en POST. Si votre URL n'est pas accessible, la plateforme essaiera plusieurs fois de délivrer le statut.
Dans le cas d'un SMS multiple, vous ne recevez qu'un seul statut 'sent' puis un autre statut final par partie de votre SMS (si tout se passe bien et que vous envoyez un SMS en deux parties, vous recevrez 1 statut 'sent' puis 2 statuts 'received')
| Clé | Valeur |
|---|---|
| message_id | L'ID unique du message sur la plateforme websms.lu |
| status | Le statut du message parmi: - sent : en cours d'envoi au mobile - received : recu par le mobile - error : message non délivré, mobile non joignable, numéro indisponible, roaming trop long, etc ... |
Classe PHP
Cliquez ici pour télécharger la classe PHP
Un exemple d'utilisation de cette classe PHP
<?php
include "api.websms.php";
$sms = new sms("{votre_login}", "{votre_mot_de_passe}");
$sms->send("34542661594860", "websms", "Déjà vu", "Appel API");
echo $sms->displayOverview();
?>
Retour en cas d'erreur
Retour en cas de succès
