Voice and Text Chatbot designed for WhatsApp and Telegram

Instructions for Running Locally Telegram Bot Application

To execute the Telegram Bot application on your local machine, kindly follow the subsections below in the specified order.

Necessary Components

To locally run the app successfully, please ensure that you have these components ready:

• Telegram Bot API key and Telegram account
  • The API key is required for connecting the web app to Telegram. You can get more information on how to create a new bot account with BotFather here.
    The account is required to test the bot after the deployment.
• IBM Cloud account (credit card required; no payment - all used services are free)
  Create an instance for the free versions of the following services (you can select Dallas as the location):
  • Speech-to-Text
  • Text-to-Speech
  • Watson Assistant (please see the section Watson Services)
  • Object Storage
  • Cloudant
• ngrok downloaded and installed
  • Also, a free ngrok account

ngrok

ngrok is a third-party software that can be used to expose "local servers to the public internet over secure tunnels" (ngrok documentation). Basically, ngrok provides a random public url that can forward requests to a local host.

Environment Set-up

After acquiring the necessary components and cloning our GitHub repository, you would need to create a Python 3 virtual environment (using virtualenv for example), and install the dependencies. Below you can see how to do these steps:

In the project local folder in your computer:
• Creating the virtual environment:
  • Mac/Linux/Windows $ python3 -m venv <name_of_virtualenv>
• Activating the virtual environment:
  • Mac/Linux (bash/zsh) - $ source <venv>/bin/activate
  • Windows (cmd.exe) - C:\> <venv>\Scripts\activate.bat
  • Windows (PowerShell) - PS C:\> <venv>\Scripts\Activate.ps1
• Installing the dependencies:
  • Should work on Windows - $ pip install -r requirements_windows_local.txt
  • Should work on Mac - $ python3 -m pip install -r requirements.txt

In the src directory, you should also create a .env file. This will store the API keys and the code will search for them.

• Mac/Linux - $ touch .env
• Windows - $ type nul > your_file.txt

In the .env file, you can store API keys with these exact names. We do this to protect sensitive information, namely, API keys and other IDs. STT, TTS, Watson Assistant, COS and Cloudant API keys can be found on the IBM Cloud website (by going to Resource List and then opening each service). For the Watson Assistant ID, you first have to launch Watson Assistant (this can be done from the resource list) and create an assistant. After that, under Assistant Settings the assistant ID will be there.

These are the API keys that you will need to run the app:

• COS_API_KEY_ID ¹
• COS_BUCKET_LINK ¹
• COS_BUCKET ¹
• COS_ENDPOINT ¹
• COS_INSTANCE_CRN ¹
• IBM_CLOUDANT_APIKEY ¹
• IBM_CLOUDANT_DATABASE ¹
• IBM_CLOUDANT_URL ¹
• STT_API_KEY ²
• STT_LANGUAGE ²
• STT_MODEL ²
• STT_SERVICE_URL ²
• TELEGRAM_BOT_TOKEN ³
• TELEGRAM_PORT ³
• TELEGRAM_WEBHOOK_URL ³
• TTS_API_KEY ²
• TTS_DEFAULT_VOICE ²
• TTS_SERVICE_URL ²
• WA_API_KEY ²
• WA_DEFAULT_ERROR_MESSAGE ²
• WA_ID ²
• WA_SERVICE_URL ²

¹Refer to Data Storage page
²Refer to Watson Services page
³The Bot Token is given by BotFather when creating a new bot (refer here).
The TELEGRAM_PORT value is the port that the deployed app listen for incoming connections, by default is 8080.
The TELEGRAM_WEBHOOK_URL is your web application main address, with a backslash in the end.

The following image is an example of how the .env file should be formatted - without the variables values, of course:

Running the App

First, run the command for your respective OS on the command line (in the folder ngrok were installed):

• Mac/Linux - $ ./ngrok http 8080
• Windows - $ ngrok http 8080

After this, an ngrok interface, similar to this, should appear:

There would be two "Forwarding" sections of the interface - you can copy the https://____.ngrok.io/ url, and store this as TELEGRAM_WEBHOOK_URL in your .env file.

After this is done you are prepared to run the app and send messages.

It is time to run the application. In the src/ folder:

• Mac/Linux/Windows $ python3 telegram_bot.py

Congratulations! The application is ready to receive requests. You now should be able to interact with the bot on Telegram. Yeeey!

You can monitor bot activity through Cloudant database and access the media files sent and received by the bot in the Cloud Object Storage bucket you create.

Of course, there should also be a working Watson Assistant dialog skill attached to your Watson Assistant assistant (that correlates with WATSON_ASSISTANT_ID) in order for you to receive sensible responses from the app.

Handling Errors

The code has try-except blocks in many places, so as to catch specific errors from the services. Most errors should produce a debug output within the terminal.