REST API

This document is targeted at software designers/programmers wishing to integrate SMS messaging as a function into their applications using RESTful API, e.g. in connection with WEB-server, unified messaging, information services etc.

SMS Messages can be transmitted using the RESTful API, the following requirements must be met to enable the service:

  • You need a Direct7 user account

  • You need sufficient credit on your Direct7 user account

Services

The Services resource represents all web services currently available via RESTful API.

RESTful services

Method

Service

Description / Notes

POST

/secure/send

Send a single message to one destination address.

POST

/secure/sendbatch

Send multiple messages to one or more destination addresses.

GET

/secure/balance

Get user account’s balance and quota.

Authentication

Services having the /secure/ path (such as Send a single message) require authentication using Basic Auth which transmits Direct7 account credentials as username/password pairs, encoded using base64.

Example:

curl -X GET -H 'Authorization: Basic Zm9vOmJhcg==' https://rest-api.d7networks.com/secure/sendbatch

We have passed the base64 encoded credentials through the Authorization header, ‘Zm9vOmJhcg==’ is the encoded username:password pair (‘foo:bar’), you can use any tool to base64 encode/decode.

If wrong or no authentication credentials are provided, a 401 Unauthorized error will be returned.

Send a single message

Send a single message to one destination address.

Definition:

https://rest-api.d7networks.com/secure/send

Parameters are the same as the http api.

Examples:

curl -X POST -H 'Authorization: Basic Zm9vOmJhcg==' -d '{
  "to": 19012233451,
  "from": "D7sms",
  "content": "Hello",
  "dlr": "yes",
  "dlr-url": "http://192.168.202.54/dlr_receiver.php",
  "dlr-level": 3
}'  https://rest-api.d7networks.com/secure/send

Note

Do not include username and password in the parameters, they are already provided through the Authorization header.

Result Format:

{"data": "Success \"c723d42a-c3ee-452c-940b-3d8e8b944868"}

If successful, response header HTTP status code will be 200 OK and and the message will be sent, the message id will be returned in data.

Send multiple messages

Send multiple messages to one or more destination addresses.

Definition:

https://rest-api.d7networks.com/secure/sendbatch

Example of sending same message to multiple destinations:

curl -X POST -H 'Authorization: Basic Zm9vOmJhcg==' -d '{
  "messages": [
    {
      "to": [
        "971509001XXX",
        "971549001XXX",
        "971559001XXX"
      ],
      "content": "Same content goes to 3 numbers",
      "from": "D7sms"
    }
  ]
}' https://rest-api.d7networks.com/secure/sendbatch

Result Format:

{"data": {"batchId": "af268b6b-1ace-4413-b9d2-529f4942fd9e", "messageCount": 3}}

If successful, response header HTTP status code will be 200 OK and and the messages will be sent, the batch id and total message count will be returned in data.

POST /secure/sendbatch json parameters

Parameter

Example(s)

Presence

Description / Notes

messages

[{“to”: 1, “content”: “hi”}, {“to”: 2, “content”: “hello”}]

Mandatory

A Json list of messages, every message contains the /secure/send parameters

globals

{“from”: “D7sms”}

Optional

May contain any global message parameter, c.f. examples

batch_config

{“callback_url”: “http://127.0.0.1:7877”, “schedule_at”: “2017-11-15 09:00:00”}

Optional

May contain the following parameters: callback_url or/and errback_url (used for batch tracking in real time c.f. examples), schedule_at (used for scheduling sendouts c.f. examples).

Note

The Rest API server has an advanced QoS control to throttle pushing messages back to Direct7, you may fine-tune it through the http_throughput_per_worker and smart_qos parameters.

Send binary messages

Sending binary messages can be done using single or batch messaging APIs.

It’s made possible by replacing the content parameter by the hex_content, the latter shall contain your binary data hex value.

Example of sending a message with coding=8:

curl -X POST -H 'Authorization: Basic Zm9vOmJhcg==' -d '{
  "to": 971509001XXX,
  "from": "D7sms",
  "coding": 8,
  "hex_content": "0623063106460628"
}' https://rest-api.d7networks.com/secure/send

The hex_content used in the above example is the UTF16BE encoding of arabic word “أرنب” (‘x06x23x06x31x06x46x06x28’).

Same goes for sending batches with binary data:

curl -X POST -H 'Authorization: Basic Zm9vOmJhcg==' -d '{
  "messages": [
    {
      "to": [
        "971509001XXX",
        "971504001XXX",
        "971505001XXX"
      ],
      "hex_content": "0623063106460628"
    }
  ]
}' https://rest-api.d7networks.com/secure/sendbatch

Usage examples:

The ref:parameter <restapi-POST_sendbatch_params> listed above can be used in many ways to setup a sendout batch, we’re going to list some use cases to show the flexibility of these parameters:

Example 1, send different messages to different numbers::

{
  "messages": [
    {
      "from": "Brand1",
      "to": [
        "55555551",
        "55555552",
        "55555553"
      ],
      "content": "Message 1 goes to 3 numbers"
    },
    {
      "from": "Brand2",
      "to": [
        "33333331",
        "33333332",
        "33333333"
      ],
      "content": "Message 2 goes to 3 numbers"
    },
    {
      "from": "Brand2",
      "to": "7777771",
      "content": "Message 3 goes to 1 number"
    }
  ]
}

Example 2, using global vars:

From the previous Example (#1) we used the same “from” address for two different messages (“from”: “Brand2”), in the below example we’re going to make the “from” a global variable, and we are asking for level3 dlr for all sendouts:

{
  "globals" : {
    "from": "Brand2",
    "dlr-level": 3,
    "dlr": "yes",
    "dlr-url": "http://some.fancy/url"
  }
  "messages": [
    {
      "from": "Brand1",
      "to": [
        "55555551",
        "55555552",
        "55555553"
      ],
      "content": "Message 1 goes to 3 numbers"
    },
    {
      "to": [
        "33333331",
        "33333332",
        "33333333"
      ],
      "content": "Message 2 goes to 3 numbers"
    },
    {
      "to": "7777771",
      "content": "Message 3 goes to 1 number"
    }
  ]
}

So, globals are vars to be inherited in messages, we still can force a local value in some messages like the “from”: “Brand1” in the above example.

Example 3, using callbacks:

As explained, Direct7 is enqueuing a sendout batch everytime you call /secure/sendbatch, the batch job will run and call Direct7’s http api to deliver the messages, since this is running in background you can ask for success or/and error callbacks to follow the batch progress.

{
  "batch_config": {
    "callback_url": "http://127.0.0.1:7877/successful_batch",
    "errback_url": "http://127.0.0.1:7877/errored_batch"
      },
  "messages": [
    {
      "to": [
        "55555551",
        "55555552",
        "55555553"
      ],
      "content": "Hello world !"
    },
    {
      "to": "7777771",
      "content": "Holà !"
    }
  ]
}

About callbacks:

The RESTful api is a wrapper around Direct7’s http api, it relies on Celery task queue to process long running batches.

When you launch a batch, the api will enqueue the sendouts through Celery and return a batchId, that’s the Celery task id.

Since the batch will be executed in background, the API provides a convenient way to follow its progression through two different callbacks passed inside the batch parameters:

{
  "batch_config": {
    "callback_url": "http://127.0.0.1:7877/successful_batch",
    "errback_url": "http://127.0.0.1:7877/errored_batch"
      },
  "messages": [
    {
      "to": "7777771",
      "content": "Holà !"
    }
  ]
}

The callback_url will be called (GET) everytime a message is successfuly sent, otherwise the errback_url is called.

In both callbacks the following parameters are passed:

Batch callbacks parameters

Parameter

Example(s)

Description / Notes

batchId

50a4581a-6e46-48a4-b617-bbefe7faa3dc

The batch id

to

1234567890

The to parameter identifying the destination number

status

1

1 or 0, indicates the status of a message sendout

statusText

Success “07033084-5cfd-4812-90a4-e4d24ffb6e3d”

Extra text for the status

About batch scheduling:

It is possible to schedule the launch of a batch, the api will enqueue the sendouts through Celery and return a batchId while deferring message deliveries to the scheduled date & time.

{
  "batch_config": {
    "schedule_at": "2017-11-15 09:00:00"
      },
  "messages": [
    {
      "to": "7777771",
      "content": "Good morning !"
    }
  ]
}

The above batch will be scheduled for the 15th of November 2017 at 9am, the Rest API will consider it’s local server time to make the delivery, so please make sure it’s accurate to whatever timezone you’re in.

It’s possible to use another schedule_at format:

{
  "batch_config": {
    "schedule_at": "86400s"
      },
  "messages": [
    {
      "to": "7777771",
      "content": "Good morning !"
    }
  ]
}

The above batch will be scheduled for delivery in 1 day from now (86400 seconds = 1 day).

Balance check

Get user account’s balance and quota.

Definition:

https://rest-api.d7networks.com/secure/balance

Parameters are the same as the http api

Examples:

curl -X GET -H 'Authorization: Basic Zm9vOmJhcg==' https://rest-api.d7networks.com/secure/balance

Note

Do not include username and password in the parameters, they are already provided through the Authorization header.

Result Format:

{"data": {"balance": "10.23", "sms_count": "ND"}}

If successful, response header HTTP status code will be 200 OK, the balance and the sms count will be returned in data.