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:

https://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.

d7-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

Mandatory

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

Receiving DLR

When requested through dlr-* fields when sending_sms-mt, a delivery receipt (DLR) will be sent back to the application url (set in dlr-url) through HTTP GET/POST depending on dlr-method.

The receiving end point must reply back using a “200 OK” status header and a body containing an acknowledgement of receiving the DLR.

In order to acknowledge DLR receipt, the receiving end point must reply back with exactly the following html body content:

ACK/Jasmin

Note

It is very important to acknowledge back each received DLR, this will prevent to receive the same message many times, c.f. DLRThrower_process for details

Note

Reshipment of a message will be delayed for config/dlr-thrower/retry_delay seconds (see configuration_dlr-thrower).

HTTP Parameters for a level 1 DLR

The following parameters are sent to the receiving end point (at dlr-url) when the DLR’s dlr-level is set to 1 (SMS-C level only)

d7-http parameters for a level 1 DLR

Parameter

Value / Pattern

Example(s)

Presence

Description / Notes

id

Universally Unique IDentifier (UUID)

16fd2706-8baf-433b-82eb-8c7fada847da

Always

Internal Jasmin’s gateway message id used for tracking messages

message_status

ESME_* SMPP Command status

ESME_ROK, ESME_RINVNUMDESTS

Always

The delivery status

level

1

1

Always

This is a static value indicating the dlr-level originally requested

connector

SMPP Connector ID

demo_cid

Always

The SMPP Connector used to send the message

HTTP Parameters for a level 2 or 3 DLR

The following parameters are sent to the receiving end point (at dlr-url) when DLR’s dlr-level is set to 2 or 3 (Terminal level or all levels)

d7-http parameters for a level 2 or 3 DLR

Parameter

Value / Pattern

Example(s)

Presence

Description / Notes

id

Universally Unique IDentifier (UUID)

16fd2706-8baf-433b-82eb-8c7fada847da

Always

Internal Jasmin’s gateway message id used for tracking messages

id_smsc

Integer

2567

Always

Message id returned from the SMS-C

message_status

ESME_* SMPP Command status

ESME_ROK, ESME_RINVNUMDESTS

Always

The delivery status

level

1

1

Always

This is a static value indicating the dlr-level originally requested

connector

SMPP Connector ID

demo_cid

Always

The SMPP Connector used to send the message

subdate

Date & time format: YYMMDDhhmm

1311022338

Optional

The time and date at which the short message was submitted

donedate

Date & time format: YYMMDDhhmm

1311022338

Optional

The time and date at which the short message reached it’s final state

sub

Integer

1

Optional

Number of short messages originally submitted. This is only relevant when the original message was submitted to a distribution list.The value is padded with leading zeros if necessary

dlvrd

Integer

1

Optional

Number of short messages delivered. This is only relevant where the original message was submitted to a distribution list.The value is padded with leading zeros if necessary

err

Integer

0

Optional

Where appropriate this may hold a Network specific error code or an SMSC error code for the attempted delivery of the message

text

Text (20 char. max)

Hello foo bar

Optional

The first 20 characters of the short message