Custom HTTP requests (inbound)

Contents

• Overview
• Connector definition
• The handler function
  • Function arguments
  • Returning data
  • Phase 1 – First pass
  • Phase 2 – Second pass

Overview

EMG uses its own format and parameter for inbound HTTP requests. For example:

http://emgserver:8080/bin/send?USERNAME=xxx&PASSWORD=yyy&DESTADDR=46123&MESSAGE=Hello+world

Sometimes EMG needs to be able to handle HTTP requests in other formats and in order to handle that we need a custom handler. You can implement such a custom handler via a HTTP connector that uses URLHANDLER keyword.

Connector definition

Sample connector definition using URLHANDLER:

CONNECTOR http-custom-in1 <
PROTOCOL=HTTP
TYPE=INCOMING
ADDRESS=0.0.0.0:8080
URLHANDLER=/sendsms_form:sendsms.pl:handle_form
URLHANDLER=/sendsms_xml:sendsms.pl:handle_xml
INSTANCES=5
USERS=users
>

Here we define a HTTP connector that listens on port 8080. It maps two different uris (“/sendsms_form” and “/sendsms_xml”) to two different functions (“handle_form” and “handle_xml”) defined in a perl file, sendsms.pl (relative paths are relative to EMGDIR, directory where server.cfg is located).

Sample perl script that implements handle_form and handle_xml

Sample URL for above connector and script:

http://emgserver:8080/sendsms_form?u=xxx&p=xxx&r=46123&t=Hello+world

The handler function

The handler function will be called at least once but it would normally be called twice for an accepted message.

Function arguments

Sample function definition:

sub do_handle_form {
  my ($ci, $arg) = @_;
  # Extract connector name
  my $cname = ${$ci}{'name'};
  my $data = ${$arg}{'data'};
  # Operation, 0 = Phase 1, 1 = Phase 2
  my $op = ${$arg}{'operation'};
  ...
}

The handler receives two arguments, a connector information hash reference and an argument hash reference.

The connection information hash contains the information of the connector where the url handler is defined. The argument hash contains two keys “operation” and “data”. The operation is set to “0” in phase1 and set to “1” in phase 2. The data contains the data from the http request (GET = query parameters, POST = body) and should be parsed by the script to extract user and message information.

Returning data

You return data from the handler function by setting additional keys in the argument hash. In phase 1 you would set “status”, “messages” and optionally “data”.

When setting a non-200 http status code, use the “data” option to set the status text (response body) returned to the http client. When returning a response body through the use of “data” remember to format it in a way that the client expects (plain text, json, xml etc).

if($recipient eq '' || $text eq '') {
  # Return fail
  ${$arg}{'status'} = 500;
  ${$arg}{'data'} = 'Parameters "r" and "t" are mandatory';
  return;
}

Phase 1 – First pass

The first time it is called it is supposed to extract and set up authentication and message parameters. A single message can be returned by setting ${$arg}{'messages'} to the reference of a hash with the message fields. Multiple messages can be returned by instead setting it to the reference of an array of such hashes. Furthermore, ${$arg}{'dlrs'} can be used to insert one or more delivery reports in the same way, but that requires the connector option ALLOW_INJECT_DLR to be set.

If no message is returned from this phase no further processing will take place. The list of fields supported here are the following. Of course, ‘origid’ and ‘messagestate’ only makes sense on a delivery report, and the address fields only on a message.

• charcode
• dcs
• dlr
• sourceaddr
• sourceaddr_ton
• sourceaddr_npi
• destaddr
• destaddr_ton
• destaddr_npi
• messagestate
• message
• username
• udh
• receipt
• origid

The HTTP status code must be set. For successful it should be set to 200 (or 202). If a mandatory parameter is missing status 500 should be set. To set http status to 200 for a successful request:

${$arg}{'status'} = 200;

Phase 2 – Second pass

In phase 2 the function is called once for each message returned from phase 1.

Now EMG has assigned a message id to each message and the message options are available from “message” in the argument hash.

my $m = ${$arg}{'message'};
my $msgid = ${$m}{'id'};

In phase two you would build the content / body of the http response and return it in argument hash key “data”.

To simply return the message id after accepting a message:

${$arg}{'data'} = ${$m}{'id'};