API HSMS - Documentation
Consulter son solde SMS avec HSMS
Vous pouvez consulter le nombre total de SMS disponible au sein de chacune de vos applications en formulant une requête de type POST comme celle-ci :
Method : POST
URL : /api/check-sms
Authorization : "bearer Token ( Disponible au sein de votre Tableau de bord HSMS )"
clientid : Identifiant de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
clientsecret : Mot de passe de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
Formulation de la requête
curl --location --request POST '/api/check-sms' \
-H 'authorization : Bearer TjJ4ZTd4emsyNUZaRW5TMFlnbWxEMTBhOnhwUERza0JJOUdLcGJQamtISnJBTjZRYQ==' \
-H 'content-type : application/form-data' \
-d 'clientid=BOULANGERIE_fbjrgfjbjnjvfvj & clientsecret=bf5b6873bc2e6e020d5bec0ad818ceb4bab605' \
Reponse attendue :
{
"SMS disponibles": 0,
"Application": "JK LIVRAISON"
}
Comment envoyer des SMS avec notre Api en Python ,Php, Java , Javascript ?
Rien de plus simple que l'envoi de sms avec l'APi de HSMS , afin d'y arriver , vous devez formuler une requete de type POST comme celle-ci :
Vous pouvez consulter le nombre total de SMS disponible au sein de chacune de vos applications en formulant une requête de type POST comme celle-ci :
Method : POST
URL : /api/envoi-sms
Authorization : "bearer Token ( Disponible au sein de votre Tableau de bord HSMS )"
clientid : Identifiant de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
clientsecret : Mot de passe de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
telephone : liste des numeros séparés d'une virgule, vous ne devez pas ajouter d'espaces , ni d'autres symboles entre les numéros ( Exemple: 2250789889494, 2250789426868)
message : le message à envoyer au(x) destinataire(s)
NB : Le nombre de message s'incrémente à chaque 160 caractères, par exemple si vous envoyez un message de 161 caractères total, le sytème vous facturera 2 SMS.
Formulation de la requête
curl --location --request POST '/api/envoi-sms/' \
-H 'authorization : Bearer TjJ4ZTd4emsyNUZaRW5TMFlnbWxEMTBhOnhwUERza0JJOUdLcGJQamtISnJBTjZRYQ==' \
-H 'content-type : application/form-data' \
-d 'clientid=BOULANGERIE_fbjrgfjbjnjvfvj & clientsecret=bf5b6873bc2e6e020d5bec0ad818ceb4bab605 & telephone=2250789889555,2250505500220,2250160709894 & message=bonjour ' \
Reponse en cas d'envoi reussi :
{
"success": true,
"message": "Message(s) envoyé(s)",
"resultats": [
{
"destinataire": "2250709797390",
"ticket": "a5555990-08bd-11ef-9401-00000a148c01"
}
]
}
status code = 200
Comment envoyer des SMS Unicode avec notre Api en Python ,Php, Java , Javascript ?
Rien de plus simple que l'envoi de sms avec l'APi de HSMS , afin d'y arriver , vous devez formuler une requete de type POST comme celle-ci :
Vous pouvez consulter le nombre total de SMS disponible au sein de chacune de vos applications en formulant une requête de type POST comme celle-ci :
Method : POST
URL : /api/envoi-sms
Authorization : "bearer Token ( Disponible au sein de votre Tableau de bord HSMS )"
clientid : Identifiant de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
clientsecret : Mot de passe de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
telephone : liste des numeros séparés d'une virgule, vous ne devez pas ajouter d'espaces , ni d'autres symboles entre les numéros ( Exemple: 2250789889494, 2250789426868)
message : le message à envoyer au(x) destinataire(s)
unicode : true.
NB : Le nombre de message s'incrémente à chaque 160 caractères, par exemple si vous envoyez un message de 161 caractères total, le sytème vous facturera 2 SMS.
Formulation de la requête
curl --location --request POST '/api/envoi-sms/' \
-H 'authorization : Bearer TjJ4ZTd4emsyNUZaRW5TMFlnbWxEMTBhOnhwUERza0JJOUdLcGJQamtISnJBTjZRYQ==' \
-H 'content-type : application/form-data' \
-d 'clientid=BOULANGERIE_fbjrgfjbjnjvfvj&clientsecret=bf5b6873bc2e6e020d5bec0ad818ceb4bab605&telephone=2250789889555,2250505500220,2250160709894&message=bonjour&unicode=true' \
Reponse en cas d'envoi reussi :
{
"success": true,
"message": "Message(s) envoyé(s)",
"resultats": [
{
"destinataire": "2250709797390",
"ticket": "a5555990-08bd-11ef-9401-00000a148c01"
}
]
}
status code = 200
Comment envoyer des SMS programmé en avance, expéditeur personnalisé avec notre Api en Python ,Php, Java , Javascript ?
Rien de plus simple que l'envoi de sms avec l'APi de HSMS , afin d'y arriver , vous devez formuler une requete de type POST comme celle-ci :
Vous pouvez consulter le nombre total de SMS disponible au sein de chacune de vos applications en formulant une requête de type POST comme celle-ci :
Method : POST
URL : /api/envoi-sms/sms-programme
Authorization : "bearer Token ( Disponible au sein de votre Tableau de bord HSMS )"
clientid : Identifiant de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
clientsecret : Mot de passe de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
telephone : liste des numeros séparés d'une virgule, vous ne devez pas ajouter d'espaces , ni d'autres symboles entre les numéros ( Exemple: 2250789889494, 2250789426868)
message : le message à envoyer au(x) destinataire(s)
dateenvoi : 2038-01-19 04:14:08
NB : Le nombre de message s'incrémente à chaque 160 caractères, par exemple si vous envoyez un message de 161 caractères total, le sytème vous facturera 2 SMS.
Formulation de la requête
curl --location --request POST '/api/envoi-sms/sms-programme' \
-H 'authorization : Bearer TjJ4ZTd4emsyNUZaRW5TMFlnbWxEMTBhOnhwUERza0JJOUdLcGJQamtISnJBTjZRYQ==' \
-H 'content-type : application/form-data' \
-d 'clientid=BOULANGERIE_fbjrgfjbjnjvfvj&clientsecret=bf5b6873bc2e6e020d5bec0ad818ceb4bab605&telephone=2250789889555,2250505500220,2250160709894&message=bonjour&dateenvoi=2024-05-02 21:55:08' \
Reponse en cas d'envoi reussi :
{
"success": true,
"message": "Message(s) envoyé(s)",
"resultats": [
{
"destinataire": "2250709797390",
"ticket": "a5555990-08bd-11ef-9401-00000a148c01"
}
]
}
status code = 200
Accusés de Réception (DLR)
Les accusés de réception vous offrent la possibilité de suivre l’état de vos messages: envoyés à l'opérateur, reçus sur le téléphone, refusés ou non transmis. Leur transmission sera effectuée à une URL spécifiée sur votre serveur, qui devra être accessible en permanence depuis notre plateforme. Dans le but de garantir la sécurité de cette URL, nous sommes en mesure de vous fournir les adresses IP de nos infrastructures, que vous devrez valider.
Les requêtes envoyées sont encodées en UTF-8. Lorsque vous créez votre application sur HSMS, il est nécessaire de nous indiquer l'adresse de traitement des accusés de réception sur votre serveur ou si vous l'avez déjà crée, comme par exemple: https://www.votredomaine.com/api-sms-reception.
La réception de notre notification doit être confirmée par votre serveur en nous répondant avec un statut 200 - OK. Cependant, dans le cas où vous effectuerez des traitements lents, nous vous prions de nous répondre avant de les effectuer de manière asynchrone, sinon vous pourriez voir une partie des notifications retardées.
Cette URL sera appelée pour chaque accusé de réception de vos messages. Il est possible d'envoyer plusieurs états pour le même message (2 : Envoyé à l'opérateur puis 3 : Délivré).
curl --location --request POST 'https://www.votredomaine.com/api-sms-reception' \
-H 'content-type : application/x-www-form-urlencoded' \
--data MsgId=eda25190-c02d-11e9-89e2-00000a0a6447 \
--data Status=3 \
--data StatusText=delivered \
--data 'DestinationAdress=+2250709797390' \
--data OriginatedAddress=00000 \
--data 'CreateDateTime=2019-02-18 12:54:23' \
--data 'SendDateTime=2019-02-18 12:54:23' \
--data 'DeliveryDateTime=2019-02-18 12:54:25' \
--data Reason=OK \
--data RSN=0 \
--data SmsCount=1 \
--data remoteid=abcdef4567
MsgId: Identifiant unique d'un message, envoyé dans la réponse synchrone sous le nom de ticket
Status: Représente, avec StatusText, l'état du SMS
StatusText: Représente, avec Status, l'état du SMS.
DestinationAdress: Le numéro du destinataire avec indicatif (+225...)
OriginatedAddress: Soit 00000, soit l'émetteur précisé dans sender
CreateDateTime: Heure de création (formaté yyyy-MM-dd HH:mm:ss)
SendDateTime: Heure de l'acquittement opérateur (formaté yyyy-MM-dd HH:mm:ss)
DeliveryDateTime: Heure de réception de l'acquittement mobile (formaté yyyy-MM-dd HH:mm:ss)
Reason: Retour spécifique à l'opérateur
RSN: Code de résultat de l'envoi du message
SmsCount: Nombre de SMS envoyés
remoteid: Champ libre limité à 250 caractères alphanumériques, identifiant métier que vous nous fournissez lors de la soumission d'un SMS et qui est retourné dans les accusés de réception pour un suivi interne au client.
Gestion des réponses (MO)
Si l'opérateur prend en charge les réponses de l'utilisateur final - les "MO" (Mobile Originated) - elles sont enregistrées sur une autre URL qui vous appartient (les recommandations fournies dans la section "Accusés de réception" s'appliquent également à cette URL). Par exemple: https://www.votredomaine.com/api-sms-reception.
Pour la France cette URL sera appelée pour chaque réponse envoyée. Pour le service de réception en Italie, veuillez contacter support@hsms.ci. La plupart du temps, les MO à l'étranger ne sont pas remontés.
curl --location --request POST 'https://www.votredomaine.com/api-sms-reception' \
-H 'content-type : application/x-www-form-urlencoded' \
--data MsgId=c8120070-bff0-11e9-ad94-00000a0a820a \
--data Status=5 \
--data StatusText=SMSMO-received \
--data 'Msisdn=+33612345678' \
--data ShortCode=36180 \
--data 'SendDateTime=2019-02-18 17:31:06' \
--data ServiceId=12345 \
--data SubServiceId=0 \
--data OriginMsgId=eda25190-c02d-11e9-89e2-00000a0a6447 \
--data Content=STOP \
--data Keyword=Stop \
--data RemoteId=abcdef1234
MsgId: Identifiant unique d'un message (identifie le MO)
Status: Status est toujours 5 pour les réponses
StatusText: StatusText est toujours SMSMO-received pour les réponses
Msisdn: Le numéro de l'expéditeur avec indicatif (+225...)
ShortCode: Le numéro court sur lequel nous avons reçu le message
SendDateTime: Heure à laquelle nous avons reçu le message (formaté yyyy-MM-dd HH:mm:ss)
ServiceId: Le ServiceId correspondant à l'échange – par défaut vous n'en aurez qu'un
SubServiceId: Le SubServiceId correspondant, par défaut, ce sera 0
OriginMsgId: Le ticket auquel ce message répond
Content: Le contenu du message reçu
Keyword: Éventuellement un mot clé, sera Default par défaut. Sera Stop si le MO a été identifié de notre côté comme une demande d'opt-out. Attention, la responsabilité de la qualification du MO comme une demande d'opt-out reste du ressort du client. Le champ Keyword est donné à titre purement indicatif.
remoteid: Permet de récupérer la valeur du champ remoteid présent lors de l'envoi du MT. Attention à la casse de ce champ qui est différente entre les deux fonctions.
API Campaign
Celle-ci permet d’envoyer des sms par paquet mais pour que ce système soit efficace, nous vous demandons de n’utiliser l’API campaign que pour des envois de taille suffisante (et notamment de lui préférer impérativement l'API unitaire pour des envois uniques comme cela serait le cas pour des SMS transactionnels).
Demande
Pour utiliser cette API, vous devez faire une demande en vous connectant à votre HSMS.
Intégration de la campagne
Nous vous demandons de limiter dans un premier temps à 50.000 le nombre de messages par lot, de nous consulter avant d'augmenter cette limite et de prendre en compte la valeur de retour en cas d'erreur due à un dépassement de taille pour le lot - cela se manifeste par une erreur HTTP 413 Request Entity Too Large.
Method : POST
URL : "/api/campaign/send-campaign"
Authorization : "bearer Token ( Disponible au sein de votre Tableau de bord HSMS )"
clientid : Identifiant de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
clientsecret : Mot de passe de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
message: exemple: "Ceci est un message de test simple avec un parametre : [param1]",
destinataires: exemple: "destinataires": [ { "msisdn": "+336xxxxxxxxx", "param1": "parametre #1", "remoteid": "remoteid1" }, { "msisdn": "+337yyyyyyyyy", "param1": "parametre #2", "remoteid": "remoteid2" } ]
dateenvoi : Le message est envoyé à l'heure et date (format : yyyy-MM-dd HH:mm:ss, par exemple : 2038-01-19 04:14:08). Il est impossible d'utiliser le timetosend pour un envoi différé de plus de 24 heures à l'avenir, il est nécessaire de gérer des délais plus importants de votre côté. Même s'il est préalablement programmé, il n'est pas envisageable d'annuler un message. Le fuseau horaire est celui de la France.Par défaut, le message sera envoyé immédiatement.
validationrequired: Cette variable mise à true signifie qu’il vous faudra valider la campagne avant son envoi avec un appel à une méthode décrite ci-dessous (dans le cas contraire, la campagne est envoyée dès réception de l’appel). Nous vous conseillons de toujours laisser ce paramètre ; il permettra de valider le nombre de SMS, qui peut différer du nombre de messages en cas de SMS longs. Attention : ceci n'est pas un mécanisme conçu pour différer un envoi. Nous nous réservons le droit de supprimer les campagnes qui resteraient trop longtemps en attente de validation.
lot: Champ optionnel : va de pair avec le champ interval. Cette option permet de lisser les envois de SMS : X SMS toutes les Y secondes (packetsize correspond à x, interval à Y)
interval: Champ optionnel : va de pair avec le champ packetsize. Valeur en secondes.
curl --location --request POST '/api/campaign/send-campaign' \
-H 'authorization : Bearer TjJ4ZTd4emsyNUZaRW5TMFlnbWxEMTBhOnhwUERza0JJOUdLcGJQamtISnJBTjZRYQ==' \
-H 'content-type : application/form-data' \
--data '{"clientid":"clientid","clientsecret":"clientsecret","message":"Ceci est un message de test simple avec un parametre : [param1]","dateenvoi":"2019-01-01 10:15:00","destinataires":[{"msisdn":"+336xxxxxxxxx","param1":"parametre #1","remoteid":"remoteid1"},{"msisdn":"+337yyyyyyyyy","param1":"parametre #2","remoteid":"remoteid2"}],"validationrequired":true,"lot":50,"interval":300}'
Reponse en cas d'envoi reussi :
{
"campaign": {
"campaignid": "2109941",
"campaignstate": "0",
"msgcount": "1",
"smscount": "1",
"result": "success",
"code": "0"
}
}
status code = 200
Validation de la campagne
Si le paramètre validationrequired a été utilisé (et positionné à true), la campagne a été intégrée mais pas lancée. Il faut la lancer en appelant l’URL suivante. Ce processus permet de valider le nombre de SMS qui vont être envoyés.
Attention : ceci n'est pas un mécanisme conçu pour différer un envoi. Nous nous réservons le droit de supprimer les campagnes qui resteraient trop longtemps en attente de validation.
Method : POST
URL : "/api/campaign/campaign-validation"
Authorization : "bearer Token ( Disponible au sein de votre Tableau de bord HSMS )"
clientid : Identifiant de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
clientsecret : Mot de passe de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
campaignid : Identifiant de la campagne obtenu lors de l'intégration du fichier
curl --location --request POST '/api/campaign/campaign-validation' \
-H 'authorization : Bearer TjJ4ZTd4emsyNUZaRW5TMFlnbWxEMTBhOnhwUERza0JJOUdLcGJQamtISnJBTjZRYQ==' \
-H 'content-type : application/form-data' \
-d 'clientid=BOULANGERIE_fbjrgfjbjnjvfvj & clientsecret=bf5b6873bc2e6e020d5bec0ad818ceb4bab605 &campaignid=12345678' \
Reponse en cas d'envoi reussi :
{
"validation": {
"campaignid": "12345678",
"result": "success",
"code": "0"
}
}
status code = 200
Générer un rapport
Après l’envoi de la campagne, il est possible d’obtenir un rapport d’envoi (il est préférable d’attendre quelques heures après le déclenchement de la campagne pour obtenir des résultats significatifs). Le rapport est en principe définitif 3 jours après la fin de la campagne.
Method : POST
URL : "/api/campaign/campaign-report"
Authorization : "bearer Token ( Disponible au sein de votre Tableau de bord HSMS )"
clientid : Identifiant de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
clientsecret : Mot de passe de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
campaignid : Identifiant de la campagne obtenu lors de l'intégration du fichier
curl --location --request POST '/api/campaign/campaign-report' \
-H 'authorization : Bearer TjJ4ZTd4emsyNUZaRW5TMFlnbWxEMTBhOnhwUERza0JJOUdLcGJQamtISnJBTjZRYQ==' \
-H 'content-type : application/form-data' \
-d 'clientid=BOULANGERIE_fbjrgfjbjnjvfvj & clientsecret=bf5b6873bc2e6e020d5bec0ad818ceb4bab605 &campaignid=12345678' \
Reponse en cas d'envoi reussi :
{
"report": {
"campaignid": "12345678",
"messages": [
{
"msisdn": "+33600000000",
"remoteid": "123",
"msgstatut": "3",
"statuttext": "delivered",
"ack": "2018-11-05 13:03:53"
},
{
"msisdn": "+33700000000",
"remoteid": "234",
"msgstatut": "3",
"statuttext": "delivered",
"ack": "2018-11-05 13:03:54"
}
]
}
}
status code = 200
API Pulling DLR MO
L'API Pulling DLR MO est à utiliser si le fonctionnent par défaut pour la récupération des DLR et MO ne s’adapte à votre application. Le mode par défaut est décrit ici. Le mode pulling est activable en option par notre support après une demande sur l'application. Si vous ne pouvez, dans votre architecture, fournir une API ouverte sur l'extérieur, notre API Pulling peut répondre à votre problématique. Ce fonctionnement en pulling vous permet alors de récupérer vos notifications et vos MO stockés sur nos serveurs dans des files d'attente. Vous devez requêter notre API de façon régulière afin de récupérer vos informations et ainsi vider vos files d'attente. Attention vous devez récupérer vos DLR et MO avant 1 mois. Au delà ceux-ci ne seront pas récupérables.
Method : POST
URL : "/api/envoi-sms/notifications-pulling"
Authorization : "bearer Token ( Disponible au sein de votre Tableau de bord HSMS )"
clientid : Identifiant de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
clientsecret : Mot de passe de l'application concernée ( Disponible au sein de votre Tableau de bord HSMS )
max : optionnel : Le nombre d'éléments que vous souhaitez récupérer (par défaut à 50)
curl --location --request POST '/api/envoi-sms/notifications-pulling' \
-H 'authorization : Bearer TjJ4ZTd4emsyNUZaRW5TMFlnbWxEMTBhOnhwUERza0JJOUdLcGJQamtISnJBTjZRYQ==' \
-H 'content-type : application/form-data' \
-d 'clientid=BOULANGERIE_fbjrgfjbjnjvfvj & clientsecret=bf5b6873bc2e6e020d5bec0ad818ceb4bab605 & max=50' \
Reponse en cas d'envoi reussi :
{
"results": [
{
"MsgId": "87270c70-a434-11eb-b321-00000a0a6448",
"Status": "2",
"StatusText": "sent",
"DestinationAdress": "+336xxxxxxxx",
"OriginatedAddress": "00000",
"CreateDateTime": "2021-04-23 15:05:07",
"SendDateTime": "2021-04-23 15:05:08",
"DeliveryDateTime": "",
"Reason": "0033648358662:20210423150507",
"SmsCount": "1",
"Price": "0.0117",
"RSN": "000",
"mccmnc": "20810",
"remoteid": "remoteid1"
}
]
}
status code = 200
Génération de Token
l'API de HSMS vous permet d'envoyer des SMS depuis votre site internet ou votre application mobile, simple et facile à integrer à vos projets.
Pour des raisons de sécurité, chacune de vos requêtes doit être accompagnée d'un Token , il est par defaut disponible sur tous les comptes HSMS , vous pouvez aussi le renouveler :
Method : POST
URL : "/api/token/"
email : Adresse Email de votre compte HSMS
password : Mot de passe de votre compte HSMS
curl --location --request POST '/api/token/' \
-H 'content-type : application/form-data' \
-d 'email=VOTRE_EMAIL_HSMS & password=VOTRE_MOT_DE_PASSE_HSMS' \
Reponse attendue :
{
"success": true,
"message": "OK",
"token": "bf5b6873bc2e6eb90e0d5bec0ad718ceb4bab605"
}
Cas Pratiques avec CURL
curl --location --request POST '/api/envoi-sms/' \
--header 'Authorization: Bearer ef4a6f41ba7a260d5ac68f0wwww91e6a' \
--form 'clientid="BOULANGERIE_dT2ju0y"' \
--form 'clientsecret="BOULANGERIEeerr2022121220927.438324Sgk9YCseKXPL2x2hhu5e"' \
--form 'telephone="2250789923424"' \
--form 'message="hello"'
Foire aux Questions
Si vous avez besoin d'aide pour l'intégration de l'API , cliquez pour ecrire à notre support technique