Botify
- Product Knowledge
What’s about
Botify plugin makes it possible to build a bot flow simply and intuitively for the WhatsApp channel (it will be available soon for the other text channels as well). It allows inbound and outbound flows to be managed. Flow addressing does not use AI and there is no natural language recognition, an exact match is made with what the user is going to write. For example, given a question with the answer 'yes' or 'no' the user will be able to choose the two buttons, but if other trigger words or phrases are configured, the user will be directed to the stream of the answer 'yes' even if the user writes 'exact', 'OK' or other phrases or words previously configured by the user.
With Botify, you start from a templateid to which customer answers: e.g. with an outbound campaign, a template is sent → customer answers → the system checks the used templateid → corresponding bot is executed.
The plugin allows interaction with third-party systems using API requests to perform actions or obtain information. So for example calling an API the flow can continue on one direction or the other.
It is possible to return an output variable to the bot so that actions can be performed based on this value. For example, it is possible to make the bot return the name of the queue, in this way, it will be possible to transfer the customer, who followed a specific question stream, to a specific queue.
Video Tutorial
Example of Botify flow for user:
Example of Botify flow with redirect to a queue:
Software installation
First, it is necessary to access the machine via ssh and run the following command with the root user to install the package for creating python virtual environments:
apt-get install python3-venv
The software is executed in the form of an XCALLY plugin, so it’s distributed as a zip archive to be installed directly through the admin interface on XCALLY Motion V3, from the AppZone → Plugins section.
Once the plugin installation file has been loaded, you can proceed with the installation. Then you can configure and create all the elements required by this plugin
Requirements for WhatsApp Channel
WhatsApp Connector Inbound and Outbound enabled
Plugin enabled on license
Configuration of a WhatsApp Account (it is also possible to create more bots for the same account)
For the WhatsApp channel, Botify supports as providers Meta and Kaylera
Creation of at least one WhatsApp template if you want to use the bot in outbound mode
Discover how to create a WhatsApp template and remember that all templates must be created as Recontact Template (you can switch on this option when creating a template and you can change it after creating it)
Configuration of actions for WhatsApp Account by editing the desired WhatsApp Account and setting Actions tab
Drag and drop the System application and insert the command:
curl "curl "http://localhost:5001/api/notify_get?channel=whatsapp&botId=&id=""{{message.id}}”
Port 5001 is the standard one, if it is already in use you can change it by entering its number also in the configuration to work correctlyIf you want to specify the bot id to be used, just enter the bot id after "botId=", e.g. curl "http://localhost:5001/api/notify_get?channel=whatsapp&botId=3&id=""{{message.id}}"
Choose a variable, so any bot output response will be saved inside the chosen variable
To use the response provided by the bot, use the JSON.parse() function applied to "{{YOUR_VARIABLE_NAME}}", and access the returnedValue attribute. In the image below, the variabl used is RESULT and the condition is as follows:
JSON.parse('{{RESULT}}').returnedValue === "Support" (So in that case the system exits from bot and passes to a specific queue → botify exits with the value indicated in action flow).To close the interaction use a gotoif application (as in the picture, the line with priority 6) with the following string: 'JSON.parse('{{RESULT}}').status=== "managed"'. Use the same variable that was used to save the output of the system application, in this example is RESULT. If the condition is true, choose the next priority of the current application if it is false, set the priority of the application to the final gotop. Now enter the close application and type the disposition you prefer.
At the end, drag and drop the Gotop application and set Priority to 99
For more clarity, see the following image:
Requirements for Chat Channel
Configure a Chat Website
Create at least one Bot for Chat or Open Channel, see Bots configuration Section
Configure actions for the Chat Website, by editing the chat website actions tab:
Drag and drop the System application and insert the command:
curl "curl "http://localhost:5001/api/notify_get?channel=chat&botId=value&id=""{{http://message.id}}"for the chat channel and OpenChannel it is mandatory to specify the bot id to be used: replace ‘value’ with the id of the bot you wish to use
Choose a variable, so any bot output response will be saved inside the chosen variable
To use the response provided by the bot, use the JSON.parse() function applied to "{{YOUR_VARIABLE_NAME}}", and access the returnedValue attribute. In the image below, the variable used is RESULT and the condition is as follows:
JSON.parse('{{RESULT}}'). returnedValue === "Sales"At the end, drag and drop the Noop application with value “noaction”
For more clarity, see the following image:
For the Chat channel, we recommend not closing the interaction via actions, as the user may not have time to read the last message of the interaction as it would be closed immediately.
Requirements for Open Channel
Configure an Open Channel Account
Create at least one Bot for Chat or Open Channel, see Bots configuration Section
Configure actions for the Open Channel, by editing the open channel account actions tab:
Drag and drop the System application and insert the command:
curl "curl "http://localhost:5001/api/notify_get?channel=chat&botId=value&id=""{{http://message.id}}"for the chat channel and OpenChannel it is mandatory to specify the bot id to be used: replace ‘value’ with the id of the bot you wish to use
Choose a variable, so any bot output response will be saved inside the chosen variable
To use the response provided by the bot, use the JSON.parse() function applied to "{{YOUR_VARIABLE_NAME}}", and access the returnedValue attribute. In the image below, the variable used is RESULT and the condition is as follows:
JSON.parse('{{RESULT}}'). returnedValue === "Sales"To close the interaction use a gotoif application (as in the picture, the line with priority 4) with the following string: 'JSON.parse('{{RESULT}}').status=== "managed" '. Use the same variable that was used to save the output of the system application, in this example is RESULT. If the condition is true, choose the next priority of the current application if it is false, set the priority of the application to the final action.
Now enter the close application and type the disposition you prefer
At the end, drag and drop the Noop application with value “noaction”
For more clarity, see the following image:
Plugin configuration
In the Configuration section of the plugin, you will need to enter the URL of the server in use and the 'motion apikey'.
BOTS configuration
To create a new bot click on symbol “+” then this window will open and you can fill in the fields:
Name: insert the bot’s name
Channel: WhatsApp, Chat or Openchannel
Fallback Message: This message will be sent if the user does not select correctly or type a trigger message (e.g. Choose one of the option)
Out of Retry message: this message will be sent if the user has exhausted the retry number (e.g. exhausted attempts)
Moreover if you select WhatsApp Channel, you also need to define:
WhatsApp Account: select the account you want to link to this bot)
WhatsApp Template:
“Outbound mode”: for a bot starting with a WhatsApp campaign, use the same template used in the campaign. It is not possible to use the same template to trigger different bots.
“Inbound mode”: do not select any template and enable the default button.
Default: enable this option if you want to use this bot for inbound interactions
Returned Value: is the value to be returned by the bot to the routing (optional). For instance, it can be used to direct chat to a queue
Session Timeout: Allows you to decide whether to enable the bot session to be considered closed after a certain number of hours. If you want to enable session closure, you can choose after how many hours since the last message was sent or received.
After choosing a button template, these options will be shown:
Text: This cannot be edited as it is a template already created and approved by Meta.
Exit: indicates the exit node, if None the bot will terminate at the current node. Clicking will show a drop-down menu where you can choose the exit node. First, you have to create the nodes and then connect them.
Matches: indicates all words or phrases that if written exactly (only upper case and lower case are irrelevant) by the user will trigger the button even if the user does not click directly on the button. The text of the button is automatically included in the matches even if not shown. For example, the word Information is already a possible match for button 1.
To add or edit questions click the three-dot symbol corresponding to the desired Bot → Edit → Actions tab → “+” button
Start: at least one question must be a start
Type:
Text – available for all channels
Template – available only for WhatsApp channel
List – available for all channels (with a maximum of 10 options)
Buttons – available only for WhatsApp channel (max 3 buttons)
Gotoif – available for all channels
Api – available for all channels
Retry: number of retry
Timeout Question: once this time, expressed in hours, has passed since the last message sent by the user, the interaction will be closed. If the user writes a message after the interaction has been closed, he will be directed to the inbound bot
Store: by enabling this flag, it is possible to save what the user writes to the database in the whatsapp_interaction in the field cf_text, in JSON format. It is also possible to use them within the bot using the syntax {{name.variable}}.
GotoIf Type
This block is used to route to one block or another based on the occurrence or non-occurrence of a condition:
In both the Variable and Value fields, variables previously saved during the flow or variables present in API responses to date can be used. In the case of the use of variables, the notation to be used is that of the double curly bracket and if attributes are to be accessed, the dot notation can be used. In this example if the condition is true the flow will continue to block 7 otherwise it will go to block 1.
API Type
Using this block is possibly make API calls to perform actions or receive information. the content of the API response will be accessible using the syntax with the double curly bracket: {{variable_name.attribute1.attribute11[2]}}, using dots to access the attributes and square brackets [] if there is a list. The API response will be saved with then name chosen in field Output Variable. In all fields is allowed the use of variables within them.
An example of the use of the API block is shown in the image above: the URL called is dynamic and depends on the content of the variable "number". It is a POST type API call, the body of the API call consists of an object containing the key "text" and the value of the variable "body" which is the last message written by the user. the result of the API call will be saved in the variable "result", as indicated in the "Output Variable" field, and the next block will be block 19
Dynamic List
The dynamic list is for you when in your flow the number of elements in a List can vary over time and you do not want to adjust it manually all the time. Let's say you want to create a flow to make bookings, the time or day slots available vary all the time, but thanks to the Dynamic List you will have no problem: make an integration with your data source via API requests and use the answer inside the List block and use the Dynamic List option:
Input Variable: type the name of a variable that you have already previously set, usually using an API block, in double curly brackets
remember that you need to access properties or sub-properties of a variable you can use the notation variableName.property.subProperty
Variable Content Type: specifies whether inside your variable you have an array or an array of objects
In the case of an array of objects, the name of the property to be used must be specified
Next Page Label: you can specify the name to be shown for the next list item button if there are more than 10 items (useful for whatsapp channel)
First Page Label: you can specify the name to be shown to return to the beginning of the list items (useful for whatsapp channel)
Data
For each user message, the cf_text column, string type but formatted as a json, of the whatsapp_interaction table is updated by writing the following information:
BotName: bot name
user-journey: nodes crossed by the user
variables: variables saved during the bot's flow and attributes obtained from API requests
status: chat status: “waiting”, “managed”, “noBotId”, “noQuestion”, “outOfRetryMessage”, “autoclose”, “parametersMissing”, “error”
Logs
The application stores log files for each component and/or function that is executed in the background. You can find these logs in the Log view, where you can check when a specific log is been updated, download, or delete it.
The logs allow you to check the proper functioning of the application, and to eventually check for errors.
You can find logs in folder /var/log/xcally/botify
As mentioned, the log files are organized by component and by type, and can be of four types:
<component_name>-combined.log, includes the list of all complete logs for that component;
<component_name>-combined.date.log (e.g. api-combined.2024-01-01.log) : these files gather the log details for the specified component, including both debug and error messages, and for the day specified in the date part of the name. The logs are rotated daily, meaning that you’ll have a new combined log file for each component for each day. The rotation limit is set to 30 days, so after 30 days the oldest logs will be deleted;
<component_name>-error.log, includes the list of all error logs for that component;
<component_name>-error.date.log: these files gather the log details related to errors only, and for the day specified in the date part of the name. The logs are rotated daily, meaning that you’ll have a new combined log file for each component for each day. The rotation limit is set to 30 days, meaning that after 30 days the oldest logs will be deleted.
botify_pro_backend.log: includes the complete logs for the backend service.
api_action.log: logs concerning api calls made by the bot.
Troubleshooting
In case of issues with the plugin, first of all you can check if the port inserted in the configuration is the correct one.
So you can copy your admin url from Botify Configuration e.g. plugins/botify-1122334455667/botify and add /server at the path to open the folder
Then open config.json file and you can see in botifyService the used port.
You can also check logs, by opening var/log/xcally/botify and explore botify_backend.log file