This topic describes the communication protocol between APPs and the webservice Followzup, to be used as a reference for the development of APPs for different types of mobile devices.

Whatever language is used, it must have the AES and RSA encryption libraries compatible with PHP, used in the development of the webservice, witch handles the requests of the mobile devices.

All communication between mobile devices APP and the webservice is performed through POST. For mobile devices requests, the POST destination URL is “http://followzup.com/wsdevice”.

The APP should define the following POST variables:

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.

The XML request sent to the webservice contains the parameters needed to execute the command.

In addition to the command to be executed and the parameters required for its execution, the XML request must include the request sequence, which corresponds to an integer starting from 1 at the device registration. After a request with sequence N, the next request must have the sequence N + 1.

IMPORTANT: In the initial registration of the device it is not necessary to enter the sequence number of the request, since the device has not yet been registered.

XML request response format (invalid sequence):

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

Where:

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

Here are the available commands for sending requests from mobile devices:

• Device registration;
• UREG: Unregister devices;
• LSUB: List subscriptions;
• LKUP: Search channels;
• SCHN: Subscribe channel;
• UCHN: Unsubscribe channel;
• ICON: Get channel icons;
• RESP: Send a message (response) to the application channel;
• DMSG: Delete message;
• CHCK: Check new messages.

All requests forwarded to the webservice must contain the Stamp code of the Interface. The Stamp code is a 128-byte string randomly generated by Followzup when a new Interface is created.

Each Interface record is associated with an APP, and the inclusion of new Interfaces can only be performed by the Followzup administrator.

To create a new APP, the developer must request the registration of the new Interface to the Followzup administrator. After inclusion, the developer will receive the new interface code (Interface-ID), the Stamp code and the RSA public key of the Interface for registering new devices.

The informations stored on the device's local base are:

Device information:

• Interface-ID: Interface identification (APP);
• Stamp: Stamp code;
• Device-ID: Device identification;
• User-ID: User identification;
• Device-tag: Device name;
• Public-key: RSA Public key (BASE64 format);
• Public-key-module: RSA Public key module (BINARY format);
• Public-key-index: RSA Public key index (BINARY format);
• Message-ID: Last message identification received;
• MD5-channel-list: Hash MD5 of the channel list;
• Last-sequence: Last request sequence number.

Subscribed channels list:

• Channel-tag: Tag of the channel;
• Subscription-code: Subscription code;
• Flag-response: Flag to display the channel text box.

Search channels list:

• Channel-tag: Tag of the channel;
• Presentation-text: Presentation text of the channel;
• Flag-private: Private channel flag;
• Flag-private-code: Private-Code flag.

Channels icon list:

• Channel-tag: Tag of the channel;
• MD5-icon: Hash MD5 of the icon image;
• Icon-image: Image string (jpeg, BASE64 format).

Messages list:

• Channel-tag: Tag of the channel;
• Message-ID: Message identification;
• Data/Hora: Date and time the message was sent (UTC);
• Message-text: Text of the message (BASE64 format);
• Message-URL: URL of the message (BASE64 format).

The following is the APP operating flow, indicating where each command is executed.