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.
user_name	User name of the user sending the message, for some connectors it is the same as user_id.
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.
scheduled	Optional date and time when the message should be sent, in ISO 8601 format.
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.
scheduled	O	The date and time when the message should be sent, in ISO 8601 format. Set to an empty string to reset/remove the schedule. E.g.: '2020-12-31T19:35:00', or including time zone: '2020-12-31T19:35:00.0000000-07:00'
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 Gateway.
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 gateway 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_id	The message ID of the message, used to be able to combine multi-part messages.
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.
tlv_list	O	Optional TLV list when the message forwarded to an SMPP Connector
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	"information", "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".
smpp_clientasyncwindowsize	O	A numeric value of 1 (no asynchronous window) or higher.
smpp_includetlvparameters	O	"0" (deliver_sm packets are sent without TLV parameters) or "1" (default, deliver_sm packets can be sent with TLV parameters).
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