User Tools

Site Tools


en-030-api-usage


Using the chanel APIs

The APIs serve to assist the application developer in the process of communicating with webzervice Followzup and in the process of decrypting the messages sent by the users, and must be obtained by download from the Followzup website.

Within the API there is a class identified by “ FZUP_xxxxxxxxxxxx ”, where “xxxxxxxxxxxx” corresponds to the Channel-ID of the channel.

The class has 3 methods:

constructor Method used in the instantiation of the object to be referenced.
decrypt Method used to decrypt messages from users' mobile devices.
submit Method to submit requests to webzervice Followzup, which can be used to send messages (command smsg) or check users (command chck).



Constructor method

Applications must instantiate an object for each channel used. When instantiated, the object initializes the variables containing the Channel ID, the cryptographic key, and the sequence number of the requests. The object must be instantiated according to the examples below:

PHP
include ("fzup_cXXXXXXXXXXX.php");
$object = new fzup_cXXXXXXXXXXX;
JAVA
import mylib.fzup_cXXXXXXXXXXX;
fzup_cXXXXXXXXXXX object = new fzup_cXXXXXXXXXXX();
RUBY
require 'fzup_cXXXXXXXXXXX'
object = fzup_cXXXXXXXXXXX.new
PERL
use fzup_cXXXXXXXXXXX;
my $object = new fzup_cXXXXXXXXXXX();
PYTHON
from fzup_cXXXXXXXXXXX import fzup_cXXXXXXXXXXX
object = fzup_cXXXXXXXXXXX()
C# .NET
fzup_cXXXXXXXXXXX object = new fzup_cXXXXXXXXXXX();
fzup_param parameters = new fzup_param();
fzup_result result = new fzup_result();



Decrypt method

The decrypt method is for decrypting messages sent by users from their mobile devices.

Here's how to use this method in the “Receiving messages from users”.



Submit method

To send messages and verify users, applications must use the submit method, which receives parameters informed by an array of strings, where each element of the array contains the parameter name and its value, separated By the equal sign. The return of this method also corresponds to an array of strings. The general call format of the method is as follows:

PHP
$result = $object -> submit ( array (
"FZUP_COMMAND = xxxx",
"FZUP_LASTSEQ = 9999",
"FZUP_PARAM_X = ...",
"FZUP_PARAM_Y = ...",
"FZUP_PARAM_Z = ..." ) );
JAVA
String[] result = object.submit ( new String[] {
"FZUP_COMMAND = xxxx",
"FZUP_LASTSEQ = 9999",
"FZUP_PARAM_X = ...",
"FZUP_PARAM_Y = ...",
"FZUP_PARAM_Z = ..." } );
RUBY
result = object.submit ( 
"FZUP_COMMAND" => "xxxx",
"FZUP_LASTSEQ" => "9999",
"FZUP_PARAM_X" => "...",
"FZUP_PARAM_Y" => "...",
"FZUP_PARAM_Z" => "..." )
PERL
my $result = $object->submit ( 
"FZUP_COMMAND = xxxx",
"FZUP_LASTSEQ = 9999",
"FZUP_PARAM_X = ...",
"FZUP_PARAM_Y = ...",
"FZUP_PARAM_Z = ..." );
PYTHON
result = object.submit([ 
"FZUP_COMMAND = xxxx",
"FZUP_LASTSEQ = 9999",
"FZUP_PARAM_X = ...",
"FZUP_PARAM_Y = ...",
"FZUP_PARAM_Z = ..."])
C# .NET
parameters.FZUP_COMMAND = "xxxx";
parameters.FZUP_LASTSEQ = 9999;
parameters.X = "...";
parameters.Y = "...";
parameters.Z = "...";
result = object.submit(parameters);

The parameters may vary according to the command to be executed, but 2 of them are common to all requests, they are: FZUP_COMMAND and FZUP_LASTSEQ, described below.


FZUP_COMMAND parameter

The FZUP_COMMAND parameter contains the function name requested from the webservice. To send messages this parameter must contain the literal smsg and to verify users this parameter must contain the literal chck.


FZUP_LASTSEQ parameter

Every request sent to webservice Followzup has a sequence number starting at 1 (one) from the creation or renewal of the channel asymmetric keys.

After forwarding a request with a certain sequence number N, the next request must have the sequence N + 1.

If the application routes a request with a sequence other than N + 1, the webservice simply discards the request and returns error code 6101, along with the value of the last sequence number used.

Upon receiving the application's FZUP_LASTSEQ parameter, the API adds “1” to this parameter and forwards the request to the webservice. In case of return of the error 6101, the API extracts the value of the last sequence in the webservice response, adds “1” to that value and forwards the request again. The value of the last used sequence is kept in the object to be used in the next requests.

The FZUP_LASTSEQ parameter is optional because the API saves the sequence value of the last request on the instantiated object, unless the object has been disposed by the environment.



Return of the submit method

The submit method returns an array of strings with 3 elements, containing:

Return code The return code of the request, the value “0” (zero) for successfully executed requests and the value “NNNN” containing the execution error code. Code 6101 is not returned to the application because it is handled by the API.
Sequence number Integer value containing the sequence number used in the request.
Request response XML The string containing the request response XML. The content of this XML depends on the type of command requested (smsg or chck).

The other return codes of the request, which vary according to the type of error found, must be handled by the application.

It is important that the sequence number used in the last request be stored in the application database, in case the instantiated object has been discarded by the environment. In this way, the last sequence can be informed to the API at the next request and prevent the API from receiving 6101 error codes, forcing requests to be rescheduled and increasing requests response time.



Example of use

Let's say a website administrator wants to receive an alert message on the mobile phone every time someone access the “Contact us” page. Below, the HTML form in the script contact.php, that implements the contact page.

contact.php...

echo '<form method="post" action="/gocontact.php">
         <input type="text" name="contact_name"><br>
         <input type="text" name="contact_email"><br>
         <textarea name="contact_text"></textarea><br>
         <input type="submit" value="Submit">
      </form>';


Next, the command lines in the contact form's handling routine, to send the alert message to the administrator of the website.

gocontact.php...

include ("fzup_xxxxxxxxxxxx.php");
$obj = new fzup_xxxxxxxxxxxx;

$name  = $_POST['contact_name'];
$email = $_POST['contact_email'];
$text  = $_POST['contact_text'];

$alert = "Message from $name ($email): $text";

$res = $obj -> submit ( array ( "FZUP_COMMAND = smsg",
                                "FZUP_USER    = admin@website.com",
                                "FZUP_MSGTEXT = $alert" ) );


en-030-api-usage.txt · Last modified: 2017/06/27 20:56 by admin

Page Tools