Use HTTP callbacks

<< Click to Display Table of Contents >>

Navigation:  How to... >

Use HTTP callbacks

Only available in Diafaan SMS Server - basic and full editions.

 

Diafaan SMS Server can use HTTP callbacks to send information about the message flow in Diafaan SMS Server to a web server. The web server can use this information for message and user accounting. For messages to send (action message_out) or for received messages (action message_in) it is also possible to block the messages completely or to change the message fields with the web server script.

 

The response of all the HTTP callback should be a URL (percentage) encoded query string. The minimum response for all callbacks is 'result=1', this means that the message will be handled normally by Diafaan SMS Server. It is important that the response from the HTTP server is as fast as possible since the handling of other messages in the Gateway or Connector is blocked until the HTTP callback is finished. When the HTTP callback takes more than 5 seconds, the message is rejected.

 

There is an example PHP HTTP callback script available on the download page of the Diafaan SMS Server website that can be used a a base for a customized script. The script includes a minimal implementation of the HTTP callback functionality and a basic user accounting system, intended for use with the SMPP Connector.

 

Message out HTTP callback


The message out callbacks are sent from each individual connector, just before the message is added to the message queue of Diafaan SMS Server. The message can be discarded with the response 'result=0' and most of the message fields can be changed in the HTTP response query string.

 

HTTP query parameters

source

The name of the connector that is sending the HTTP callback.

action

"message_out".

user_id

User ID of the user sending the message.

ip_number

The IP number of the sender, if applicable.

from

The source number or name to be sent with the message.

to

The destination address of the message.

message

The message text of the message.

message_type

The message type for the message.

message_guid

Unique message GUID for the message.

message_info

User generated message info, this value is not used by Diafaan SMS Server and can be set freely.

user_info

The optional user info field.

priority

The priority of the message, default 0.

gateway

The name of the gateway(s) that are allowed to send the message.

tlv_list

Optional TLV list when the message is sent with an SMPP server.

session_count

The index of the message in the current session. This field is only used in connection based connectors like the SMPP Connector.

example: http://host.com/?source=SQL+Connector&action=message_out&user_id=&ip_number=&from=%2B44xxxxxxxx&to=%2B44xxxxxxxx&message=Message+text

 

The HTTP response may contain the following parameters, the optional parameters should only be used if you want to change one or more of the message fields

result

M

"0" (reject message) or "1" (accept message).

result_error_text

O

Optional error text to facilitate debugging if result=0. This parameter is ignored by Diafaan SMS Server.

user_id

O

User ID of the user sending the message.

from

O

The source number or name to be sent with the message.

to

O

The destination address of the message.

message

O

The message text of the message.

message_type

O

The message type for the message.

message_guid

O

Unique message GUID for the message.

message_info

O

User generated message info, this value is not used by Diafaan SMS Server and can be set freely.

user_info

O

The optional user info field.

error_code

O

A connector dependent error code that is sent back to the sender when the message is rejected. For messages from the SMPP Connector, the error code must be one of the ESME_R.... error numbers.

error_text

O

The error text that is sent back to the sender when the message is rejected. Not all connector protocols support an error text.

priority

O

The priority of the message, default 0.

gateway

O

The name of the gateway(s) that are allowed to send the message.

tlv_list

O

Optional TLV list when the message is sent with an SMPP server.

close_connection

O

Set to "1" to request that the connector closes the connection to the client after the message is handled (sent or rejected).

example: result=1&user_id=64535&from=%2B4400000000&to=%2B4411111111&message=Changed+message+text

 

 

Message in HTTP callback


The message in callbacks are sent from each individual gateway, just before the message is added to the message queue of Diafaan SMS Server. The message can be discarded with the response 'result=0' and most of the messages fields can be changed in the HTTP response query string.

 

HTTP query parameters

source

The name of the connector that is sending the HTTP callback.

action

"message_in".

from

The source number or name to be sent with the message.

to

The destination address of the message.

sms_central

The SMSC number of the SMSC that delivered the message.

message

The message text of the message.

message_type

The message type for the message.

message_part

The message part number when an incomplete multi-part message is received.

message_parts_received

The received number of message parts when an incomplete multi-part message is received.

message_parts_total

The total amount of messages parts of this message.

send_time

The send date and time of the message.

receive_time

The date and time the message is received by Diafaan SMS Server.

pdu

The PDU of the message.

tlv_list

The TLV list of the SMPP message (only for messages from an SMPP Gateway).

example: http://host.com/?source=GSM+Modem+Gateway&action=message_in&from=%2B44xxxxxxxx&to=%2B44xxxxxxxx&message=Message+text

 

The HTTP response may contain the following parameters, the optional parameters should only be used if you want to change one or more of the message fields

result

M

"0" (reject message) or "1" (accept message).

result_error_text

O

Optional error text to facilitate debugging if result=0. This parameter is ignored by Diafaan SMS Server.

user_id

O

User ID of the user sending the message.

from

O

The source number or name to be sent with the message.

to

O

The destination address of the message.

message

O

The message text of the message.

message_type

O

The message type for the message.

connector_list

O

The list of connectors that may receive the message.

example: result=1&user_id=64535&from=%2B4400000000&to=%2B4411111111&message=Changed+message+text

 

 

Message log HTTP callback


The message log callbacks are sent from each individual connector when the initial send result of the message is received.

 

HTTP query parameters

source

The name of the connector that is sending the HTTP callback.

action

"message_log".

user_id

User ID of the user sending the message.

from

The source number or name to be sent with the message.

to

The destination address of the message.

message

The message text of the message.

message_type

The message type for the message.

message_guid

Unique message GUID for the message.

message_info

User generated message info.

message_id

The message ID that was returned by the gateway.

message_parts

The number of sent message parts for the message.

gateway

The name of the gateway that has sent the message.

status_code

"200" (message sent) or "300" (message failed).

status_text

The status text of the message.

error_code

The error code that was returned by the gateway.

error_text

The error text that was returned by the gateway.

send_time

The date and time the message was sent, in ISO 8601 UTC format.

user_info

The optional user info field.

pdu

The PDU or comma separated PDU list of the sent message.

result_trace

An error trace of the message, this field can give an indication of the reliability of the gateways.

 

The HTTP response is ignored by Diafaan SMS Server, it is best to return 'result=1' for future compatibility.

 

 

Message log update HTTP callback


The message log update callbacks are sent from each individual connector when an update is received for a previous message log callback. This callback is usually sent after a delivery confirmation is received for one of the messages.

 

HTTP query parameters

source

The name of the connector that is sending the HTTP callback.

action

"message_log_update".

user_id

User ID of the user sending the message.

message_id

The message ID that was returned by the gateway.

message_guid

Unique message GUID for the message.

message_info

User generated message info.

status_code

"201" (message received on phone) or "301" (message could not be delivered to the phone).

status_text

The status text of the message.

error_code

The error code that was returned by the gateway.

error_text

The error text that was returned by the gateway.

receive_time

The date and time the message was received on the phone (only when status_code is "201"), in ISO 8601 UTC format.

user_info

The optional user info field.

receipt

The receipt text of the delivery report (only for receipts from an SMPP Gateway).

tlv_list

The TLV list of the SMPP receipt (only for receipts from an SMPP Gateway).

 

The HTTP response is ignored by Diafaan SMS Server, it is best to return 'result=1' for future compatibility.

 

 

Event log HTTP callback


The event log callbacks are sent for all error, warning or information events in Diafaan SMS Server. Repeating errors are usually throttled to a maximum of one per hour, similar to the event log in Diafaan SMS Server.

 

HTTP query parameters

source

The name of the module in Diafaan SMS Server that triggered the event.

action

"event_log"

event_time

The date and time when the event was triggered, in ISO 8601 UTC format.

event_type

"error", "warning", "error" or "unknown".

event_message

The event description.

event_trace

The event description, including optional additional information about the source of the problem.

 

The HTTP response is ignored by Diafaan SMS Server, it is best to return 'result=1' for future compatibility.

 

 

Validate user HTTP callback


Validate the user name or password, depending on the type of connector this callback is sent once for every connection or every time a message has to be send. Connectors that do not support user/password logon, like the SQL Connector, don't send this callback at all.

 

HTTP query parameters

source

The name of the connector that is sending the HTTP callback.

action

"validate_user".

ip_number

The IP number of the sender (if applicable).

user_id

The login user ID (user name).

password

The login password.

example: http://host.com/?source=Web+Connector&action=validate_user&user_id=&ip_number=127%2E0%2E0%2E1&user_name=User&password=Password

 

The HTTP response may contain the following parameters, the optional parameters should only be used if you want to change the user ID

result

M

"0" (reject username and password) or "1" (accept user name and password).

result_error_text

O

Optional error text to facilitate debugging if result=0. This parameter is ignored by Diafaan SMS Server.

user_id

O

User ID override.

example: result=1&user_id=64535

 

User validation requests from an SMPP Connector can also return these connection specific parameters

smpp_maxmessagesperminute

O

A numeric value of 0 (unlimited) or higher.

smpp_messageidformat

O

"hexadecimal", "decimal" or "guid".

smpp_characterencoding

O

"gsmdefaultalphabet", "iso_8859_1", "iso_8859_15", "gsmdefaultalphabet7bitspacked" or "gsmdefaultalphabet7bitspackedifudh".

smpp_packettimeout

O

A numeric value between 10 and 120 (seconds).

smpp_connectiontimeout

O

A numeric value between 10 and 3600 (seconds).

smpp_maxuseridconnections

O

A numeric value of 0 (unlimited) or higher.

smpp_use16bitconcatenationid

O

"0" (no) or "1" (yes).

smpp_messageouthandling

O

"default" or "smpp_packets".

smpp_messageinhandling

O

"deliver_sm", "deliver_sm_usepayloadtlv" or "data_sm".

example: result=1&smpp_maxmessagesperminute=600&smpp_use16bitconcatenationid=1

 

 

Accept connection HTTP callback


This callback is sent when a client wants to connect to an IP server based Connector, like the SMPP Connector. The connection can be refused if the response is 'result=0'.

 

HTTP query parameters

source

The name of the connector that is sending the HTTP callback.

action

"accept_connection".

ip_number

The IP number of the sender (if applicable).

example: http://host.com/?source=SMPP+Connector&action=accept_connection&user_id=&ip_number=127%2E0%2E0%2E1

 

The HTTP response may contain the following parameters, the optional parameters should only be used if you want to change the user ID.

result

M

"0" (reject connection) or "1" (accept connection).

result_error_text

O

Optional error text to facilitate debugging if result=0. This parameter is ignored by Diafaan SMS Server.

user_id

O

User ID override.

example: result=1&user_id=64535