LiveZilla Live Chat
EN  DE Please sign in or register Hi
If I could resume this software in one word would be amazing.
André Argolo
Show all reviews


LiveZilla Chat Bot API



Chat Bot API Information and Usage
This is the documentation for the LiveZilla Chat Bot API included from 7.0.5.0. Please read the contents of this page carefully.

While the LiveZilla Chat Bot in its standard setting is able to browse the Knowledge Base, you can use the Chat Bot API in order to perform more complex processes. The logic of the Chat Bot API needs to be placed inside a separate ChatBot script (e.g. PHP).

Each Chat Bot can have its own script which needs to be saved as an absolute URL (see Bot Account in User Management).

The Chat Bot API is supposed to exchange data between the LiveZilla server and the Chat Bot script as well as visualizing it on the user side. Each inquiry consists of two objects (REQUEST and RESPONSE) which are exchanged in JSON format via POST. The user input (REQUEST) is sent to the Chat Bot script which processes it and immediately sends the RESPONSE.

  All errors will be logged in _log/error_php.log.



Request Object (Visitor)
Request object is represented as JSON objects having the following keys:

JSON Key Type Comment Example
RequestNumberintRequests serial number starting with 00
ResponseTostringLast Response IDR7546584783
ValuestringVisitors inputHi, this is a test
BotIdstringID of Botb23d62db4063344
BotNamestringName of BotExample Bot
VisitorNamestringName of VisitorJohn
GroupIdstringID of Groupsupport
HumanAvailableboolHuman operator is availabletrue
LanguageboolVisitor Language (ISO 2letter Code)FR
Operatorsarray(operator)Operator List[operator1, operator2]
TagobjectTag from last Response{prop:value,...}

When visitors end the chat, an Exit Message with the value "[__[EXIT]__]" will be sent to your script automatically.


Operator Object
Operator object is represented as JSON objects having the following keys:

JSON Key Type Comment Example
IdstringOperator IDjohn_doe
FullnamestringName of operatorJohn Doe
Statusstring0 | 1 | 2 | 3 (Online, Busy, Offline, Away)0
Groupsarray(string)List of groups this operator is a member of["support", "tech"]






Response Object (Bot)
Response object is represented as JSON objects having the following keys:

JSON Key Type Required Comment Example
IdstringYesAlphanumeric ID, max 32 charsR7546584783
ValuestringNoGeneral response text (HTML)Hi, this is my answer
Selectarray(Button)NoButton list[button1, button2]
SearchKBboolNoSearch knowledge base and add resultsfalse
BlockboolNoBlock input fieldfalse
Actionchat | messageNoStart chat with human or leave a messagechat
OperatorstringNoAction target operator (ID)john_doe
GroupstringNoAction target group (ID)support
Dataarray(int,string)NoStore visitor information[111=>"John", 112=>"john@doe.com"]
TagobjectNoTag to be returned with next Request{prop:value,...}


Button Object
Button object is represented as JSON objects having the following keys:

JSON Key Type Required Comment Example
TitlestringYesButton title (HTML)Button 1
ReturnstringNoThe value sent back as response after click
URLstringNoURL to be opened on clickhttp://...
ScriptstringNoJavscript code to be executed on clickalert(123);
Actionchat | messageNoStart chat with human or leave a messagechat
OperatorstringNoAction target operator (ID)john_doe
GroupstringNoAction target group (ID)support




ChatBot-Script QuickStart Example

<?php
$requestObject = json_decode($_POST["livezilla_user_api_request"]);

$responseObject = array();
$responseObject["Value"] = "";
$responseObject["Id"] = rand(1111111,9999999);
$responseObject["SearchKB"] = false;

if($requestObject->RequestNumber==0)
{
    $responseObject["Select"] = array();
    $responseObject["Select"][] = array("title"=>"Enter something","return"=>"something");
    $responseObject["Select"][] = array("title"=>"Link (go to website)","url"=>"http://www.livezilla.net","return"=>"");
    $responseObject["Select"][] = array("title"=>"Run some Javascript (JS)","script"=>"alert(123);","return"=>"");
    $responseObject["Select"][] = array("title"=>"Start a Chat","action"=>"chat","operator"=>"administrator","group"=>"support");
    $responseObject["Select"][] = array("title"=>"Leave a Message","action"=>"message","group"=>"support");
    $responseObject["Value"] = "Thanks for testing me. Here's a list of options, please click something:";
}

if(!empty($responseObject["Value"]))
    echo json_encode($responseObject);
?>
        




ChatBot-Script Program-O Bot

<?php
$requestobj = json_decode($_POST["livezilla_user_api_request"]);
$responseNode = array();
$responseNode["ResponseTo"] = "";
$responseNode["Id"] = rand(1111111,9999999);
$responseNode["SearchKB"] = false;

$url = "http://api.program-o.com/v2/chatbot/?bot_id=6&say=".$requestobj->Value."&convo_id=".$requestobj->VisitorId."&format=json";
$sdata = json_decode(file_get_contents($url));
$responseNode["Value"] = $sdata->botsay;

if(!empty($responseNode["Value"]))
	echo json_encode($responseNode);
?>
        




ChatBot-Script Pizza Bot

<?php
$requestobj = json_decode($_POST["livezilla_user_api_request"]);

$responseNode = array();
$responseNode["Value"] = "";
$responseNode["ResponseTo"] = "";
$responseNode["SearchKB"] = false;

if($requestobj->Value != "[__[EXIT]__]")
{
    // first user interaction
    if($requestobj->ResponseTo == "")
    {
        // store initial question
        $responseNode["Data"] = array();
        $responseNode["Data"]["114"] = $requestobj->Value;

        $responseNode["Id"] = "action:request_name";
        $responseNode["Value"] = "Ok. What's your name please?";
    }

    // user defines name
    if($requestobj->ResponseTo == "action:request_name")
    {
        $responseNode["Id"] = "action:request_pizza_type";
        $responseNode["Value"] = "Great, nice to meet you <b>" . $requestobj->Value . "</b>.";
        $responseNode["Value"] .= "What size do you like your Pizza?<br><br>";

        // store name
        $responseNode["Data"]["111"] = $requestobj->Value;
        $responseNode["Data"] = array();

        $responseNode["Select"] = array();
        $responseNode["Select"][] = array("title"=>"Medium - 10\" / 25 cm.","return"=>"Medium");
        $responseNode["Select"][] = array("title"=>"Italian - 12\" / 30 cm.","return"=>"Italian");
        $responseNode["Select"][] = array("title"=>"Large - 14\" / 35 cm.","return"=>"Large");

        // block input field
        $responseNode["Block"] = true;
    }

    // user defines pizza style
    if($requestobj->ResponseTo == "action:request_pizza_type")
    {
        $responseNode["Id"] = "action:request_customer_number";
        $responseNode["Value"] = "Your Pizza will be " . $requestobj->Value . " style. All saved!";
        $responseNode["Value"] .= "Your customer number would be helpful, too. Do you have one?<br><br>";

        // store pizza type (represents custom combobox field 0)
        $responseNode["Data"] = array();
        $responseNode["Data"]["0"] = $requestobj->Value;

        $responseNode["Select"] = array();
        $responseNode["Select"][] = array("title"=>"Yes","return"=>"Yes");
        $responseNode["Select"][] = array("title"=>"No","return"=>"No");

        // block input field
        $responseNode["Block"] = true;
    }

    if($requestobj->ResponseTo == "action:request_customer_number")
    {
        // and so on ...
        $responseNode["Value"] = "This demo ends here ...";
        $responseNode["Block"] = false;
    }
}
else
{
    // say good bye
    $responseNode["Id"] = "action:end_chat";
    $responseNode["Value"] = "Take care, bye!";
}
echo json_encode($responseNode);
?>

        





Something missing?


If you find anything missing please let us know and we will add the missing structures right away. Thanks.