Skip to content

Envoyer un message

post
https://api.reach.talkylabs.com/rest/messaging/v1/create

Cette opération permet d'envoyer ou de planifier un message.

Lorsque vous envoyez un nouveau message via l'API, vous devez inclure le paramètre dest qui correspond au numéro de téléphone de destination. Vous devez également inclure le paramètre body qui contient le contenu du message ainsi que le paramètre src qui contient le numéro ou l'identifiant alphanumérique de l'expéditeur.

Pour planifier un message, vous devez également fournir le paramètre suivant :

  • scheduledTime : la date et l'heure à laquelle le sms sera envoyé dans le format ISO-8601.
Warning

La plateforme Reach met en file d'attente les demandes d'envoi de messages et les distribue dès que possible. Vous pouvez envoyer des messages à la plateforme Reach à un rythme rapide, tant que les demandes ne dépassent pas votre limite de concurrence. Lorsque cela se produit, la plateforme Reach commence à répondre avec le code HTTP 429 qui signifie Too Many Requests.

Paramètres

  • deststringrequired

    Le numéro de téléphone en format E.164 récipiendaire du message.

  • srcstringrequired

    Le numéro de téléphone (en format E.164) ou l'identifiant alphanumérique de l'expéditeur à l'origine du message.

  • bodystringrequired

    Le contenu du message à envoyer. Il peut contenir jusqu'à 1 600 caractères GSM-7. Cette limite varie si votre message n'est pas composé uniquement de caractères GSM-7. Plus généralement, le contenu du message ne doit pas dépasser 10 segments.

  • bulkIdentifierstringoptional

    L'identifiant 'bulk' (c-à-d d'envoi de masse) auquel appartient ce message.

  • scheduledTimedate-timeoptional

    Date et heure à laquelle le message sera envoyé. Doit être au format ISO 8601. Un message doit être programmé au moins 15 minutes avant l'heure d'envoi du message et ne peut être programmé plus de 5 jours avant la demande.

  • statusCallbackurloptional

    L'URL à utiliser pour envoyer des mises à jour concernant le statut de votre message. Si elle est fournie, l'API Reach Messaging enverra des requêtes POST à l'URL lors de ces changements de statut de message: queued, failed, sent, canceled, delivered, ou undelivered. L'URL doit contenir un nom d'hôte valide et les underscores ne sont pas autorisés. Voir [details](#envoi- de-mises-à-jour-à-l'url-statuscallback) pour plus d'informations.

  • maxPricenumberoptional

    Le coût total maximum dans la monnaie de l'applet pour que le message soit délivré. Si le coût effectif dépasse maxPrice, le message échouera et un statut failed sera retourné.

  • validityPeriodintegeroptional

    Il représente la durée, en secondes, pendant laquelle le message peut rester dans la file d'attente. Une fois ce délai écoulé, le message échoue et un statut failed est retourné. Une fois qu'un message a été accepté par un opérateur réseau, il n'est pas garanti que le message ne sera pas mis en file d'attente après cette période par l'opérateur réseau. Il est recommandé que cette valeur soit d'au moins 5 secondes. La valeur maximale autorisée est de 14 400, ce qui correspond à 4 heures. La valeur par défaut est 14 400.

Envoi de mises à jour à l'URL statusCallback

L'URL statusCallback est destinée à vous notifier ou à notifier votre application d'une mise à jour concernant le statut d'un message envoyé via la plateforme Reach. Lorsque le statut de votre message change, la plateforme Reach envoie une requête POST à l'URL fournie.

La requête contiendra le nouveau statut de votre message et, dans la mesure du possible, le paramètre dlrDate correspondant à la "Done Date" incluse dans le DLR (Delivery Receipt) reçu de l'opérateur réseau. Le format du paramètre dlrDate est YYMMDDhhmm où :

* YY est les deux derniers chiffres de l'année (00-99) * MM est le mois à deux chiffres (01-12) * DD est le jour à deux chiffres (01-31) * hh est les deux chiffres de l'heure (00-23) * mm est la minute à deux chiffres (00-59).

De plus, la requête contiendra les attributs messageId, src, dest, body, bulkId, numSegments, numMedia, et les attributs errorCode et errorMessage de l'objet MessagingItem correspondant. Notez que cette liste peut évoluer dans le temps sans préavis.

Pour des raisons de sécurité, la plateforme Reach inclut une signature dans l'en-tête de chaque requête envoyée à votre application via le paramètre X-Reach-Signature. Il est fortement recommandé de valider toute requête reçue par votre application afin de s'assurer qu'elle provient bien de la plateforme Reach. Pour ce faire, vous pouvez utiliser la méthode de validation de requête intégrée fournie par toutes nos bibliothèques clientes. Vous trouverez ci-dessous des extraits de code illustrant quelques exemples.

const apiKey = process.env.REACH_TALKYLABS_API_KEY;
const client = require('reach');

// Your callback url
const url = 'https://abcde123.app.com/callback';

// This is an example of parameters from the Reach platform request that are stored in a variable
const params = {
  dest: '+237671234567',
  src: '+237691234567',
  status: 'sent',
  messageId: 'MIDXXXXXXXXXX'
};

// Get the X-Reach-Signature header attached to the request as a variable
const reachSignature = 'BgtycF093HJywxcyTonHeJcuiZ8=';

// Validate the retrieved signature
console.log(client.validateRequest(apiKey, reachSignature, url, params));

Exemple 1: Envoyer un message SMS

L'exemple ci-dessous montre comment envoyer un SMS à l'aide de l'API de messagerie Reach.

En envoyant la requête de l'exemple, la plateforme Reach enverra un SMS de +237691234567 (un numéro de téléphone enregistré dans l'Applet qui envoie la requête) à +237671234567 et dont le contenu est Hello World! This is a sms message..

curl -X POST https://api.reach.talkylabs.com/rest/messaging/v1/create --data-urlencode "dest=+237671234567" --data-urlencode "src=+237691234567" --data-urlencode "body=Hello World! This is a sms message." -H "ApiUser: $REACH_TALKYLABS_API_USER" -H "ApiKey: $REACH_TALKYLABS_API_KEY"
Output example
{
  "appletId": "AIDXXXXXXXXXXXX",
  "apiVersion": "1.0.0",
  "body": "Hello World! This is a sms message.",
  "dest": "+237671234567",
  "src": "+237691234567",
  "bulkId": null,
  "numSegments": 1,
  "numMedia": 0,
  "price": 25.0,
  "priceUnit": "xaf",
  "messageId": "MIDXXXXXXXXXXXX",
  "status": "sent",
  "messageType": "outbound",
  "errorCode": null,
  "errorMessage": null,
  "dateCreated": "2016-08-29T09:12:33.001Z",
  "dateSent": "2016-08-29T09:12:34.001Z",
  "dateUpdated": "2016-08-29T09:12:35.001Z"
}

Exemple 2: Programmer un message SMS

L'exemple ci-dessous montre comment programmer un SMS à l'aide de l'API Reach Messaging.

Le message est programmé pour être envoyé le 31 août 2016, à 01:23:45 UTC.

curl -X POST https://api.reach.talkylabs.com/rest/messaging/v1/create --data-urlencode "dest=+237671234567" --data-urlencode "src=+237691234567" --data-urlencode "body=Hello World! This is a sms message." --data-urlencode "scheduledTime=2016-08-31T01%3A23%3A45Z" -H "ApiUser: $REACH_TALKYLABS_API_USER" -H "ApiKey: $REACH_TALKYLABS_API_KEY"
Output example
{
  "appletId": "AIDXXXXXXXXXXXX",
  "apiVersion": "1.0.0",
  "body": "Hello World! This is a sms message.",
  "dest": "+237671234567",
  "src": "+237691234567",
  "bulkId": null,
  "numSegments": 1,
  "numMedia": 0,
  "price": null,
  "priceUnit": null,
  "messageId": "MIDXXXXXXXXXXXX",
  "status": "scheduled",
  "messageType": "outbound",
  "errorCode": null,
  "errorMessage": null,
  "dateCreated": "2016-08-29T09:12:33.001Z",
  "dateSent": null,
  "dateUpdated": "2016-08-29T09:12:33.001Z"
}