HTTP API

Direct7 HTTP API allows sms gateway integration using simple HTTP GET/POST requests.

SMS Messages can be transmitted using HTTP protocol, 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

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

Features

Using HTTP API you can:

  • Send and receive SMS,

  • Receive http callbacks for delivery notification (receipts) when SMS is received (or not) on mobile station

  • Send and receive long (more than 160 characters) SMS, unicode/binary content and receive http callbacks when a mobile station sends you a SMS-MO.

  • Check your balance status

Sending SMS

In order to deliver SMS-MT messages, Data is transferred using HTTP GET/POST requests. The D7 gateway accepts requests at the following URL:

http://smsc.d7networks.com:1401/send

This guide will help understand how the API works and provide examples for sending SMS.

HTTP request parameters

When calling HTTP API URL from an application, the below parameters must be passed (at least mandatory ones), the api will return a message id on success, see HTTP response.

ja-http sending SMS parameters

Parameter

Value / Pattern

Example(s)

Presence

Description / Notes

to

Destination address

20203050

Mandatory

Destination address, only one address is supported per request

from

Originating address

20203050, D7

Optional

Originating address, In case rewriting of the sender’s address is supported or permitted by the SMS-C used to transmit the message, this number is transmitted as the originating address

coding

0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 13 or 14

1

Optional

Sets the Data Coding Scheme bits, default is 0, accepts values all allowed values in SMPP protocol [1]_

username

Text (30 char. max)

D7_user

Mandatory

Username for D7 user account.

password

Text (30 char. max)

D7_pass

Mandatory

Password for D7 user account.

priority

0, 1, 2 or 3

2

Optional

Default is 0 (lowest priority)

sdt

String

000000000100000R (send in 1 minute)

Optional

Specifies the scheduled delivery time at which the message delivery should be first attempted, default is value is None (message will take SMSC’s default). Supports Absolute and Relative Times per SMPP v3.4 Issue 1.2

validity-period

Integer

1440

Optional

Message validity (minutes) to be passed to SMSC, default is value is None (message will take SMSC’s default)

dlr

yes or no

yes

Optional

Default is no (no DLR will be tracked)

dlr-url

HTTP(s) URL

http://host/dlr.php

Mandatory if dlr

If a DLR is requested (dlr = ‘yes’), dlr-url MUST be set, if not, dlr value is reconsidered as ‘no’

dlr-level

1, 2 or 3

2

Mandatory if dlr

1: SMS-C level, 2: Terminal level, 3: Both

dlr-method

GET or POST

GET

Mandatory if dlr

DLR is transmitted through http to a third party application using GET or POST method.

tags

Text

1,702,9901

Optional

Will tag the routable to help interceptor or router enable specific business logics.

content

Text

Hello world !

Mandatory if hex-content not defined

Content to be sent

hex-content

Binary hex value

0623063106460628

Mandatory if content not defined

Binary to be sent

HTTP response

When the request is validated, a SubmitSM PDU is set up with the provided request parameters and sent to the routed connector through a AMQP queue, a queued message-id is returned:

Success "07033084-5cfd-4812-90a4-e4d24ffb6e3d"

Otherwise, an error is returned:

Error "No route found"
HTTP response code details

HTTP Code

HTTP Body

Meaning

200

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

Message is successfully queued, messaged-id is returned

400

Error “Mandatory arguments not found, please refer to the HTTPAPI specifications.”

Request parameters validation error

400

Error “Argument _ is unknown.”

Request parameters validation error

400

Error “Argument _ has an invalid value: _.”

Request parameters validation error

400

Error “Mandatory argument _ is not found.”

Request parameters validation error

400

dynamic messages

Credentials validation error, c.f. user_credentials

403

Error “Authentication failure for username:_”

Authentication error

403

Error “Authorization failed for username:_”

Credentials validation error, c.f. user_credentials

403

Error “Cannot charge submit_sm, check RouterPB log file for details”

User charging error

412

Error “No route found”

Message routing error

500

Error “Cannot send submit_sm, check SMPPClientManagerPB log file for details”

Fallback error, checking log file will provide better details