API SMS

Cette documentation vous présente une façon simple et efficace d'envoyer des SMS via nos APIs.

Notre API va vous permettre d'intégrer la fonctionnalité d'envoi de SMS directement depuis vos applications métier. EkoSMS vous propose avec un seul compte d'acheminer vos SMS au Cameroun et à l'international. Il faudra simplement nous préciser les destinations additionnelles souhaitées.

Attention, vous avez l'obligation de prendre en compte la volonté des destinataires de ne plus recevoir de SMS. En fonction des pays de destination (déterminés par le préfixe téléphonique de leur numéro de mobile), différents canaux peuvent leur être proposés pour exercer ce droit (réponse "STOP" sur un Shortcode ou d'un numéro long indiqué dans le message envoyé, utilisation d'un lien vers une page de désabonnement, etc.) et des lois et règlements différents peuvent en encadrer les modalités.

Inscription

Nous vous proposons l’ouverture d’un compte pour tester gratuitement notre service. La création d'un compte est sans engagement. Pour ouvrir un compte envoyez un mail à support@ekotech.cm en précisant :

- Vos coordonnées :

email du compte
nom
prénom
nom de la société
Siret
numéro de téléphone

- Les adresses IP fixes des serveurs depuis lesquelles seront émis les messages si vous désirez un contrôle par IP.

- En retour, nous vous fournissons les identifiants nécessaires à l'utilisation de l'API.

Le compte d'envoi que nous vous ouvrons peut supporter plusieurs offres et tarifs différents en fonction des destinations et des opérateurs, n’hésitez pas à nous préciser les destinations que vous souhaitez tester.

Envoyer des SMS

Authentification

A l'ouverture de votre compte 3 paramètres vous seront transmis :

username : nom d'utilisateur

password : mot de passe utilisateur

serviceid : votre identifiant de routage optionnel (permet d'avoir plusieurs routes d'envoi, une seule vous sera assignée au départ)

Votre username et votre password vous seront nécessaires afin de vous authentifier pour chaque envoi.

Accès au service

L'API est disponible via l'URL https://api-public.ekotech.cm/

Envoyer un sms en quelques minutes

Cet exemple est la manière la plus simple d'envoyer un SMS : l'authentification, le message et le numéro suffisent dans la majorité des cas d'utilisations.

POST https://api-public.ekotech.cm/messages BODY

usernameUSERNAME

Votre username, transmis à l'inscription

passwordPASSWORD

Votre password, transmis à l'inscription

msisdnMSISDN

Numéro du destinataire avec indicatif (+237...) ou au format international (0033...). Vous pouvez ajouter jusqu'à 500 msisdn séparés d'une virgule : +2376xxxx1,+2376xxxx2,+2376xxxx3

msgMessage simple

Contenu du message.

Le contenu du message est limité à 160 caractères pour un SMS standard (qui utilise l'alphabet GSM – attention aux caractères comptant double, comme €). Nous autorisons avec l'option "messages longs" un envoi de 7 SMS de 153 caractères (la concaténation des SMS utilise 7 caractères par message). Si vos besoins impliquent une taille de message supérieure à 5 x 153 caractères, merci de contacter le support pour demander une analyse du besoin et un paramétrage spécifique. Des limitations imposées par l'opérateur peuvent s'imposer.

Request:
curl --request POST \
  --url https://api-public.ekotech.cm/messages \
  --data username=USERNAME \
  --data password=PASSWORD \
  --data msisdn=MSISDN \
  --data 'msg=Message simple'
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-public.ekotech.cm/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20simple",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://api-public.ekotech.cm/messages")
  .body("username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20simple")
  .asString();
var data = "username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20simple";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-public.ekotech.cm/messages");

xhr.send(data);
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api-public.ekotech.cm/messages"

	payload := strings.NewReader("username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20simple")

	req, _ := http.NewRequest("POST", url, payload)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
import http.client

conn = http.client.HTTPSConnection("api-public.ekotech.cm")

payload = "username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20simple"

conn.request("POST", "/messages", payload)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
Response:200 OK
{
  "results": [
    {
      "msisdn": "+237600000000",
      "smscount": "1",
      "code": "0",
      "reason": "ACCEPTED",
      "ticket": "f85050d0-e5e7-11e9-89e2-00000a0a6447"
    }
  ]
}

SMS Unicode

Il est possible d'envoyer des messages en Unicode et donc de ne pas être limité à l'alphabet GSM.

Toutefois, dans ce mode chaque caractère est encodé sur 16 bits, et un message sera limité à 70 caractères (contre 160 habituellement) - avec la possibilité d'envoyer jusqu'à 7 messages longs (de 67 caractères chacun).

POST https://api-public.ekotech.cm/messages BODY

usernameUSERNAME

Votre username, transmis à l'inscription

passwordPASSWORD

Votre password, transmis à l'inscription

msisdnMSISDN

Numéro du destinataire avec indicatif (+237...) ou au format international (0033...). Vous pouvez ajouter jusqu'à 500 msisdn séparés d'une virgule : +2376xxxx1,+2376xxxx2,+2376xxxx3

msgMessage unicode ‼ 🥳📱

Contenu du message.

Le contenu du message est ici limité à 70 caractères - l'encoding utilisé en "messages Unicode" est l'UCS-2. Nous autorisons avec l'option "messages longs" un envoi de 7 SMS de 67 caractères (la concaténation des SMS utilise 3 caractères par message). Si vos besoins impliquent une taille de message supérieure à 5 x 67 caractères, merci de contacter le support pour demander une analyse du besoin et un paramétrage spécifique. Des limitations imposées par l'opérateur peuvent s'imposer.

allowunicodetrue

Permets l'utilisation de l'Unicode.

Si le contenu du SMS l'impose (présence de caractères NON GSM 03.38) alors le SMS est envoyé en unicode.

Sans ce paramètre, votre message sera converti pour être envoyé au format alphabet GSM (GSM 03.38 ) après transformation des caractères dans des équivalents proches.

Request:
curl --request POST \
  --url https://api-public.ekotech.cm/messages \
  --data username=USERNAME \
  --data password=PASSWORD \
  --data msisdn=MSISDN \
  --data 'msg=Message unicode ‼ 🥳📱' \
  --data allowunicode=true
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-public.ekotech.cm/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20unicode%20%E2%80%BC%20%F0%9F%A5%B3%F0%9F%93%B1&allowunicode=true",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://api-public.ekotech.cm/messages")
  .body("username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20unicode%20%E2%80%BC%20%F0%9F%A5%B3%F0%9F%93%B1&allowunicode=true")
  .asString();
var data = "username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20unicode%20%E2%80%BC%20%F0%9F%A5%B3%F0%9F%93%B1&allowunicode=true";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-public.ekotech.cm/messages");

xhr.send(data);
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api-public.ekotech.cm/messages"

	payload := strings.NewReader("username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20unicode%20%E2%80%BC%20%F0%9F%A5%B3%F0%9F%93%B1&allowunicode=true")

	req, _ := http.NewRequest("POST", url, payload)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
import http.client

conn = http.client.HTTPSConnection("api-public.ekotech.cm")

payload = "username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20unicode%20%E2%80%BC%20%F0%9F%A5%B3%F0%9F%93%B1&allowunicode=true"

conn.request("POST", "/messages", payload)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
Response:200 OK
{
  "results": [
    {
      "msisdn": "+237600000000",
      "smscount": "1",
      "code": "0",
      "reason": "ACCEPTED",
      "ticket": "d540de50-e904-11e9-89e2-00000a0a6447"
    }
  ]
}

SMS programmé en avance, expéditeur personnalisé

L'utilisation des envois différés doit concerner des volumes faibles et des utilisations ponctuelles. Il n'est pas recommandé d'utiliser cette fonctionnalité au-delà de quelques centaines de messages à programmer. La priorité est donnée aux envois immédiats et pas aux messages programmés, il est donc fortement déconseillé d'utiliser cette fonction pour programmer des envois massifs (bulk) dans le futur.

Envoi d'un sms programmé pour 04h18 le 19 janvier 2038^[1], avec comme expéditeur "Test01".

POST https://api-public.ekotech.cm/messages BODY

usernameUSERNAME

Votre username, transmis à l'inscription

passwordPASSWORD

Votre password, transmis à l'inscription

msisdnMSISDN

Numéro du destinataire avec indicatif (+237...) ou au format international (0033...). Vous pouvez ajouter jusqu'à 500 msisdn séparés d'une virgule : +2376xxxx1,+2376xxxx2,+2376xxxx3

msgMessage simple

Contenu du message.

timetosend2038-01-19 04:14:08

Date et heure de l'émission du message (format : yyyy-MM-dd HH:mm:ss ex : 2038-01-19 04:14:08). Le timetosend ne peut pas être utilisé pour un envoi différé de plus de 24h dans le futur, des délais plus grands doivent être gérés de votre côté. Même programmé en avance, il n'est pas possible d'annuler un message. Le fuseau horaire est celui de la France (car c'est où nos serveur se trouvent). Si si entre-temps un destinataire fait part de sa volonté de ne plus recevoir de SMS (STOP), vous ne pourrez pas agir sur un envoi préprogrammé.

senderTest01

Personnalisation de l'émetteur : 11 caractères alphanumériques, par exemple "Magasin" (la valeur par défaut diffère selon les pays et opérateurs). Certains opérateurs refuseront la personnalisation de l'émetteur

Request:
curl --request POST \
  --url https://api-public.ekotech.cm/messages \
  --data username=USERNAME \
  --data password=PASSWORD \
  --data msisdn=MSISDN \
  --data 'msg=Message simple' \
  --data 'timetosend=2038-01-19 04:14:08' \
  --data sender=Test01
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-public.ekotech.cm/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20simple&timetosend=2038-01-19%2004%3A14%3A08&sender=Test01",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://api-public.ekotech.cm/messages")
  .body("username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20simple&timetosend=2038-01-19%2004%3A14%3A08&sender=Test01")
  .asString();
var data = "username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20simple&timetosend=2038-01-19%2004%3A14%3A08&sender=Test01";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-public.ekotech.cm/messages");

xhr.send(data);
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api-public.ekotech.cm/messages"

	payload := strings.NewReader("username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20simple&timetosend=2038-01-19%2004%3A14%3A08&sender=Test01")

	req, _ := http.NewRequest("POST", url, payload)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
import http.client

conn = http.client.HTTPSConnection("api-public.ekotech.cm")

payload = "username=USERNAME&password=PASSWORD&msisdn=MSISDN&msg=Message%20simple&timetosend=2038-01-19%2004%3A14%3A08&sender=Test01"

conn.request("POST", "/messages", payload)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
Response:200 OK
{
  "results": [
    {
      "msisdn": "+237600000000",
      "smscount": "1",
      "code": "0",
      "reason": "ACCEPTED",
      "ticket": "1ba127e0-e907-11e9-89e2-00000a0a6447"
    }
  ]
}

Tous les paramètres

Cet exemple regroupe tout les paramètres possibles. Dans la majorité des cas, seuls les 4 premiers seront utiles.

Ils ne sont pas forcément compatibles, merci de lire les précisions pour chaque paramètre.

POST https://api-public.ekotech.cm/messages BODY

usernameUSERNAME

Votre username, transmis à l'inscription

passwordPASSWORD

Votre password, transmis à l'inscription

msisdn+237600000000

Numéro du destinataire avec indicatif (+237...) ou au format international (0033...). Vous pouvez ajouter jusqu'à 500 msisdn séparés d'une virgule : +2376xxxx1,+2376xxxx2,+2376xxxx3

msgMessage 👍

Contenu du message.

Limité à 160 caractères de l'alphabet GSM si les paramètres allowunicode et dcs ne sont pas utilisés. Nous autorisons avec l'option "messages longs" un envoi de 7 SMS de 153 caractères (la concaténation des SMS utilise 7 caractères par message). Si vos besoins impliquent une taille de message supérieure à 5 x 153 caractères, merci de contacter le support pour demander une analyse du besoin et un paramétrage spécifique. Des limitations imposées par l'opérateur peuvent s'imposer.

allowunicodetrue

Permets l'utilisation de l'Unicode.

Sans ce paramètre, votre message sera converti pour être envoyé en utilisant l'alphabet GSM

serviceid12345

Permets de gérer plusieurs offres différentes sur un compte unique (par exemple : une offre pour des messages Alerting et une offre pour des messages Marketing au Cameroun et ailleurs).

senderTest01

timetosend2038-01-19 04:14:08

Date et heure de l'émission du message (format : yyyy-MM-dd HH:mm:ss ex : 2038-01-19 04:14:08). Le timetosend ne peut pas à plus de 24h dans le futur, des délais plus grands doivent être gérés de votre côté. Même programmé en avance, il n'est pas possible d'annuler un message. Le fuseau horaire est celui de la France (lieu des serveurs). Si entre-temps un destinataire fait part de sa volonté de ne plus recevoir de SMS (STOP), vous n'êtes plus en capacité de le gérer sur ces envois préprogrammés.

encodingUTF-32

L'encoding que vous utilisez pour nous envoyer le message (de vos serveurs à nos serveurs). Si ce champ n’est pas renseigné, nous regarderons les headers http, et s’ils ne sont pas renseignés, nous considérerons que le message est encodé en UTF-8.

remoteidabcdef4567

Champ libre limité à 250 caractères alphanumériques, vous permet de nous donner un identifiant métier que nous vous renverrons dans les accusés de réception et réponses. Pour les envois multiples, vous pouvez envoyer soit un remoteid pour tout le push, soit un remoteid par msisdn.

uniqueidghij0123

Avec le msisdn, crée un couple unique qui permettra de garantir que le même message n'est pas envoyé plusieurs fois, même en cas de réitération d'un envoi (par exemple consécutif à une non-réponse). Attention, compte tenu du mécanisme mis en place, un impact négatif sur les performances est possible. Lors de la réception d’un doublon, nous vous renverrons le même ticket correspondant à l’envoi correspondant (et le smscount en réponse sera de 0 étant donné que nous n’enverrons pas de message supplémentaire). Etant donné que l’unicité est garantie par le couple uniqueid-msisdn, vous avez ici aussi le choix pour les envois multiples d’envoyer un seul uniqueid ou un uniqueid par msisdn. Contrairement au remoteid, nous ne vous renverrons pas cet uniqueid lors des notifications. Il est limité à 35 caractères. Nous vérifions l'unicité du code sur le mois courant.

subserviceid67890

Concernant l’implémentation très particulière de ce champ, contactez nous.

dcs240

Data Coding Scheme, permet de changer la classe du message. Cette option est destinée à un usage averti et n'est pas applicable dans tous les contextes. Merci de contacter le support si vous avez besoin de l'utiliser.

pid65

Protocol Identifier, permet entre autre de remplacer des SMS envoyés précédemment. Cette option est destinée à un usage averti et n'est pas applicable dans tous les contextes. Merci de contacter le support si vous avez besoin de l'utiliser.

udh0605040B8423F0

User Data Header, permet de créer, par exemple des SMS enrichis. Vous n’avez pas à le gérer pour les SMS longs. Cette option est destinée à un usage averti et n'est pas applicable dans tous les contextes. Merci de contacter le support si vous avez besoin de l'utiliser.

Request:
curl --request POST \
  --url https://api-public.ekotech.cm/messages \
  --data username=USERNAME \
  --data password=PASSWORD \
  --data 'msisdn=+237600000000' \
  --data 'msg=Message 👍' \
  --data allowunicode=true \
  --data serviceid=12345 \
  --data sender=Test01 \
  --data 'timetosend=2038-01-19 04:14:08' \
  --data encoding=UTF-32 \
  --data remoteid=abcdef4567 \
  --data uniqueid=ghij0123 \
  --data subserviceid=67890 \
  --data dcs=240 \
  --data pid=65 \
  --data udh=0605040B8423F0
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-public.ekotech.cm/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "username=USERNAME&password=PASSWORD&msisdn=%2B33600000000&msg=Message%20%F0%9F%91%8D&allowunicode=true&serviceid=12345&sender=Test01&timetosend=2038-01-19%2004%3A14%3A08&encoding=UTF-32&remoteid=abcdef4567&uniqueid=ghij0123&subserviceid=67890&dcs=240&pid=65&udh=0605040B8423F0",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://api-public.ekotech.cm/messages")
  .body("username=USERNAME&password=PASSWORD&msisdn=%2B33600000000&msg=Message%20%F0%9F%91%8D&allowunicode=true&serviceid=12345&sender=Test01&timetosend=2038-01-19%2004%3A14%3A08&encoding=UTF-32&remoteid=abcdef4567&uniqueid=ghij0123&subserviceid=67890&dcs=240&pid=65&udh=0605040B8423F0")
  .asString();
var data = "username=USERNAME&password=PASSWORD&msisdn=%2B33600000000&msg=Message%20%F0%9F%91%8D&allowunicode=true&serviceid=12345&sender=Test01&timetosend=2038-01-19%2004%3A14%3A08&encoding=UTF-32&remoteid=abcdef4567&uniqueid=ghij0123&subserviceid=67890&dcs=240&pid=65&udh=0605040B8423F0";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-public.ekotech.cm/messages");

xhr.send(data);
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api-public.ekotech.cm/messages"

	payload := strings.NewReader("username=USERNAME&password=PASSWORD&msisdn=%2B33600000000&msg=Message%20%F0%9F%91%8D&allowunicode=true&serviceid=12345&sender=Test01&timetosend=2038-01-19%2004%3A14%3A08&encoding=UTF-32&remoteid=abcdef4567&uniqueid=ghij0123&subserviceid=67890&dcs=240&pid=65&udh=0605040B8423F0")

	req, _ := http.NewRequest("POST", url, payload)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
import http.client

conn = http.client.HTTPSConnection("api-public.ekotech.cm")

payload = "username=USERNAME&password=PASSWORD&msisdn=%2B33600000000&msg=Message%20%F0%9F%91%8D&allowunicode=true&serviceid=12345&sender=Test01&timetosend=2038-01-19%2004%3A14%3A08&encoding=UTF-32&remoteid=abcdef4567&uniqueid=ghij0123&subserviceid=67890&dcs=240&pid=65&udh=0605040B8423F0"

conn.request("POST", "/messages", payload)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
Response:200 OK
{
  "results": [
    {
      "msisdn": "+237600000000",
      "smscount": "1",
      "code": "0",
      "reason": "ACCEPTED",
      "ticket": "3b420ba0-f01e-11e9-90c5-00000a0a6447"
    }
  ]
}

Accusés de réception

Les accusés de réception vous permettent de suivre votre message et d'en connaitre l'état : envoyé à l'opérateur, reçu sur le téléphone, refusé, ou non délivré. Ils seront transmis sur une URL définie sur votre serveur et qui devra être accessible depuis notre plateforme en continu. Si vous souhaitez protéger ces URL, nous pouvons vous transmettre les adresses IP de nos infrastructures, qu'il conviendra d'autoriser sur les vôtres.

Les requêtes envoyées sont encodées en UTF-8.

Vous devez nous fournir l'url de traitement de la réception des accusés sur votre serveur :

Ex : https://www.mondomaine.com/api-sms-receive.php

Votre serveur devra acquitter la réception de notre notification en nous répondant avec un statut 200 - OK. Toutefois, si des traitements lents ont lieu de votre côté, nous vous invitons à nous répondre avant de les effectuer de manière asynchrone, sous peine de voir une partie des notifications retardées.

Cette URL sera appelée pour chaque accusé de réception de vos messages. Ainsi plusieurs états peuvent être envoyés pour le même message (2 : envoyé opérateur puis 3 : délivré mobile). Il est conseillé de sauvegarder le statut le plus élevé car les événements peuvent arriver dans le désordre.

Voici la requête qui sera envoyée à votre serveur :

POST https://your.url.example/dlr HEADERS

Content-Typeapplication/x-www-form-urlencoded

Type MIME utilisé

BODY

MsgIdeda25190-c02d-11e9-89e2-00000a0a6447

Identifiant unique d'un message, envoyé dans la réponse synchrone sous le nom de ticket

Status3

Représente, avec StatusText, l'état du SMS

StatusTextdelivered

Représente, avec Status, l'état du SMS.

Les états possibles sont :

0 – waiting : En attente

1 – in progress : En cours d'envoi

2 – sent : Envoyé à l'opérateur

3 – delivered : Délivré

4 – refused : Refusé par l'opérateur

6 – not delivered : Non délivré

DestinationAddress+237612345678

Le numéro du destinataire avec indicatif (+237...)

OriginatedAddress00000

Soit 00000, soit l'émetteur précisé dans sender

CreateDateTime2019-02-18 12:54:23

Heure de création (formaté yyyy-MM-dd HH:mm:ss)

SendDateTime2019-02-18 12:54:23

Heure de l'acquittement opérateur (formaté yyyy-MM-dd HH:mm:ss)

DeliveryDateTime2019-02-18 12:54:25

Heure de réception de l'acquittement mobile (formaté yyyy-MM-dd HH:mm:ss)

ReasonOK

Retour spécifique à l'opérateur

RSN0

Code de résultat de l'envoi du message

SmsCount1

Nombre de SMS envoyés

remoteidabcdef4567

Request:
curl --request POST \
  --url https://your.url.example/dlr \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data MsgId=eda25190-c02d-11e9-89e2-00000a0a6447 \
  --data Status=3 \
  --data StatusText=delivered \
  --data 'DestinationAddress=+237612345678' \
  --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
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://your.url.example/dlr",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "MsgId=eda25190-c02d-11e9-89e2-00000a0a6447&Status=3&StatusText=delivered&DestinationAddress=%2B33612345678&OriginatedAddress=00000&CreateDateTime=2019-02-18%2012%3A54%3A23&SendDateTime=2019-02-18%2012%3A54%3A23&DeliveryDateTime=2019-02-18%2012%3A54%3A25&Reason=OK&RSN=0&SmsCount=1&remoteid=abcdef4567",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://your.url.example/dlr")
  .header("content-type", "application/x-www-form-urlencoded")
  .body("MsgId=eda25190-c02d-11e9-89e2-00000a0a6447&Status=3&StatusText=delivered&DestinationAddress=%2B33612345678&OriginatedAddress=00000&CreateDateTime=2019-02-18%2012%3A54%3A23&SendDateTime=2019-02-18%2012%3A54%3A23&DeliveryDateTime=2019-02-18%2012%3A54%3A25&Reason=OK&RSN=0&SmsCount=1&remoteid=abcdef4567")
  .asString();
var data = "MsgId=eda25190-c02d-11e9-89e2-00000a0a6447&Status=3&StatusText=delivered&DestinationAddress=%2B33612345678&OriginatedAddress=00000&CreateDateTime=2019-02-18%2012%3A54%3A23&SendDateTime=2019-02-18%2012%3A54%3A23&DeliveryDateTime=2019-02-18%2012%3A54%3A25&Reason=OK&RSN=0&SmsCount=1&remoteid=abcdef4567";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://your.url.example/dlr");
xhr.setRequestHeader("content-type", "application/x-www-form-urlencoded");

xhr.send(data);
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://your.url.example/dlr"

	payload := strings.NewReader("MsgId=eda25190-c02d-11e9-89e2-00000a0a6447&Status=3&StatusText=delivered&DestinationAddress=%2B33612345678&OriginatedAddress=00000&CreateDateTime=2019-02-18%2012%3A54%3A23&SendDateTime=2019-02-18%2012%3A54%3A23&DeliveryDateTime=2019-02-18%2012%3A54%3A25&Reason=OK&RSN=0&SmsCount=1&remoteid=abcdef4567")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("content-type", "application/x-www-form-urlencoded")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
import http.client

conn = http.client.HTTPSConnection("your.url.example")

payload = "MsgId=eda25190-c02d-11e9-89e2-00000a0a6447&Status=3&StatusText=delivered&DestinationAddress=%2B33612345678&OriginatedAddress=00000&CreateDateTime=2019-02-18%2012%3A54%3A23&SendDateTime=2019-02-18%2012%3A54%3A23&DeliveryDateTime=2019-02-18%2012%3A54%3A25&Reason=OK&RSN=0&SmsCount=1&remoteid=abcdef4567"

headers = { 'content-type': "application/x-www-form-urlencoded" }

conn.request("POST", "/dlr", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Consulter le crédit

Cette requête permets de vérifier votre crédit. Il peut y avoir un délai avant l'affichage des opérations sur cette requête. A cause des traitements asynchrones effectués, votre crédit peut être légèrement négatif.

Si votre compte est de type postpaid, les champs amount et currency ne seront pas présents.

GET https://api-public.ekotech.cm/balance?username=USERNAME&password=PASSWORD PATH PARAMETERS

usernameUSERNAME

Votre username, transmis à l'inscription

passwordPASSWORD

Votre password, transmis à l'inscription

Request:
curl --request GET \
  --url 'https://api-public.ekotech.cm/balance?username=USERNAME&password=PASSWORD'
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-public.ekotech.cm/balance?username=USERNAME&password=PASSWORD",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.get("https://api-public.ekotech.cm/balance?username=USERNAME&password=PASSWORD")
  .asString();
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-public.ekotech.cm/balance?username=USERNAME&password=PASSWORD");

xhr.send(data);
package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api-public.ekotech.cm/balance?username=USERNAME&password=PASSWORD"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
import http.client

conn = http.client.HTTPSConnection("api-public.ekotech.cm")

conn.request("GET", "/balance?username=USERNAME&password=PASSWORD")

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
Response:200 OK
{
  "type": "prepaid",
  "amount": 9398.413,
  "currency": "EUR"
}

Codes d'erreur

Vous pouvez retrouvez ci-dessous une liste exhaustive des codes d'erreur de l'API :

-1 : Authentification failed
-2 : Invalid destination address. Champ msisdn mal formaté.
-3 : Invalid operator
-4 : No route defined. Si vous recevez cette erreur, vous essayez probablement d'envoyer dans un pays dont l'offre n'est pas câblée. Si vous souhaitez rajouter cette offre, veuillez contacter support@ekotech.cm.
-5 : No transaction found
-6 : Parameter "method" not found. Check parameters
-7 : Time to send not allowed
-8 : Datacoding scheme invalid
-9 : Serviceid not found
-10 : Message too long
-11 : Not enough credit
-12 : Invalid parameter

Comptage de caractères

Cet outil vous permet de saisir votre message et de connaître combien de SMS seront nécessaires à son envoi. Il vous permet aussi de savoir quels caractères ne peuvent pas être envoyés avec l'alphabet GSM et ainsi de comprendre pourquoi votre message nécessite plus ou moins de SMS.

Message:

Votre message sera envoyé en 1 SMS. (Unicode)

Détails :

Cela corresponds à 0 caractères.

Légende :

A Caractère présent dans l'alphabet GSM, compte pour un caractère.

€ Caractère présent dans l'extension GSM, compte pour deux caractères.

ë Caractère NON présent en GSM, force le message à être envoyé en Unicode. Compte pour un caractère.

🦆 Caractère NON présent en GSM, force le message à être envoyé en Unicode. Compte pour deux caractères.

Attention en Unicode, un message simple est limité à 70 caractères (contre 160 en GSM).

De 1 à 160 caractères = 1 SMS

De 161 à 306 caractères = 2 SMS

De 307 à 459 caractères = 3 SMS

De 460 à 612 caractères = 4 SMS

De 613 à 765 caractères = 5 SMS

De 766 à 918 caractères = 6 SMS

De 919 à 1071 caractères = 7 SMS