/
Botify

Botify

Overview

Botify plugin facilitates seamless interactions via WhatsApp, Open Channel and Chat channel using a softbot. It expertly manages predefined conversation flows, ensuring smooth and efficient communication with customers.
With a predefined bot flow, Botify can automatically dispatch various types of messages.

The plugin's intelligent design allows it to dynamically adjust the conversation based on the customer's responses or the data retrieved from REST API requests.
So Botify can determine the appropriate bot to initiate and the optimal flow to follow, ensuring a responsive and tailored customer interaction experience. 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 corresponding answer.

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.

It is also 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.

Please note that a dedicated license is required to use the Botify plugin. For further details, refer to the price list or contact your sales account.

 

Video Tutorial

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

 

Benefits and target markets

  • Simplicity: effortlessly manage conversational flows within XCALLY for enhanced efficiency

  • Integration: manage basic chatbot functionalities without the need for third-party integrations

  • Efficiency: lower operational expenses while maximizing overall efficiency

Botify can be a very useful feature, applicable to different examples of target markets:

BPO

FINANCIAL INSTITUTIONS

To manage dynamic conversations based on customer responses, enabling multichannel management without complex integrations and providing analytical data to monitor performance. Botify enables scalable operations and supports agents with suggestions, improving the overall customer experience.
To simplify support for routine inquiries, scheduling appointments, and sending documents.

HEALTH CARE

E-COMMERCE

To automate appointment scheduling, improving communication with patients, conducting symptom assessments, sending medication reminders, and collecting feedback.
To provide order updates, personalized product recommendations, manage customer inquiries, engage customers with targeted promotions, recover abandoned carts, and collect feedback.

UTILITIES

HOTELLERIE

To simplify customer interactions through account management, service interruption notifications, energy efficiency tips, appointment scheduling, emergency assistance, and feedback collection.
To facilitate reservation management, manage requests, provide personalized recommendations, assist with checkin/check-out, collect feedback, and promote special offers.

Plugin Installation

To install Botify:

  1. Access the machine via ssh

  2. Run the following command with the root user to install the package for creating python virtual environments: apt-get install python3-venv

  3. Upload the Botify zip archive through the admin interface on XCALLY Motion V3, from the AppZone → Plugins section.

  4. After the upload is complete, you can find the Botify plugin row. Click on the three dots button menu and select Install plugin.

  5. Go under Plugins → Botify.

  6. In the Configuration section of the Botify plugin, enter:

    1. the URL of the server in use

    2. the 'motion apikey'

The Botify plugin is now installed, and you can proceed with the requirements check and configuration steps described below, depending on the channel you intend to use.

Botify bots configuration

To create a new bot in Botify:

  1. Go under Plugins → Botify.

  2. In the Bots section of the Botify plugin, click the + blue button

  3. Enter the below details:

  • Name: insert the bot’s name

  • Channel: select WhatsApp, Chat or Openchannel → check the requirements are met: Botify for WhatsApp Channel | Botify for Chat Channel | Botify for Open Channel

  • Fallback Message: define the message that 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: define the message that will be sent if the user has exhausted the retry number (e.g. exhausted attempts)

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

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.

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.

    • Example of button 1 configuration:

      • Text: information

      • Matches: info, more info

  1. To add or edit questions click the three-dots menu corresponding to the desired Bot and select Edit

  2. Go under Actions tab and click on “+” button

  1. Fill the below fields:

  • 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) → see here

    • Buttons – available only for WhatsApp channel (max 3 buttons)

    • Gotoif – available for all channels → see here

    • Api – available for all channels → see here

  • 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

The GotoIf 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, you can use variables previously saved during the flow, as well as variables present in API responses up to that point. Variables must be written using double curly brackets {{ }}, and dot notation can be applied to access attributes.

For example we can set:

  • Condition: {{initdata.text}} > 10

  • Exits:

    • True: the flow continues to a certain block

    • False: the flow continues to another block

API Type

Using the API block, it is possible to make API calls to perform actions or retrieve information.

The content of the API response will be accessible using the double curly bracket syntax, for example:
{{variable_name.attribute1.attribute11[2]}}

  • Use dots . to access attributes.

  • Use square brackets [] to access list items.

The API response will be stored under the name defined in the Output Variable field.
Variables can be used in all fields within this block.

Below an example of the use of the API block:

  • Type: API

  • URL: The URL invoked (https://server-IP:port/api/{{number}}/info) is dynamic and depends on the content of the variable number.

  • Request type: It is a POST type API call.

  • Headers: {“content-type”:”application/json”}

  • Body: {“text”:”{{body}}”}The body of the request consists of an object containing the key text and the value of the variable body, which corresponds to the last message written by the user.

  • Result: The result of the API call is stored in the variable result, as defined in the Output Variable field.

  • Exit: 19-{{result.createdAt}} After the execution, the flow continues to block 19.

Dynamic List

The Dynamic List is useful when the number of elements in a list may vary over time and you don’t want to adjust it manually.

For example, imagine building a booking flow: the available time or day slots change continuously. With the Dynamic List option, this is not an issue.

You can:

  1. Integrate your flow with an external data source via API requests.

  2. Use the API response inside the List block.

  3. Enable the Dynamic List option to automatically update the list elements based on the data retrieved.

Enter the below information:

  • Input Variable: the name of a variable already defined earlier in the flow (usually from an API block). The variable must be referenced using double curly brackets: {{variableName}}.

    • To access properties or sub-properties, use dot notation:
      {{variableName.property.subProperty}}.

  • Variable Content Type: the structure of the data inside your variable:

    • Array → use when the variable contains a simple list.

    • Array of Objects → use when the variable contains a list of objects.
      In this case, you must specify which object property will be used.

  • Next Page Label: the text to display for navigating to the next set of list items when there are more than 10 items (particularly useful for WhatsApp channel).

  • First Page Label: the text to display for returning to the beginning of the list items (also useful for WhatsApp channel).

Below an example of the use of the Dynamic List:

  • Input Variable: {{variableName.property.subProperty}}

  • Variable content type: array of objects

  • Object Property name: property2

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 Plugins → Botify → 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.

image-20240926-152254.png

  1. Copy your admin url from Botify Configuration e.g. plugins/botify-1122334455667/botify

  2. Add /server at the path to open the folder

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

 

Moreover if an error like this occurs:

[ERROR] app > Python backend service error: NameError: name 'scheduler' is not defined

You can do a check on server's timezone configuration. The timezone file could show a different timezone, which conflicted with Botify. Fixing the timezone file, the error should not appear.

 

If the plugin is not working, you can check whether it is active.

Navigate to Settings → System → Processes and verify in the list if the plugin is running (ONLINE label).

If not, go to App Zone → Plugins, open the plugin list, click the three-dots menu of the specific plugin, select Uninstall plugin, and then Install plugin again.

Please note that uninstalling only stops the processes; it does not remove the plugin itself, so all previously entered configurations are preserved.