HTTP API specifications

<< Click to Display Table of Contents >>

Navigation:  Reference > Connector properties > Web connector >

HTTP API specifications

HTTP commands, all editions


HTTP commands can be sent with both GET or POST methods, the POST method requires a url-encoded BODY with content-type 'application/x-www-form-urlencoded '. In this manual the GET method is used for all examples.

 

send-message

Send one or more messages.

 

parameters

username

optional

The name of the user, if omitted the guest account is used

password

optional

The password of the user

to

required

One or more phone/pager numbers, separated by semicolons

contact-name

required

One or more contact names and/or groups from the user's contact list, separated by semicolons

from

optional

Sender id

message

optional

Message text

message-type

optional

Message type to indicate if the message is text, Unicode, flash etc.

message-guid

optional

Unique message id, this parameter overrides the standard message ID of Diafaan SMS Server

message-info

optional

Freely usable message info, this parameter is not used internally by Diafaan SMS Server

gateway

optional

One or more gateway names, separated by semicolons, that may be used to send the message

priority

optional

A higher number ensures that the message is placed higher in the message send queue and is sent before messages with a lower priority.

validity-period

optional

The validity period of the SMS message, in seconds.

 

returns

OK: message-id

or

ERROR:error-code error-message

 

If multiple messages are sent this command returns one response line per message in the order at which the numbers are located in the to and contact-name fields. Since numbers may be blocked and the contact-name can be a group, the number of return lines may be different from the number of to or contact-name entries.

 

example

http://localhost:9710/http/send-message?username=admin&password=&to=%2B44xxxxxxxx&message-type=sms.automatic&message=Message+Text

 

request-status-update

Get the status of a previously sent message.

 

parameters

username

optional

The name of the user, if omitted the guest account is used

password

optional

The password of the user

message-id

mandatory

Message id of the previously sent message

info

optional

The type of status information that is returned:

 

"status" status code and status message (default)

"error-code" error code and error text (if available)

"gateway" the name of the gateway that sent the message (if available)

 

returns

STATUS:status-code status-message

or

ERROR-CODE:error-code error-message

or

GATEWAY:gateway-name

or (if the API call fails)

ERROR:error-code error-message

 

example

http://localhost:9710/http/request-status-update?username=admin&password=&message-id=c3b0c20a-b63e-4bbf-919f-3d4251a8b9c0

 

remove-queued-message

Remove a previously sent message from the send queue.

 

parameters

username

optional

The name of the user, if omitted the guest account is used

password

optional

The password of the user

message-id

mandatory

Message id of the previously sent message

 

returns

OK: status-message

or

ERROR: error-message

 

example

http://localhost:9710/http/remove-queued-message?username=admin&password=&message-id=c3b0c20a-b63e-4bbf-919f-3d4251a8b9c0

 

request-server-status

Get the status of the Diafaan SMS Server and all the Gateways and Connectors statistics.

 

parameters

username

optional

The name of the user, if omitted the guest account is used

password

optional

The password of the user

 

returns

An XML file with the status and statistics of Diafaan SMS Server.

or

ERROR:error-code error-message

 

example

http://localhost:9710/http/request-server-status?username=admin&password=

 

request-received-messages

Get a list of received messages in the inbox.

 

parameters

username

optional

The name of the user, if omitted the guest account is used

password

optional

The password of the user

limit

optional

The maximum number of messages returned

remove

optional

Set to "1" to remove the returned messages from the database

order

optional

Set to "newest" to get newest messages first, otherwise oldest messages are displayed first.

 

returns

An XML file with a list of the requested messages.

or

ERROR:error-code error-message

 

example

http://localhost:9710/http/request-received-messages?username=admin&password=&limit=10&order=newest

 

<?xml version='1.0' encoding='UTF-8'?>

<MessageList Count="2">

 <Message>

   <From>+44xxxxxx</From>

   <To />

   <MessageText>Message text 1</MessageText>

   <MessageType>sms.text</MessageType>

   <MessageId>ae97a8b7-5336-445a-ae67-e658aa8f6aed</MessageId>

   <MessagePart>-1</MessagePart>

   <ReceivedMessageParts>1</ReceivedMessageParts>

   <TotalMessageParts>1</TotalMessageParts>

   <SendTime>20100219200855</SendTime>

   <ReceiveTime>20100219200848</ReceiveTime>

   <Gateway>GSM Modem Gateway</Gateway>

   <SMSC>+44xxxxxxxxx</SMSC>

   <PDU>079458560488019539B53F50000012091028055400DD47719649987CD25D87506</PDU>

   <IsRemoved>0</IsRemoved>

 </Message>

 <Message>

   <From>+33xxxxxxxx</From>

   <To />

   <MessageText>Message text 2</MessageText>

   <MessageType>sms.text</MessageType>

   <MessageId>ae97a8b7-5336-445a-ae67-e658aa8f6aed</MessageId>

   <MessagePart>-1</MessagePart>

   <ReceivedMessageParts>1</ReceivedMessageParts>

   <TotalMessageParts>1</TotalMessageParts>

   <SendTime>20100219200855</SendTime>

   <ReceiveTime>20100219200848</ReceiveTime>

   <Gateway>GSM Modem Gateway</Gateway>

   <SMSC>+33xxxxxxxxx</SMSC>

   <PDU>07474523460488019539B53F50000012091028055400DD47719649987CD25D87506</PDU>

   <IsRemoved>0</IsRemoved>

 </Message>

</MessageList>

 

 

HTTP commands, basic- and full edition only


Warning: The 'send-server-command' HTTP API command can leave Diafaan SMS Server in an unstable state if one of the server setting, gateway settings, connector settings or routing settings is set to an unsupported value.

 

The 'send-server-command' HTTP API command can only be used by the administrator (admin) account or by a user with administrator privileges.

In Diafaan SMS Server 4.0 or higher this command is disabled by default, it can be enabled with the SendServerCommandEnabled property in the advanced settings of the Web Connector.

 

send-server-command

Send a command to the server to start and stop a gateway or connector or change one of the settings of the server

 

Start one or more gateways

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"start-gateway"

gateway

optional

The name of the gateway or a list of gateway names, separated by semicolons. Leave empty to affect all gateways

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=start-gateway&gateway=GSM+Modem+Gateway

 

Stop one or more gateways

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"stop-gateway"

gateway

optional

The name of the gateway or a list of gateway names, separated by semicolons. Leave empty to affect all gateways

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=stop-gateway&gateway=GSM+Modem+Gateway+1%3BGSM+Modem+Gateway+2

 

Restart (stop and start) one or more gateways

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"restart-gateway"

gateway

optional

The name of the gateway or a list of gateway names, separated by semicolons. Leave empty to affect all gateways

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=restart-gateway

 

Start one or more connectors

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"start-connector"

connector

optional

The name of the connector or a list of connector names, separated by semicolons. Leave empty to affect all connectors

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=start-connector&connector=Email+Connector

 

Stop one or more connectors

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"stop-connector"

connector

optional

The name of the connector or a list of connector names, separated by semicolons. Leave empty to affect all connectors

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=stop-connector&connector=Email+Connector%3BSQL+Connector

 

Restart (stop and start) one or more connectors

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"restart-connector"

connector

optional

The name of the connector or a list of connector names, separated by semicolons. Leave empty to affect all connectors

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=restart-connector&connector=Email+Connector%3BSQL+Connector

 

Reset send limit, only for GSM Modem Gateways

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"reset-send-limit"

gateway

optional

The name of the GSM Modem Gateway or a list of gateway names, separated by semicolons. Leave empty to affect all GSM Modem Gateways

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=reset-send-limit&gateway=GSM+Modem+Gateway

 

Pause sending messages with the selected gateway(s)

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"pause-sending"

gateway

optional

The name of the gateway or a list of gateway names, separated by semicolons. Leave empty to affect all gateways

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=pause-sending&gateway=GSM+Modem+Gateway

 

Resume sending messages with the selected gateway(s)

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"resume-sending"

gateway

optional

The name of the gateway or a list of gateway names, separated by semicolons. Leave empty to affect all gateways

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=resume-sending&gateway=GSM+Modem+Gateway

 

Get the server configuration XML data (all gateway and connector settings)

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"get-server-configuration"

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=get-server-configuration

 

Get the server settings XML data (all general settings of Diafaan SMS Server)

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"get-server-settings"

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=get-server-settings

 

Change one of the gateway properties (see the server configuration XML data for valid properties and values)

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"set-gateway-property"

gateway

optional

The name of the gateway or a list of gateway names, separated by semicolons. Leave empty to affect all gateways

property

mandatory

The name of the gateway property

value

mandatory

The new value of the gateway property

reload

optional

Set to "0" to prevent restarting the gateway if you want to change more properties, by default the gateway is restarted immediately

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=set-gateway-property&gateway=GSM+Modem+Gateway&property=Enabled&value=0

 

Change one of the connector properties (see the server configuration XML data for valid properties and values)

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"set-connector-property"

connector

optional

The name of the connector or a list of connector names, separated by semicolons. Leave empty to affect all connectors

property

mandatory

The name of the connector property

value

mandatory

The new value of the connector property

reload

optional

Set to "0" to prevent restarting the connector if you want to change more properties, by default the connector is restarted immediately

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=set-connector-property&connector=SQL+Connector&property=SMSOut.Enabled&value=0

 

Change one of the connector routing properties (see the server configuration XML data for valid properties and values)

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"set-routing-property"

connector

optional

The name of the connector or a list of connector names, separated by semicolons. Leave empty to affect all connectors

gateway

optional

The name of the gateway or a list of gateway names, separated by semicolons. Leave empty to affect all gateways

property

mandatory

The name of the routing property

value

mandatory

The new value of the routing property

reload

optional

Set to "0" to prevent restarting the connector if you want to change more routing properties, by default the connector is restarted immediately

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=set-routing-property&connector=SQL+Connector&gateway=GSM+Modem+Gateway&property=Receive&value=0

 

Change one of the settings properties (see the server settings XML data for valid properties and values)

username

mandatory

The name of the user, the user must have administrator privileges

password

mandatory

The password of the user

command

mandatory

"set-settings-property"

property

mandatory

The name of the settings property

value

mandatory

The new value of the settings property

reload

optional

Set to "0" to prevent reloading the new setting if you want to change more settings, by default the new setting is loaded immediately

example

http://localhost:9710/http/send-server-command?username=admin&password=&command=set-settings-property&property=LogEventsToEmail&value=1