1. Introduction

Afin de vous faciliter les possibilités d'intégrer la fonctionnalité d'envoi d'SMS directement dans vos applications et sites web, nous avons mis en place une API flexible et robuste à la fois. Pour permettre à un grand nombre de développeurs d'utiliser notre API, elle est déployée entièrement dans une architecture C# .NET 4.5, interagissant parfaitement avec n'importe quel environnement ou langage de programmation (PHP, C#.NET, VB.NET, Java, Windev ...).

Les lignes suivantes vous permettront de commencer par envoyer des SMS depuis votre application en quelques minutes seulement :

  • URL de base (notre serveur) : http://aspsmsapi.com/http/sendsms.aspx
  • Méthode d'envoi : POST (uniquement)
  • Mais avant tout, depuis votre compte, allez dans l'onglet Modifier mon Profil. Sélectionnez YES au niveau de : Activer l’API
  • Si vous souhaitez recevoir les rapports de livraison dans votre application, alors indiquez sous votre profil l'URL de réception automatique des rapports (en commençant par http://) dans le champ URL Report. Notez que les variables du rapport seront envoyées sur cette URL avec la méthode POST (Voir la section 7).
  • Sur la même page quelques lignes plus bas, prenez note de votre apikey (respectez la casse). Validez les modifications et vous êtes prêts pour la suite.

2. Quelques fonctionnalités

  • Envoi de message vers une ou plusieurs destinations (pays) à la fois
  • Personnalisation d'identifiant d'envoi
  • Envoi de message long jusqu'à 612 caractères (4 pages)
  • Envoi immédiat ou programmé
  • Envoi de message classic ou binaire
  • Envoi de message en mode normal ou flash
  • Rapport de livraison en mode PUSH ou PULL

3. Paramètres

PARAMETRES DESCRIPTION PRESENCE
authmode Valeur attendue : http Obligatoire
username Votre nom d'utilisateur (ex. 22898774451) Obligatoire
apikey Il s’agit de votre clé API. Vous trouverez apikey sous votre compte => Profil Obligatoire
msg Contenu du message à envoyer. 612 caractères maximum (url encoded)* Obligatoire
dest Numéro de téléphone mobile du destinataire au format international (ex. 22898663210). Si vous souhaitez envoyer le même message à plusieurs destinataires, il suffit de les aligner en les séparant par une virgule (ex. 22890199533,22898774450,22995668923).
Important : Mettre les numéros avec l'indicatif du pays devant sans le signe + ni 00.
Obligatoire
senderid Identifiant d'envoi. Il peut être alpha numérique (11 caractères max) ou numérique (14 caractères max). Sauf autorisation spéciale, vous devez l'avoir préalablement créé sous votre compte. A défaut, votre username sera utilisé comme identifiant. Obligatoire
customid ID unique vous permettant de tracker le statut de livraison de chaque destinataire dans votre application. Facultatif
bulkid Vous permet de regrouper tous les destinataires d'un même envoi sous une référence Facultatif
date Pour programmer l'envoi d'un message. Elle doit être au format dd-mm-yyyy hh:mm:ss (jour-mois-année heures-minutes-secondes).
Exemple : 21-09-2014 10:30:15. Si vous fournissez une date erronée ou déjà passée, le message ne sera pas programmé, mais envoyé immédiatement.
Facultatif
type Type de message : text (message normal) ou binary (message binaire). Par défaut, le type est : text Facultatif

 

4. Réponse du serveur

Après exécution de votre requête dans les meilleures conditions, le serveur vous retourne une réponse dans une liste :

  • Le statut de la requête Le numéro du destinataire
  • L’identité de l’opérateur (réseau)
  • Le coût du message
  • L’ID unique du message généré par le serveur (servant à vérifier le statut de livraison dans notre système)
  • Le solde de votre compte

Exemple

OK|22890894488|Togo Cell|18,000|22102014225851e9bc0562|4933,000

 

5. En cas d'echec

En cas d'erreur lors de l'envoi, le serveur vous retournera l'une des erreurs suivantes :


MESSAGE DESCRIPTION
ERROR:LOGIN_FAILED Echec de connexion
ERROR:MISSING_USERNAME Votre nom d'utilisateur est introuvable
ERROR:MISSING_APIKEY Vous n'avez pas fourni votre clé API
ERROR:MISSING_CONTENT Contenu non fourni ou incorrect
ERROR:MISSING_RECIPIENT Vous n'avez indiqué aucun destinataire
ERROR:MISSING_AUTH_MODE Vous devez fournir http comme valeur de la variable authmode
ERROR:MISSING_SENDER_ID Vous n'avez indiqué aucun nom d'envoi (senderid)
INVALID_COUNTRY_CODE Indicatif du pays incorrect
INVALID_LENGTH Le numéro du destinataire est incorrect. Trop court
INVALID_NETWORK_CODE Le numéro du destinataire semble n'appartenir a aucun opérateur
ERROR:LOW_BALANCE Le solde de votre compte est trop bas pour envoyer ce message

 

6. Rapport de livraison

Il est intéressant de pouvoir connaître le statut du message envoyé pour faire une mise à jour dans votre base de données. Pour ce faire, vous pouvez utiliser la méthode PUSH ou la méthode PULL.


1. Par la méthode PUSH, vous recevez systématiquement le statut (rapport de livraison) de vos messages sur l'URL préalablement configurée sur votre compte (lire l'introduction plus haut)


2. La méthode PULL vous permet d'exécuter à tout moment une requête HTTP par la méthode GET, pour consulter le statut d'un message (100 rêquetes maximum par heure)


Exemple


A l'URL de demande de statut des messages (PULL), passez les variables suivantes :

PARAMETRES DESCRIPTION PRESENCE
messageid ID unique du message dont vous souhaitez obtenir le statut. Obligatoire
username Nom d'utilisateur de votre compte Obligatoire
apikey Clé API de votre compte Obligatoire

Exemple

 

Si vous avez fourni un lien de réception des statuts de livraison sous votre compte (lire introduction plus haut), alors espérez recevoir par la méthode POST, les variables comme indiquées dnas la section suivante (Codes des statuts de livraison)

7. Codes des status de livraison

Pour chaque requête du statut d'un message, par la méthode PULL ou la méthode PUSH, le serveur vous renvoie une chaine (liste) comportant :


Variables et interprétations

status Statut actuel du message
network Nom de l'opérateur ou du réseau auquel appartient le numéro
cost Coût facturé pour le message
messageid ID unique du message
date Date et heure de livraison

Exemple

SUCCESS|22890894488|Togo Cell|18,000|22102014225851e9bc0562|22/10/2014 16:48:21

Interprétation des codes

OK Message accepté par notre serveur. Tentatives de transmission à l'opérateur
ACCEPTED Message accepté par l'opérateur. Tentatives de livraison en cours.
SUCCESS Message livré avec succès
FAILED Message non livré (échec)
EXPIRED Délai de tentatives de livraion dépassé (échec)
SCHEDULED Message programmé pour livraison ultérieure

 

8. Solde de votre compte

Vous pouvez à tout moment connaître le solde de votre compte en envoyant une requête http par la méthode GET vers l'URL :


Paramètres

VARIABLES DESCRIPTION
username Nom d'utilisateur de votre compte
apikey La clé API de votre compte

Exemple