Voice and Text Chatbot designed for WhatsApp and Telegram

Instructions for Deploying the WhatsApp Bot Web App to IBM Cloud Code Engine

In this tutorial you will learn how to deploy the WhatsApp Bot web app to IBM Cloud Code Engine. To ensure successful deployment of the application, please follow the subsections below in the specified order.

Reminder: Deploying to IBM Cloud is a suggestion. You may deploy this application on any cloud application platform using either the source code or the Docker image generated in this tutorial.

IBM Cloud Code Engine Overview

Code Engine (CE) is a PaaS (Platform as a Service) to deploy web applications to the cloud with ease and without the need to manage the underlying infrastructure. Code Engine automatically scales applications based on demand and provides built-in integrations with other IBM Cloud services. Code Engine has a free usage amount that should let us deploy the chatbot for testing purposes.

This tutorial will take you through the deployment process, which will be done mostly with the IBM Cloud CLI (Command Line Interface). For more information you can visit the official CE documentation and the documentation for CE plugin in IBM Cloud CLI.

Necessary Components

To proceed in this tutorial, kindly ensure that you have the following components:

• WhatsApp account
  • For testing the bot after the deployment.
• Twilio account (no credit card needed; comes with 15 USD credit)

  • We have curated a page which contains detailed instructions on the process of creating a Twilio Sandbox. To access the page, kindly follow this link.

• 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
• Container Registry
• Code Engine
• IBM Cloud CLI installed


• Docker Desktop (or Podman Desktop) installed

Environment Set-up

Cloning this repository should take care of the files and folders set-up. Locally, you need to create a virtual environment (venv), install the requirements, and set up a .env file in the folder src/.

This is how you can create a venv, activate, and install the requirements:

In the project local folder in your computer:
• Creating the virtual environment:
  • Mac/Linux/Windows $ python3 -m venv <name_of_virtualenv>
• Installing the requirements:
  • $ pip install -r requirements.txt

To create and set up the .env file, you can use VS Code or your favorite terminal text editor. We will need these environment variables to build the Docker Image and deploy the app:

• TWILIO_ACCOUNT_SID ¹
• TWILIO_AUTH_TOKEN ¹
• TWILIO_SANDBOX_NUMBER ²
• WA_API_KEY ³
• WA_ID ³
• WA_SERVICE_URL ³
• COS_API_KEY_ID ⁴
• COS_BUCKET ⁴
• COS_BUCKET_LINK ⁴
• COS_ENDPOINT ⁴
• COS_INSTANCE_CRN ⁴
• IBM_CLOUDANT_URL ⁴
• IBM_CLOUDANT_APIKEY ⁴
• IBM_CLOUDANT_DATABASE ⁴
• STT_API_KEY ³
• STT_SERVICE_URL ³
• STT_MODEL ³
• TTS_API_KEY ³
• TTS_DEFAULT_VOICE ³
• TTS_SERVICE_URL ³
• DEFAULT_ERROR_MESSAGE ⁵

¹Avaliable on Twilio Console
²Avaliable on Twilio Sandbox Settings
³Refer to Watson Services page
⁴Refer to Data Storage page
⁵A default message for reply to media unsupported. Spaces must be replaced by an underscore.

We have curated a page which contains detailed instructions on the process of creating a Twilio Sandbox account and obtaining the essential API keys. To access the page, kindly follow this link.

The following image is an example of how the .env file should be formatted:

Deploying the App

The following content will walk through deploying the app using the CLI. It is loosely based on this tutorial. To facilitate the distribution of the application and it's deployment to Code Engine, it is strongly recommended to containerize the application source code together with all of the related configuration files, libraries, and dependencies required for it to run. Access this IBM page to find more information about containerization.

The first thing to do when you want to generate a image of an application is to choose the tool that you will use to do it. There are many container runtime tools like Docker and Podman. In this tutorial we will going to use Docker.

Docker Overview

Docker is a platform for "developing, shipping, and running applications." (Docker documentation). Docker containers give the ability to package an application and share it with others, without needing too much work on setting up environments. Containers can also run on a variety of environments, making it suitable for quickly deploying the chatbot on the cloud.

Verifying the Dockerfile configuration

Before proceeding, please ensure that the dockerfile is configured to run the Python application for WhatsApp as depicted in the image below. If the command line that runs the WhatsApp application is commented out, please uncomment it and comment out the command line that runs the Telegram application.

Building the Docker Image and pushing it to IBM Cloud Container Registry

With the previous steps being concluded successfully, open the terminal in the project main folder and execute the following commands:

• Login into IBM Cloud
  $ ibmcloud login
That may fail. If it does, you can use $ ibmcloud login --sso.
Follow the steps, obtain the passcode, and login. If a region is requested, select us-south (Dallas).


• Set the IBM Cloud resource group
$ ibmcloud target -g Default
This command set the resource group to Default.
To see all resource groups avaliable, use ibmcloud resources


• Login into IBM Cloud Container Registry (CR)
  $ ibmcloud cr login
If the Container Registry plugin is not installed, please run ibmcloud plugin install cr.
Keep the registry address. If you selected us-south, the registry address is us.icr.io


• Choose a name for your CR namespace and create that namespace.
  $ ibmcloud cr namespace-add <my-namespace>
Please be sure to choose a unique name for the namespace in the region.


• Keep the <image-link>:
  <registry-address>/<my-namespace>/<my-repository>:<my-tag>


• Build the Docker Image
  $ docker build --tag <image-link> .
To avoid overwriting, the repository title should be unique in the namespace, as the tag.


• Push the Image
  $ docker push <image-link>

Done! Now you are ready to deploy the web application to Code Engine.

Creating the app

Once we logged on IBM Cloud CLI previously, these are the main steps to deploying the app to CE:

• Create a project on Code Engine to store the application
$ ibmcloud ce proj create -name <proj-name>
The name of the project must have 128 characters or less and must consist of alphanumeric characters, '-', ':', '_' or '.'


• Create an IBM Cloud API Key using the command line interface and save as .txt
$ ibmcloud iam api-key-create <api_key_name> --file <file_name_to_save.txt>


• Open the .txt file and copy the apikey value from the json.


• Select the working project on Code Engine
$ ibmcloud ce proj select -name <proj-name>


• Create the Registry access on Code Engine
$ ibmcloud ce registry create --name <registry-access> --server <registry-address> --username iamapikey --password <paste apikey>
This step enables Code Engine to access the private image that was stored at Container Registry.
The registry name must consist of lower case alphanumeric characters, '-' and must start and end with an alphanumeric character.


• Create the application on Code Engine
$ ibmcloud ce app create --n <app-name> --image <image-link> --registry-secret <registry-access>


• Get the application link
$ ibmcloud ce app get -n <app-name> -output url

Congratulations! You have deployed the application to cloud!
Ps: This process can be made by IBM Cloud console if you prefer.

Configuring Twilio Sandbox and testing the bot

After completing the previous steps, we shall now proceed with configuring the Twilio Sandbox and testing the bot. For this, open up Twilio console.

Then navigate to your WhatsApp Sandbox settings:

1. Messaging
2. Settings
3. WhatsApp sandbox settings

You should be able to see a screen just like this one:

Then you should copy and paste your ngrok url in the box "WHEN A MESSAGE COMES IN". Append the path "/chatbot-message" to your url too - so the final url that goes in that box should be similar to https://<app-name>.____.us-south.codeengine.appdomain.cloud/chatbot-message. All other settings can be left as the default.

To interact with the bot, send the Sandbox code from an WhatsApp account to the Sandbox number, avaliable in the same page you paste the application URL. Then, start talking to the machine by texting or recording a "Hi" or "Hey".

After this is done, you now should be able to interact with the bot on WhatsApp. 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. You can also view a reduced version of the conversation history in the Twilio Console, going to the Overview page (Messaging -> Overview), under "Recent Messages".

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.

Note: The deployment can be made by IBM Cloud console, if you prefer.

Handling Errors

In case of any problem with the deployed application, first stop the Code Engine application, then run it again. You can check the application logs in your terminal, as this tutorial shows, to verify if any exception was raised or error occurred.

The code has try-except blocks in many places, so as to catch Twilio and Flask specific errors. Most errors should produce a debug output within the terminal. Some errors might be visible from the Twilio console, and Twilio might email you when errors occur.