Botify

Owned by Product Knowledge
Last updated: Sept 16, 2024
8 min read

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.

Automatic closing of interactions

There is a system of automatic closing of interactions: every hour a check is made on the pending interactions within each of the bots, if one of these interactions has the last message older than 24 hours the interaction will be closed and written to the database as terminated in 'timeout'.
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

https://app.guidde.com/share/playbooks/kjeDUMNfH65CUfQ5RuqdXV?origin=3wPlti10dEfOGQjG7BKQvB2q4IC3

 

 

Example of Botify flow for user:

Example of Botify usage for user.mp4

Example of Botify flow with redirect to a queue:

example of botify sending conversation to the queue.mp4

 

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

  • 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)

  • 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)

    • All templates must be created by choosing the Meta Provider

  • 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}}”

      • If 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:

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.

  • Time to live: 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.

  • 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

  • Default: enable this option if you want to use this bot for inbound interactions

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, Template, List, Buttons, Gotoif or Api

For Openchannel and Chat Channels, template and button types don’t exist, while list type does not show the options, but you have to list them within the text

  • Retry: number of retry

  • Time to live: 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

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. As mentioned, the log files are organized by component and by type, and can be of four types:

  • Component-combined.log: includes the list of all the complete logs for that component

  • Component-combined.date.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, meaning that after 30 days the oldest logs will be deleted.

  • Component-error.log includes the list of all the error logs for that component.

  • Component-error.date.log: these files gather the log details related to the 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.