User Tools

Site Tools


en-111-communication


Communication Process

Information channels and mobile devices communicate with webservice in asynchronous mode through POST requests.

In the case of information channels, they also receive information from the webservice through POST when users send messages to the application from their mobile device. This type of request will be detailed later (topic POST messages from users).



POST Request to webservice

The POST request from information channels and mobile devices to webservice includes 3 parameters:

  • id: Contains the identification of the requester, which may be the internal code of the channel (Channel-ID), the internal code of the mobile device (Device-ID) or the internal code of the interface (Interface-ID ). The latter (Interface-ID), is used to request registration of new devices;

  • key: Contains the temporary AES key encrypted with the public key of the requestor and encoded in Base64;

  • frame: Contains the XML request, encrypted with the temporary AES key and encoded in Base64. The content of this XML depends on the type of request that was sent (command and parameters).



XML request

The content of the XML request (encrypted and base64-encoded in the POST parameter frame), varies depending on the type of request that is being forwarded to the webservice.

Into a XML request, two tags are common to all requests except for registration of new devices. They are:

  • cmd: Contains the command to be executed by the webservice;
  • seq: Contains the sequence number of the request.

The available commands for information channels are: smsg and chck. For mobile devices, in addition to requesting registration of new devices, the available commands are: ureg, lsub, lkup, icon, schn, uchn, chck, dmsg and resp.

For mobile devices, the tag stp (interface stamp) is also common to all requests, including the registration of new devices.

The others tags, vary according to the requested command and correspond to the parameters necessary to its execution.

The tag seq (request sequence) corresponds to an integer starting from 1 at the creation of the information channel or the device registration. After a request with sequence N, the next request must have the sequence N + 1.

Commands sent with sequence error are not executed by webservice, and the corresponding error code is returned to the requester (code 6101 for information channels and 7101 for mobile devices ).

Requests for registering new devices does not receive the 7101 errors, because in the registration, the sequence number is still being created.



XML POST response

In response to the POST, the webservice returns the XML POST response, which should not mistaken with the XML request response, as described below. The POST response XML includes 3 tags:

<?xml version="1.0" encoding="utf-8"?>
<followzup>
<retcode>return-code</retcode>
<retframe>xml-request-response</retframe>
<retmd5>md5-hash</retmd5>
</followzup>

where:

  • retcode: Return code of the requested command represented by 4 numeric digits or “0” (zero) for successfully execution;
  • retframe: Contains the XML request response, encrypted with the temporary key AES and encoded in Base64. The XML request response depends on the command that was requested and the AES key used in its encryption is the same were used when the request was sent;
  • retmd5: Contains the MD5 hash of the retframe tag, to be validated by the requester.



XML request response

After decrypting the retframe tag from the XML POST response, we get the XML request response, whose content depends on the type of command sent to the webservice. For XML request response details, see the respective command documentation.


XML request response (invalid sequence):

In case of an invalid sequence (error code 6101 or 7101), the following XML request response XML returs to the requester:

<?xml version="1.0" encoding="utf-8"?>
<followzup>
<seq>Last-sequence</seq>
</followzup>

Where:

  • Last-sequence: Sequence number used in the last request.

When the requester receives a sequence error (6101 or 7101), it must get the value of the last sequence sent (Last-sequence), add 1 and re-send the request to the webservice.



POST from User messages

When the information channel has a valid URL in the Response Message URL attribute, the APP (mobile device) shows a text box in the channel message list. When the user sends a message through this text box, the application receives a POST from the webservice for the given URL. This POST contains the message sent by the user.

The variables included in POST are described in the topic Receiving messages from users.

In the Followzup communication protocol, the POST sent to the application does not return any information to the webservice.


en-111-communication.txt · Last modified: 2017/05/30 07:14 by admin

Page Tools