What’s about

Botify plugin makes it possible to build a bot flow simply and intuitively for the WhatsApp, Open Channel, Chat channels. 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:

Open

Example of Botify flow with redirect to a queue:

Open

 

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.

Open

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

For more clarity, see the following image:

Open

Requirements for Chat Channel

For more clarity, see the following image:

Open

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

For more clarity, see the following image:

Open

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'.

Open

BOTS configuration

To create a new bot click on symbol “+” then this window will open and you can fill in the fields:

Open

 

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

Open

• 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

Open

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

Open

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.

Open

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:

Open

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

Open

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.

Open

You can also check logs, by opening var/log/xcally/botify and explore botify_backend.log file