Send a message

This operation allows to send or schedule a message.

When sending a new message via the API, you must include the dest parameter. This value should be the destination phone number. You must also include the body parameter containing the message's content as well as the src parameter containing the sender alphanumeric Id or number.

To schedule a message, you must additionally pass the following parameter:

• scheduledTime: the date and time at which the sms will be sent in the ISO-8601 format.

Parameters

• deststringrequired

  The destination phone number in E.164 format of the message.

• srcstringrequired

  The phone number (in E.164 format), or the alphanumeric sender ID that initiated the message.

• bodystringrequired

  The text of the message to send. It can be up to 1,600 GSM-7 characters in length. That limit varies if your message is not made of only GSM-7 characters. More generally, the message body should not exceed 10 segments.

• bulkIdentifierstringoptional

  The identifier of the bulk operation this message belongs to.

• scheduledTimedate-timeoptional

  The datetime at which the message will be sent. Must be in ISO 8601 format. A message must be scheduled at least 15 min in advance of message send time and cannot be scheduled more than 5 days in advance of the request.

• statusCallbackurloptional

  The URL that will be called to send updates regarding the status of your message. If provided, the Reach Messaging API will POST these message status changes to the URL: queued, failed, sent, canceled, delivered, or undelivered. URLs must contain a valid hostname and underscores are not allowed. See details for more information.

• maxPricenumberoptional

  The maximum total price in the applet currency that should be paid for the message to be delivered. If the cost exceeds maxPrice, the message will fail and a failed status is sent to the status callback.

• validityPeriodintegeroptional

  It represents how long, in seconds, the message can remain in the queue. After this period elapses, the message fails and the status callback is called. After a message has been accepted by a carrier, however, there is no guarantee that the message will not be queued after this period by the carrier. It is recommended that this value be at least 5 seconds. The maximum allowed value is 14,400 which corresponds to 4 hours. The default is 14,400.

Sending updates to the statusCallback URL

The statusCallback URL is meant to notify you or your application about an update regarding the status of a message sent via the Reach platform. Whenever the status of your message changed, the Reach platform sends a POST request on the provided URL.

The request will contain the new status of your message and, whenever possible, the dlrDate parameter corresponding to the Done Date included in the DLR (Delivery Receipt) received from the carrier. The format of the dlrDate is YYMMDDhhmm where:

* YY is last two digits of the year (00-99) * MM is the two-digit month (01-12) * DD is the two-digit day (01-31) * hh is the two-digit hour (00-23) * mm is the two-digit minute (00-59).

In addition, the request will contain the messageId, src, dest, body, bulkId, numSegments, numMedia, and the errorCode and errorMessage attributes of the corresponding MessagingItem object. Note that this list could evolve over time without prior notice.

For security purposes, the Reach platform includes a signature in the header of every request sent to your application via the X-Reach-Signature parameter. It is highly recommend to validate any request received by your application to be sure that it originates from the Reach platform. To do so, you can leverage the built-in request validation method provided by all of our client libraries. Below are code snippets demonstrating some examples.

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));

Example 1: Send an SMS message

The example below demonstrates how to send an SMS using the Reach Messaging API.

By sending the request in the example, the Reach platform will send an SMS from +237691234567 (a phone number registered to the Applet sending the request) to +237671234567 and whose content is 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"

{
  "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"
}

Example 2: Schedule an SMS message

The example below demonstrates how to schedule an SMS using the Reach Messaging API.

The message is scheduled to be sent on August 31 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"

{
  "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"
}