Documentation API

Préambule

Cette API est destinée à créer des campagnes automatiquement. L'application de la campagne est à personnaliser sur la plateforme Sinch pour pouvoir être dupliquée par cette API. Les statistiques d'une campagne sont disponibles après la date d'envoi de cette dernière.

Les requêtes API décrites plus bas doivent être faire sur https://api.myelefant.com excepté la connexion utilisateur dont l'URL est https://platform.myelefant.com/api/login.

Le contenu de toutes les réponses HTTP sont au format JSON. Une réponse dont le statut HTTP est 400 indique une erreur d'utilisation de l'API. Une réponse dont le statut HTTP est 401 indique une erreur authentification. En cas d'erreur, l'attribut errors documente les erreurs.

Les chaînes de caractères envoyées vers le service doivent être encodées en UTF-8 sauf indication contraire. De même, les chaînes de caractères que vous recevez sont encodées en UTF-8.

Excepté l'authentification, toutes les requêtes POST acceptent deux types de contenu.

L'en-tête Content-Type: application/x-www-form-urlencoded permet de poster des paramètres « url encodés » qui est le format standard des formulaires web.
L'en-tête Content-Type: application/json permet de poster les paramètes dans un objet JSON. Un encoding différent de l'UTF-8 peut être spécifié dans le paramètre charset de la façon suivante.
```
Content-Type: application/json; charset=utf-16
```

Authentification

Authentification avec clé secrète (recommandée)

Demandez une clé secrète pour utiliser l'API sans le mot de passe du compte. Si nous l'avons générée, elle est disponible sur la page Options de Sinch. Cette clé doit être stockée sur votre serveur de façon sécurisée et ne doit pas être diffusée.

Pour utiliser les autres points d'API, il faut demander un token d'accès avec la clé secrète. Cette demande est décrite ci-dessous et doit être faite de serveur à serveur. Un token d'accès vous sera fourni dans la réponse et servira à vous identifier dans toutes les autres requêtes. Le token d'accès expire au bout de 2h. Il faudra en obtenir un autre après ce délai.

Requête

URL

https://api.myelefant.com/v1/token

Methode

POST

En-têtes

Authorization: Basic <secret key>

Remplacer <secret key> par votre clé secrète.

Exemple

POST /api/token HTTP/1.1
Host: api.myelefant.com
Content-Length: 0
Accept: application/json
Authorization: Basic NWM1MDQyNzAtYzUwYi00MDgxLTk0ZWMtZGFkODQyMWQyOTRmOjc2NWYzMTVlLTIwM2QtNGJjNC05ZmExLTkyNWRkMGJlODUxMQ==
Accept-Encoding: gzip

Exemple cURL

curl 'https://api.myelefant.com/v1/token' -X POST -H 'Authorization: Basic NWM1MDQyNzAtYzUwYi00MDgxLTk0ZWMtZGFkODQyMWQyOTRmOjc2NWYzMTVlLTIwM2QtNGJjNC05ZmExLTkyNWRkMGJlODUxMQ==' -H 'Accept-Encoding: gzip' -H 'Accept: application/json' -H 'Content-Length: 0' --compressed

Exemple Python

import requests
response = requests.post(
    'https://api.myelefant.com/v1/token',
    headers={'Authorization': 'Basic NWM1MDQyNzAtYzUwYi00MDgxLTk0ZWMtZGFkODQyMWQyOTRmOjc2NWYzMTVlLTIwM2QtNGJjNC05ZmExLTkyNWRkMGJlODUxMQ=='}
)

Réponse en cas de succès

La réponse en JSON contient le token d'accès à ajouter dans l'en-tête Authorization des autres requêtes.

Attributs de l'objet JSON

access_token: Token d'accès nécessaire aux autres requêtes.
expires: Date UTC d'expiration du token d'accès au format ISO.

Exemple

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 119

{"access_token": "vNjIyZTAyNWQtYjRkOC00OWNiLThiY2UtZWRhYTJjYTRkMWQ0", "expires": "2016-08-12T10:45:04", "success": true}

Réponse en cas d'erreur

En cas d'erreur le statut HTTP est 401 et la réponse en JSON contient le message d'erreur dans l'attribut errors.

Exemple

HTTP/1.1 401 UNAUTHORIZED
Content-Type: application/json
Content-Length: 50

{"errors": "Invalid secret key", "success": false}

Utilisation du token d'accès

Sauf indication contraire, le token d'accès obtenu doit être ajouté dans l'en-tête Authorization des autres requêtes de la façon suivante.

Authorization: Bearer vNjIyZTAyNWQtYjRkOC00OWNiLThiY2UtZWRhYTJjYTRkMWQ0

Si le token d'accès n'est pas valide ou expiré, le status de la réponse sera 401.

Exemple d'erreur

HTTP/1.1 401 UNAUTHORIZED
Content-Type: application/json
Content-Length: 73
Access-Control-Allow-Origin: *

{"errors": {"Authorization": ["Invalid access token"]}, "success": false}

Authentification avec mot de passe (obsolète)

Pour utiliser l'API, il est nécessaire de s'authentifier avec votre compte Sinch. Un token vous sera fourni dans la réponse et servira à vous identifier dans toutes les autres requêtes. Le token expire au bout de 2h. Il faudra en obtenir un autre après ce délai.

Requête

URL

https://api.myelefant.com/v1/authenticate

Methode

POST

En-têtes

Content-Type: application/x-www-form-urlencoded

Corps

email=user%40example.com&password=mypass

Les paramètres sont au format application/x-www-form-urlencoded.

email: E-mail du compte Sinch
password: Mot de passe du compte Sinch

Exemple

POST /api/authenticate HTTP/1.1
Host: api.myelefant.com
Content-Length: 48
Accept: application/json
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Accept-Encoding: gzip, deflate

email=alice%40exemple.org&password=monMotDePasse

Exemple cURL

curl 'https://api.myelefant.com/v1/authenticate' -H 'Accept-Encoding: gzip' -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' --data 'email=alice%40exemple.org&password=monMotDePasse' --compressed

Exemple Python

import requests
response = requests.post(
    'https://api.myelefant.com/v1/authenticate',
    {'email': 'alice@example.org', 'password': 'monMotDePasse'}
)

Réponse en cas de succès

La réponse en JSON contient le token d'authentification à préciser dans l'en-tête token de toutes les autres requêtes.

Exemple

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 66
Access-Control-Allow-Origin: *

{"token": "9032e61f-2eca-4464-bfad-3cf9f6f9aa54", "success": true}

Réponse en cas d'erreur

En cas d'erreur le statut HTTP est 400 et la réponse en JSON contient le message d'erreur dans l'attribut errors.

Exemple

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
Content-Length: 51
Access-Control-Allow-Origin: *

{"errors": "Authentication fail", "success": false}

Utilisation du token

Le token obtenu doit être ajouté dans l'en-tête token des autres requêtes de la façon suivante.

token: 9032e61f-2eca-4464-bfad-3cf9f6f9aa54

Si le token n'est pas valide ou expiré, le status de la réponse sera 401.

Exemple d'erreur

HTTP/1.1 401 UNAUTHORIZED
Content-Type: application/json
Content-Length: 58
Access-Control-Allow-Origin: *

{"errors": {"token": ["Invalid token"]}, "success": false}

La connexion utilisateur permet de démarrer une session utilisateur sans son mot de passe. Il est nécessaire d'avoir un token d'accès obtenu depuis votre serveur grâce à votre clé secrète. L'utilisateur doit effectuer la requête suivante avec son navigateur. Placez un lien sur votre site par exemple.

Attention, c'est la seule requête qui se fait sur https://platform.myelefant.com.

Requête

URL

https://platform.myelefant.com/api/login

Methode

GET

Voir les options générales de l'app

access_token: Un token d'accès obtenu depuis votre serveur grâce à votre clé secrète.

Exemple

GET /api/login?access_token=ZWU5YjU2NWUtZjM4NS00OWYyLTg5YmMtZjA3Nzg1YWYwMWE2 HTTP/1.1
Host: platform.myelefant.com
User-Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:48.0) Gecko/20100101 Firefox/48.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Referer: http://my.site.com/my-connect-page/
Connection: keep-alive

Exemple HTML avec moteur de template Jinja

<a href="https://platform.myelefant.com/api/login?access_token={{ access_token }}">Connexion</a>

Exemple HTML et Javascript

<a id="connectLink" href="https://platform.myelefant.com/api/login">Connexion</a>
<script>
    // Get access token from your server
    var accessToken = 'ZWU5YjU2NWUtZjM4NS00OWYyLTg5YmMtZjA3Nzg1YWYwMWE2';
    document.getElementById('connectLink').href += '?access_token=' + accessToken;
</script>

Réponse en cas de succès : redirection

La réponse est une redirection 302 vers la page listant les campagnes Sinch du compte.

Exemple

HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 269
Location: https://platform.myelefant.com/campaigns
Set-Cookie: richsms-v2.cookie=0f49d737408384d7559f37d54f2ee6e2b810260f; Expires=Fri, 19-Aug-2016 13:37:38 GMT; Max-Age=86400; Path=/

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>Redirecting...</title>
<h1>Redirecting...</h1>
<p>You should be redirected automatically to target URL: <a href="https://platform.myelefant.com/campaigns">https://platform.myelefant.com/campaigns</a>.  If not click the link.

Réponse en cas d'erreur

En cas d'erreur le statut HTTP est 401 et la réponse en texte contient le message d'erreur.

Exemple

HTTP/1.1 401 UNAUTHORIZED
Content-Type: text/plain; charset=utf-8
Content-Length: 20

Invalid access token

Création d'une campagne

La création d'une campagne se fait par duplication d'une autre existante. Vous pouvez personaliser votre application sur l'interface de Sinch puis programmer de façon automatique l'envoi de campagnes similaires.

Cette requête ne supporte pas la concurrence sur un même compte. Il est recommandé d'effectuer séquentiellement les requêtes créant des campagnes sur un même compte

Requête

URL

https://api.myelefant.com/v1/campaign/create

Methode

POST

En-têtes

Authorization ou token: Token d'authentification (voir Authentification)
Content-Type: application/x-www-form-urlencoded ou application/json (voir Préambule)

Voir les options générales de l'app

logic: Template type choice (only duplicate is available). duplicate sert à la création de campagne.
logic_param: Paramètres de l'application qui dépend du type d'application choisi.
name: Nom de la campagne.
sender: Ce paramètre est disponible pour le canal SMS uniquement. Nom de l'expéditeur du message. Optionnel si logic est de type duplicate et que la campagne copiée a déjà un émetteur correct. Dans ce cas, l'émetteur de la nouvelle campagne sera une copie de l'émetteur de la campagne copiée. (Optionnel)
message: Ce paramètre est disponible pour le canal SMS uniquement. Contenu du message où [[URL]] est remplacé par l'URL de l'application et [[X]] est remplacé par la valeur de la colonne X (A à Z). Optionnel si logic est de type duplicate et que la campagne copiée a déjà un message correct. Dans ce cas, le message de la nouvelle campagne sera une copie du message de la campagne copiée. (Optionnel)
contacts: Base de contacts c'est-à-dire une liste de liste de chaîne de caractères au format JSON, exemple : [["0612345678", "Alice"], ["0612345679", "Bob"]]
send_date: Date d'envoi de la campagne dans le futur (1h dans le passé est accepté), au format yyyy-mm-dd HH:MM
timezone: L'identifiant du fuseau horaire selon le nommage standard (Europe/Paris, UTC), valeur par défaut : Europe/Paris
tag: Chaîne de caractère quelconque. (Optionnel)
external_channel: true pour utiliser le canal externe, sinon ne pas utiliser ce paramètre. Le canal externe est disponible uniquement si l'option a été débloquée sur votre compte. (Optionnel)
field_names: Liste des noms des champs de contact fournis dans le paramètre contacts, par défaut: A, B, C… Les noms doivent contenir seulement des caractères alphanumerics, underscores, tirets ou espaces blancs. Ces noms de champs seront retournés dans la route données d'un contact. (Optionnel)

Soit la requête inclut tous les paramètres, soit elle n'inclut ni sender, ni message.

Exemple de duplication d'une application existante en Python

import requests
import simplejson as json
import datetime
r = requests.post('https://api.myelefant.com/v1/campaign/create', {
    'logic': 'duplicate',
    'logic_param': '0cafc06b-13ba-4e1e-b03c-dd7b9a11b5e7', # UUID de la campagne à dupliquer
    'name': 'Mon app',
    'sender': 'Moi',
    'message': 'Bonjour [[B]] ! Clique ici [[URL]]',
    'contacts': json.dumps([['0612345678', 'Alice'], ['0612345679', 'Bob'], ['0634567812', 'Claire']]),
    'send_date': datetime.datetime.now().strftime('%Y-%m-%d %H:%M'),
}, headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})

La valeur du paramètre logic_param doit être l'identifiant (UUID) d'une de vos campagnes. Cet identifiant est affiché dans la liste de vos campagnes lorsque que vous cliquez sur "Afficher les IDs".

Exemple de duplication d'une application existante au format JSON en Python

import requests
import simplejson as json
import datetime
r = requests.post('https://api.myelefant.com/v1/campaign/create', json.dumps({
    'logic': 'duplicate',
    'logic_param': '0cafc06b-13ba-4e1e-b03c-dd7b9a11b5e7', # UUID de la campagne à dupliquer
    'name': 'Mon app',
    'sender': 'Moi',
    'message': 'Bonjour [[B]] ! Clique ici [[URL]]',
    'contacts': [['0612345678', 'Alice'], ['0612345679', 'Bob'], ['0634567812', 'Claire']],
    'send_date': datetime.datetime.now().strftime('%Y-%m-%d %H:%M'),
}), headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8', 'Content-Type': b'application/json'})

Réponse en cas de succès

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": true,
    "solde": 430,
    "campaign": {
        "uuid": "5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f",
        "url": "https://rsms.co/bTD",
        "contact_count": 2,
        "duplicated_contacts": [],
        "wrong_contacts": [],
        "tag": null
    }
}

solde: Crédits restant après la création de la campagne
uuid: Identifiant de la nouvelle campagne
url: URL de l'application Sinch
contact_count: Nombre de contacts pris en compte
duplicated_contacts: Liste des numéros de téléphone qui étaient présent plusieurs fois dans la requête
wrong_contacts: Liste des numéros de téléphone dont le format n'est pas reconnu
tag: Tag de la campagne

Exemple de réponse en cas d'erreurs dans les paramètres.

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": false,
    "errors": {
        "logic": ["Logic not found. Try with duplicate"],
        "name": ["This field is required."],
        "sender": ["Invalid input."],
        "message": ["This field is required."],
        "send_date": ["Not a valid datetime value"]
    }
}

Chaque paramètre erroné apparaît dans l'objet errors avec une liste de messages d'erreur.

Envoyer des SMS sur une campagne

Ce point d'entrée permet, sur une campagne existante, d'ajouter des contacts et d'envoyer un message à ces contacts.

Cette requête ne supporte pas la concurrence sur une même campagne. Il est recommandé d'effectuer séquentiellement les requêtes utilisant le même paramètre campaign_uuid.

Il est également recommander de regrouper les requetes (dans les limites des paramètres) au lieu de multiplier le nombre de requetes sur une même campagne (par exemple, éviter les requetes avec un seul contact).

Requête

URL

https://api.myelefant.com/v1/campaign/sendsms

Methode

POST

En-têtes

Authorization ou token: Token d'authentification (voir Authentification)
Content-Type: application/x-www-form-urlencoded ou application/json (voir Préambule)

Voir les options générales de l'app

campaign_uuid: UUID de la campagne
contact (déprécié): Un contact c'est-à-dire une liste de chaîne de caractères au format JSON, exemple : ["0612345678", "Alice"]
contacts: Plusieurs contacts c'est-à-dire une liste de chaînes de caractères au format JSON, exemple : [["0612345678", "Alice"], ["0612345679", "Bob"]]. La taille maximale de la liste est de 1000.
external_channel: true pour utiliser le canal externe, sinon ne pas utiliser ce paramètre. Le canal externe est disponible uniquement si l'option a été débloquée sur votre compte. (Optionnel)

Exemple en Python

import requests
import simplejson as json
import datetime
r = requests.post('https://api.myelefant.com/v1/campaign/sendsms', {
    'campaign_uuid': '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f',
    'contacts': json.dumps([["0612345678", "Alice"], ["0612345679", "Bob"]]),
}, headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})

Exemple au format JSON en Python

import requests
import simplejson as json
import datetime
r = requests.post('https://api.myelefant.com/v1/campaign/sendsms', json.dumps({
    'campaign_uuid': '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f',
    'contacts': [["0612345678", "Alice"], ["0612345679", "Bob"]],
}), headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8', 'Content-Type': b'application/json'})

Réponse en cas de succès

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": true,
    "contacts": [
        {
            "msisdn": "33612345678",
            "url": "https://rsms.co/bTD0",
        },
        {
            "msisdn": "33612345679",
            "url": "https://rsms.co/bTD1",
        }
    ]
}

Exemple de réponse en cas d'erreurs dans les paramètres.

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": false,
    "errors": {
        "campaign_uuid": ["Campaign '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f' not found."],
        "contact": ["No JSON object could be decoded."],
    }
}

Chaque paramètre erroné apparaît dans l'objet errors avec une liste de messages d'erreur.

Liste des campagnes

Fournit un résumé de toutes les campagnes envoyées par le compte. Cela permet de connaitre l'identifiant de la campagne, le nom de l'émetteur, le message envoyé, les dates d'envoi, etc.

Requête

URL

https://api.myelefant.com/v1/campaigns

Methode

GET

En-têtes

Authorization ou token: Token d'authentification (voir Authentification)

Voir les options générales de l'app

start: La date d'envoi minimum au format yyyy-mm-dd HH:MM:SS (Optionnel)
stop: La date d'envoi maximum (exclus) au format yyyy-mm-dd HH:MM:SS (Optionnel)
status: Filtre sur le statut, doit être contenu dans la liste: ['draft', 'scheduled', 'sending', 'sent'] (Optionnel)
extended: Affiche plus d'informations sur les campaigns. De nouveaux champs peuvent être ajouté par la suite sans annonce préalable. ['false', 'true'] (Optionnel) default: false

Exemple en Python

import requests
r = requests.get('https://api.myelefant.com/v1/campaigns', headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})

Réponse en cas de succès

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": true,
    "campaigns": [
        {
            "status": "draft",
            "code": "HcE",
            "send_date": null,
            "name": "Modele pour API",
            "message": "Demo [[A]], voir [[URL]]",
            "contact_count": 4,
            "id": "c2d2f656-09f4-4e26-b9f3-92c14e15116d",
            "sender": "DemoEmett",
            "is_test": true,
            "tag": null,
            "connect_tag": null,
            "is_burst": false,
            "conversation": {
                "module": "module_name",
                "data": {}
            }
        },
        {
            "status": "sent",
            "code": "mpD",
            "send_date": "2016-04-06 10:40:00",
            "name": "Campagne promo",
            "message": "Bonjour [[A]], opération déstockage à [[URL]]",
            "contact_count": 3500,
            "id": "e397637a-f9e2-4838-bcd0-2b87eef1311b",
            "sender": "Prom Emett",
            "is_test": false,
            "tag": "mycampaignid",
            "connect_tag": "mybaseid",
            "is_burst": false,
            "conversation": null
        },
        {
            "status": "scheduled",
            "code": "bTD",
            "send_date": "2016-04-12 15:30:00",
            "name": "Mon app",
            "message": "Bonjour [[B]] ! Clique ici [[URL]]",
            "contact_count": 2,
            "id": "a7b28fd-a216-4d31-90b3-0f62c2e4ee7f",
            "sender": "Moi",
            "is_test": false,
            "tag": null,
            "connect_tag": null,
            "is_burst": true,
            "conversation": {
                "module": "module_name",
                "data": {
                    "type": "order",
                    "foo": "bar"
                }
            }
        }
    ],
}

id: Identifiant de la campagne (UUID)
code: Identifiant court sur 3 caractères
name: Nom de la campagne
sender: Nom de l'émetteur
message: Contenu du message
send_date: Date d'envoi UTC de la campagne. La date est au format yyyy-mm-dd HH:MM:SS.
status: État actuel de la campagne. L'état vaut une des valeurs suivantes : draft (brouillon), scheduled (prêt à l'envoi), sending (en cours d'envoi) ou sent (envoyé).
contact_count: Nombre de contacts
is_test: Vrai si la campagne est un test, faux sinon.
tag: Tag de la campagne
connect_tag: Tag de la base venant de Connect.
is_burst: État du mode burst : activé / non activé
conversation: Informations contenues dans le paramétrage du module conversation s'il a été activé : null / Objet
conversation.module: Nom public du module activé
conversation.data: Objet contenant des paramètres entrés dans le module de conversation d'une campagne par l'équipe Sinch
channel: Channel - seulement disponible si extended=true
has_landing_page: A une landing page - seulement disponible si extended=true

Statistiques d'une campagne

Après l'envoi d'une campagne, les statistiques de celle-ci sont disponibles pendant 6 mois. Passé ce délai la liste des contacts sera vide Un résumé global nous informe du nombre de messages envoyés, reçus, stoppés, le nombre de clics général et unique, le nombre de prévisualisations et enfin le nombre de NPAI. Pour chaque contact on a la date d'envoi et de réception du message, le fait qu'il ait répondu STOP, le nombre et les dates de visites, son user agent et le fait que la prévisualisation du lien s'est affichée dans le message.

Requête

URL

https://api.myelefant.com/v1/campaign/stats

Methode

GET

En-têtes

Authorization ou token: Token d'authentification (voir Authentification)

Voir les options générales de l'app

campaign_uuid: UUID de la campagne
start: Index du premier contact à retourner, inclus (pagination, defaut: 0)
stop: Index d'arrêt, exclus (pagination, defaut: nombre de contacts)
columns: Ajoute les colonnes du fichier de contacts à la réponse (Optionnel)
filters: Filtre les champs des contacts de la réponse par nom (Optionnel)

Exemple en Python

import requests
r = requests.get('https://api.myelefant.com/v1/campaign/stats', params={
    'campaign_uuid': '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f'
}, headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})

Réponse en cas de succès

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": true,
    "summary": {
        "sms_submitted": 3,
        "sms_delivered": 2,
        "sms_stopped": 1,
        "clicks": 3,
        "unique_clicks": 2,
        "previews": 1,
        "npai": 1,
        "credits_used": 3,
    },
    "contacts": [
            {
                "msisdn": "33612345678",
                "url": "https://rsms.co/bTD0",
                "message": "Bonjour Alice ! Clique ici https://rsms.co/bTD0",
                "submitted": u"2014-12-16 13:00:00",
                "delivered": u"2014-12-16 13:30:00",
                "stopped": null,
                "visits": 2,
                "datetimes": "2014-12-16 14:00:00,2014-12-16 14:30:00",
                "preview": null,
                "user_agent": "Firefox OS",
                "npai": false,
            },
            {
                "msisdn": "33612345679",
                "url": "https://rsms.co/bTD1",
                "message": "Bonjour Bob ! Clique ici https://rsms.co/bTD1",
                "submitted": "2014-12-16 13:01:00",
                "delivered": "2014-12-16 13:31:00",
                "stopped": true,
                "visits": 1,
                "datetimes": "2014-12-16 15:00:00",
                "preview": true,
                "user_agent": "Android",
                "npai": false,
            },
            {
                "msisdn": "33634567812",
                "url": "https://rsms.co/bTD2",
                "message": "Bonjour Claire ! Clique ici https://rsms.co/bTD2",
                "submitted": "2014-12-16 13:02:00",
                "delivered": null,
                "stopped": null,
                "visits": 0,
                "datetimes": null,
                "preview": null,
                "user_agent": null,
                "npai": true,
            },
        ],
    }
}

Réponse en cas de succès avec le paramètre columns

Paramètres

columns=1&columns=3

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": true,
    "summary": {
        "sms_submitted": 3,
        "sms_delivered": 2,
        "sms_stopped": 1,
        "clicks": 3,
        "unique_clicks": 2,
        "previews": 1,
        "npai": 1,
        "credits_used": 3,
    },
    "contacts": [
            {
                "msisdn": "33612345678",
                "url": "https://rsms.co/bTD0",
                "message": "Bonjour Alice ! Clique ici https://rsms.co/bTD0",
                "submitted": u"2014-12-16 13:00:00",
                "delivered": u"2014-12-16 13:30:00",
                "stopped": null,
                "visits": 2,
                "datetimes": "2014-12-16 14:00:00,2014-12-16 14:30:00",
                "preview": null,
                "user_agent": "Firefox OS",
                "npai": false,
                "columns": ["CLIENT1234", "Alice"]
            },
            {
                "msisdn": "33612345679",
                "url": "https://rsms.co/bTD1",
                "message": "Bonjour Bob ! Clique ici https://rsms.co/bTD1",
                "submitted": "2014-12-16 13:01:00",
                "delivered": "2014-12-16 13:31:00",
                "stopped": true,
                "visits": 1,
                "datetimes": "2014-12-16 15:00:00",
                "preview": true,
                "user_agent": "Android",
                "npai": false,
                "columns": ["CLIENT5678", "Bob"]
            },
            {
                "msisdn": "33634567812",
                "url": "https://rsms.co/bTD2",
                "message": "Bonjour Claire ! Clique ici https://rsms.co/bTD2",
                "submitted": "2014-12-16 13:02:00",
                "delivered": null,
                "stopped": null,
                "visits": 0,
                "datetimes": null,
                "preview": null,
                "user_agent": null,
                "npai": true,
                "columns": ["CLIENT9123", "Mark"]
            },
        ],
    }
}

Réponse en cas de succès avec le paramètre filters

Paramètres

filters=msisdn&filters=message

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": true,
    "summary": {
        "sms_submitted": 3,
        "sms_delivered": 2,
        "sms_stopped": 1,
        "clicks": 3,
        "unique_clicks": 2,
        "previews": 1,
        "npai": 1,
        "credits_used": 3,
    },
    "contacts": [
            {
                "msisdn": "33612345678",
                "message": "Bonjour Alice ! Clique ici https://rsms.co/bTD0"
            },
            {
                "msisdn": "33612345679",
                "message": "Bonjour Bob ! Clique ici https://rsms.co/bTD1"
            },
            {
                "msisdn": "33634567812",
                "message": "Bonjour Claire ! Clique ici https://rsms.co/bTD2"
            },
        ],
    }
}

Toutes les dates de la réponse sont au format yyyy-mm-dd HH:MM:SS.

summary

sms_submitted: Nombre de messages envoyés
sms_delivered: Nombre de messages reçus
sms_stopped: Nombre de stops
clicks: Nombre total de visites
unique_clicks: Nombre total de visites uniques
previews: Nombre total de prévisualisations
napi: Nombre total de NPAI

contacts

msisdn: Numéro de téléphone du contact au format MSISDN
url: URL de l'application du contact
message: Contenu du message
submitted: Date d'envoi du message
delivered: Date de réception du message
stop: Booléen indiquant si le contact a répondu STOP
visits: Nombre de visites sur l'application
datetimes: Liste des dates de visite
preview: Booléen indiquant si la prévisualisation du lien s'est affichée dans le message
user_agent: User agent du navigateur web

Réponse en cas de campagne non trouvée

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": false,
    "errors": {
        "campaign_uuid": "La campagne n'existe pas ou n'est pas associée à ce compte."
    }
}

Obtenir les événements d'une campagne

Ce point d'entrée permet, sur une campagne existante, d'obtenir la liste des événements de la campagne entre deux dates données.

Requête

URL

https://api.myelefant.com/v1/campaign/log

Methode

GET

En-têtes

Authorization ou token: Token d'authentification (voir Authentification)

Voir les options générales de l'app

campaign_uuid: UUID de la campagne
start: La date du premier événement souhaité au format yyyy-mm-dd HH:MM:SS
stop: La date du dernier événement souhaité au format yyyy-mm-dd HH:MM:SS
columns: Ajoute les colonnes du fichier de contacts à la réponse (Optionnel)
types: Optional filter on event type. Par exemple : types=SUBMIT&types=DELIVER. Voir la liste des types. (Optionnel)

Exemple en Python

import requests
r = requests.get('https://api.myelefant.com/v1/campaign/log', params={
    'campaign_uuid': '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f',
    'start': '2015-07-06 17:30:00',
    'stop': '2015-07-06 19:00:00'
}, headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})

Réponse en cas de succès

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": true,
    "log": [
        {
            "datetime" : "2015-07-06 17:30:00",
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "SUBMIT",
            "data": {"datetime" : "2015-07-06 17:29:54", "success": true, "message": "Bonjour Alice ! Clique ici https://rsms.co/bTD0", "nb_parts": 1}
        },
        {
            "datetime" : "2015-07-06 17:30:01",
            "contact": {"push_id": "clientid", "channel": "push"},
            "type": "SUBMIT",
            "data": {"datetime" : "2015-07-06 17:30:00", "success": true, "message": "Bonjour Alice !", "nb_parts": 1}
        },
        {
            "datetime" : "2015-07-06 17:30:02",
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "DELIVER",
            "data": {"datetime" : "2015-07-06 17:30:01", "success": true, "code": "2", "reason": "Delivered", "nb_parts": 1}
        },
        {
            "datetime" : "2015-07-06 17:31:42",
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "RESPONSE",
            "data": {"datetime" : "2015-07-06 17:31:40", "message": "STOP svp", "stop": true}
        },
        {
            "datetime" : "2015-07-06 17:31:00"
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "VISIT",
            "data": {
                "datetime" : "2015-07-06 16:55:22",
                "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 5_0_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Mobile/9A405",
                "device": {"family": "iPhone"},
                "os": {"family": "iOS", "version", "5.0.1"},
                "browser": {"family": "Mobile Safari", "version": "5.0.1"}
            }
        },
        {
            "datetime" : "2015-07-06 17:31:00"
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "OG_PREVIEW",
            "data": {
                "datetime" : "2015-07-06 16:55:22",
                "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 5_0_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Mobile/9A405",
            }
        },
        {
            "datetime": "2015-07-06 17:59:19",
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "TRACKER",
            "data": {
                "datetime": "2015-07-06 17:58:32",
                "name": "button_662a",
                "value": "click"
            }
        },
        {
            "datetime": "2015-07-06 17:35:24",
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "FORM",
            "data": {
                "datetime": "2015-07-06 17:31:28",
                "name": "newsletter_inscriptions",
                "form": {
                    "email": "customer@example.com"
                }
            }
        }
    ]
}

Response on success with the parameter start, stop and columns

Paramètres

start=2015-07-06%2017%3A29%3A40&stop=2015-07-06%2017%3A30%3A20&columns=1&columns=3

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": true,
    "log":[
        {
            "datetime" : "2015-07-06 17:30:00",
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms", "columns": ["CLIENT1234", "Alice"]},
            "type": "SUBMIT",
            "data": {"datetime" : "2015-07-06 17:29:54", "success": true, "message": "Bonjour Alice ! Clique ici https://rsms.co/bTD0", "nb_parts": 1}
        },
    ]
}

Exemple de réponse en cas d'erreurs dans les paramètres

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": false,
    "errors": {
        "campaign_uuid": ["Campaign '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f' not found."],
        "start": ["this field is required"]
        "stop": ["this field is required"]
    }
}

Chaque paramètre erroné apparaît dans l'objet errors avec une liste de messages d'erreur.

Les types d'événements sont les suivants :

SUBMIT: envoi du message
DELIVER: réception du message par le destinataire
RESPONSE: message de réponse envoyé par le destinataire
VISIT: visite sur l'app du destinataire (le destinataire a cliqué sur le lien dans le message)
OG_PREVIEW: prévisualisation de l'app du destinataire (la prévisualisation du lien s'est affichée dans le message)
TRACKER: action enregistrée sur l'app (un clic sur un bouton par exemple)
FORM: donnée envoyée par les contacts dans les formulaires de l'app

Un événement possède toujours ces quatre attributs :

datetime: Date de l'enregistrement de l'événement dans Sinch au format yyyy-mm-dd HH:MM:SS
contact: Objet représentant le destinataire du message. Le msisdn est le numéro de téléphone au format MSISDN. Le code est l'index Sinch du contact. Il est possible d'ajouter l'attribut columns dans la requête avec le paramètre du même nom pour obtenir des données supplémentaires sur les contacts.
type: Type de l'événement. Les valeurs possibles sont citées plus haut.
data: Données de l'événement qui dépend du type.

Description des données de l'événement par type (le contenu du champ data) :

SUBMIT

datetime: Date de l'envoi du message au format yyyy-mm-dd HH:MM:SS
success: true si nous avons réussi à envoyer le message, sinon false
message: Texte du message
nb_parts: Nombre de sous-parties du message; dans le cas d'un sms multiple, le nombre de sms simples envoyés. Peut être absent

DELIVER

datetime: Date de l'envoi du message au format yyyy-mm-dd HH:MM:SS
success: true si le destinataire a reçu le message, sinon false
code: Obsolète, maintenu pour compatibilité
reason: Raison de l'échec, peut être absent
nb_parts: Nombre de sous-parties du message; dans le cas d'un sms multiple, le nombre de sms simples reçus. Peut être absent

RESPONSE

datetime: Date de la réponse au format yyyy-mm-dd HH:MM:SS
message: Texte du message écrit par le destinataire
stop: true si le mot "stop" est dans le message, sinon false

VISIT

datetime: Date de la visite au format yyyy-mm-dd HH:MM:SS
user_agent: User agent du navigateur utilisé par le destinataire
device: Appareil déterminé avec le user agent
os: Système d'exploitation déterminé avec le user agent
browser: Navigateur déterminé avec le user agent

OG_PREVIEW

datetime: Date de la prévisualisation au format yyyy-mm-dd HH:MM:SS
user_agent: User agent du robot de la messagerie utilisée par le destinataire

TRACKER

datetime: Date de la visite au format yyyy-mm-dd HH:MM:SS
name: Nom de l'événement utilisateur dans l'app
value: Valeur de l'événement (null si non utilisé).

FORM

datetime: Date de la création de l'entrée du formulaire au format yyyy-mm-dd HH:MM:SS
name: Nom du formulaire
form: Object contenant les champs d'une entrée du formulaire

Obtenir les données d'un contact

Ce point d'entrée, pour le moment interne seulement, permet d'obtenir un contact d'une campagne. L'identifiant du contact est nécessaire. La réponse contient les noms de champs du contact fournis par la route de création de campagne. Les Connecteurs SFTP peuvent utiliser l'en-tête CSV comme noms de champs. Le contact est disponible pendant 6 mois après l'envoi de la campagne. Passé ce délai le contact ne sera pas trouvé.

Requête

URL

https://api.myelefant.com/v1/campaign/contacts/{contact_id}

Methode

GET

En-têtes

Authorization ou token: Token d'authentification (voir Authentification)

Exemple avec Curl

curl https://api.myelefant.com/v1/campaign/contacts/018d55fe-dd08-4cb4-bece-e4efa5f0be01_0 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Réponse en cas de succès

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": true,
    "fields": [
        {"name": "phone", "value": "33612345678"},
        {"name": "firstname", "value": "Alice"}
    ]
}

Obtenir les contacts d'une campagne

Ce point d'entrée permet, sur une campagne existante, d'obtenir la liste des contacts de la campagne. Les contacts sont disponibles pendant 6 mois après la création de la campagne. Passé ce délai la liste des contacts sera vide.

Requête

URL

https://api.myelefant.com/v1/campaign/contacts

Methode

GET

En-têtes

Authorization ou token: Token d'authentification (voir Authentification)

Voir les options générales de l'app

campaign_uuid: UUID de la campagne

Exemple en Python

import requests
r = requests.get('https://api.myelefant.com/v1/campaign/contacts', {
    'campaign_uuid': '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f',
}, headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})

Réponse en cas de succès

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": true,
    "contacts": [
        ["0612345678", "Alice"],
        ["0612345679", "Bob"],
        ["0634567812", "Claire"]
    ]
}

Exemple de réponse en cas d'erreurs dans les paramètres

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": false,
    "errors": {
        "campaign_uuid": ["Campaign '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f' not found."],
    }
}

Chaque paramètre erroné apparaît dans l'objet errors avec une liste de messages d'erreur.

Infos d'une campagne

Retourne les informations d'une campagne. Cela permet de connaitre l'identifiant de la campagne, le nom de l'émetteur, le message envoyé, les dates d'envoi, etc.

Requête

URL

https://api.myelefant.com/v1/campaigns/{id}

Methode

GET

En-têtes

Authorization ou token: Token d'authentification (voir Authentification)

Exemple en Python

import requests
r = requests.get('https://api.myelefant.com/v1/campaigns/5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f', headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})

Réponse en cas de succès

Statut HTTP

Content-Type

application/json

Contenu

{
    "success": true,
    "campaign":
        {
            "status": "draft",
            "code": "HcE",
            "send_date": null,
            "name": "Modele pour API",
            "message": "Demo [[A]], voir [[URL]]",
            "contact_count": 4,
            "id": "c2d2f656-09f4-4e26-b9f3-92c14e15116d",
            "sender": "DemoEmett",
            "is_test": true,
            "tag": null,
            "connect_tag": null,
            "conversation": {
                "module": "module_name",
                "data": {}
            },
            "format": "rich",
            "validation_errors" : {
                "contacts": [],
                "message": ["Missing sender"],
                "app": ["App is empty"],
                "global": ["Not enough credits"]
            }
        },
}

id: Identifiant de la campagne (UUID)
code: Identifiant court sur 3 caractères
name: Nom de la campagne
sender: Nom de l'émetteur
message: Contenu du message
send_date: Date d'envoi UTC de la campagne. La date est au format yyyy-mm-dd HH:MM:SS.
status: État actuel de la campagne. L'état vaut une des valeurs suivantes : draft (brouillon), scheduled (prêt à l'envoi), sending (en cours d'envoi) ou sent (envoyé).
contact_count: Nombre de contacts
is_test: Vrai si la campagne est un test, faux sinon.
tag: Tag de la campagne
connect_tag: Tag de la base venant de Connect.
conversation: Informations contenues dans le paramétrage du module conversation s'il a été activé : null / Objet
conversation.module: Nom public du module activé
conversation.data: Objet contenant des paramètres entrés dans le module de conversation d'une campagne par l'équipe Sinch
format: Format de la campagne. Peut être simple or rich
validation_errors: Liste des erreurs par page à corriger pour que la campagne soit valide

Limites Connues

Afin de ne pas surcharger l'API, nous recommandons d'effectuer des appels sequentiels sur les différents endpoints et d'éviter les appels en parallèle sur le même compte.

Pour plus d'information, merci de nous contacter: campaign_manager_api@sinch.com

Documentation API

Préambule

Authentification

Authentification avec clé secrète (recommandée)

Authentification avec mot de passe (obsolète)

Connexion utilisateur

Création d'une campagne

Envoyer des SMS sur une campagne

Liste des campagnes

Statistiques d'une campagne

Obtenir les événements d'une campagne

Obtenir les données d'un contact

Obtenir les contacts d'une campagne

Infos d'une campagne

Limites Connues