Python Automation

BotCity Maestro integration for Python bots

Follow this article or the video below to learn how to integrate your bots with the Maestro:


  • Runner: download it here.
  • BotCLI: download it here. Alternatively, Botcity’s BotStudio comes with a bundled BotCLI. The Studio can be found here.
  • You must be registered to the BotCity Maestro platform.
  • You must be able to run a bot using the Runner (see how in our previous tutorial here)


  • This article is based on Hugo Slepicka’s in-depth tutorial, which can be found here.

Step 1 – Log in to BotCity Maestro

Access the BotCity Maestro platform and log in with your credentials. Notice how you can already take a peek at the task queue from the home page, but since we want more details, click “Task Queue”, as shown in the image below:

In the Task Queue page, you’ll see a history of the tasks you executed:

If you have followed our previous tutorial, you should see your first bot execution marked as “Running”. However, you know for sure that it’s already finished. Why is that?

It is the bot developer’s responsibility to inform the BotCity Maestro via the SDK of the proper final status of a task. This allows for better control and also to add details about the task completion that can later be inspected by users via the BotCity Maestro portal.

Step 2 – Install Packages

In this tutorial, we will be adding new lines of code to our bot that requires the botcity-maestro-sdk package to be installed on your computer:

Keep in mind that, if you created your bot using BotCity’s template, this step is not necessary because it comes with the botcity-maestro-sdk package already listed in your requirements.txt file.

Step 3 – Set up the RunneStep 3 – Connecting to BotCity Maestro

Open your source code using whatever IDE or text editor you prefer:

Let’s start by adding the following import to our code:

We need to establish a connection between our code and the BotCity Maestro platform. You could do that using BotCityMaestro.login:

However, since the bot is already being executed by the Runner, there is a more convenient way. Simply use self.maestro, which is already logged in and provides the access_token you need:

Step 4 – Task Status Integration

In order to have your future tasks marked as Finished in the Task Queue, use this command at the end of your bot execution:

Notice how we are taking advantage of the fact our automation is already being executed by the Runner to obtain the task_ID from the execution parameter.

There are two other status options we could use. AutomationTaskFinishStatus.FAILED and AutomationTaskFinishStatus.PARTIALLY_COMPLETED. It’s up to the user to determine when to use each one of them, but here’s an example of the code after all those modifications:

Step 5 – Creating a Log

Knowing that a task was finished, successfully or not, is often not enough when monitoring an automation. There is some precious information collected during the process that may be useful to the user. Fortunately, It’s possible to send it to the BotCity Maestro platform by creating a log, and filling it with log entries.

To create a log, we provide the activityLabel of the activity we are creating a log for, and a list of Columns that will hold our information. We can do it like this:

Step 6 – Creating a new Log Entry

Now that our log has been created, we want to fill it with some information. As an example, we’ll collect the number of subscribers BotCity’s Youtube channel has. Here is a way to do it:

To add a new entry to our log, we invoke the method new_log_entry, which receives the activity label we have previously obtained, and an object with the values of each log field we want to fill:

Step 7 – Alerts

Alerts can be used to display a message in the BotCity Maestro platform that may be classified as an INFO, WARNING or ERROR. For example, we could set an info alert to go off if BotCity’s youtube channel meets a certain subscribers milestone:

We’ll use 100 subscribers to make sure the alert will go off. Also, keep in mind you can change the alert type to AlertType.INFO, AlertType.WARN or AlertType.ERROR.

Step 8 – Messages

It’s also possible to have your bot send a message to a list of BotCity Maestro users or to a list of external email addresses. The message body can be written in either TEXT or HTML format:

Keep in mind that the email and user list parameters are optional, so you may pass it as an empty list using []. You must provide at least one of the lists with content.

Step 9 – Artifacts

It’s possible for your bot to both download and upload files to and from BotCity Maestro.

Uploading a file only requires one line of code:

Of course, we’d first have to create the subscribers.txt file:

Step 10 – Update your automation

Here is the final version of our code:

Before testing it out, we need to provide the Runner with the new, updated version. First, we need to rebuild our package:

Then, we shall use the BotCli to upload our new package to the BotCity Maestro, so it may later be downloaded by the runner:

Step 11 – Final Test

Let’s create a new task for the runner, and see what are the results of our bot execution through the BotCity Maestro platform:

Task Queue:




Result Files:

Head of Developer Experience @ BotCity.

Leave a Reply