This is a Starter Kit (SK), which is designed to get you up and running quickly with a common industry pattern, and to provide information and best practices around Watson services and bots. This application demonstrates how the Conversation service can be used with different bot kits such as those from Facebook and Twilio to enable users to have an intuitive and natural conversation with the bots. This use case for this starter kit is around discussing the weather. The starter kit uses the WeatherInsights service to gather weather data and provide forecasts.
A running instance of the application in this Starter Kit is available as a demo. The demo does not include Facebook or Twilio integration. Running the application using the Facebook and Twilio bots requires credentials to access their services. For information about obtaining credentials and integrating Twilio and Facebook bots, see Installing the bots.
Table of Contents
- Getting Started
- About the Weather conversation pattern
- Adapting/Extending the Starter Kit
- Best Practices
Creating a [IBM Bluemix][bluemix] Account
- Go to https://bluemix.net/
- Create a Bluemix account if required.
- Log in with your IBM ID (the ID used to create your Bluemix account)
Note: The confirmation email from Bluemix mail take up to 1 hour.
Deploy this sample application in Bluemix
Clone the repository into your computer and navigate to the new directory
git clone https://github.com/watson-developer-cloud/text-bot.git cd text-bot
Sign up in Bluemix or use an existing account.
- If it is not already installed on your system, download and install the Cloud-foundry CLI tool.
manifest.ymlfile in the folder that contains your code and replace
text-botwith a unique name for your application. The name that you specify determines the application's URL, such as
your-application-name.mybluemix.net. The relevant portion of the
manifest.ymlfile looks like the following:
declared-services: conversation-service: label: conversation plan: free weatherinsights-service: label: weatherinsights plan: Free-v2 cloudantNoSQLDB-service: label: cloudantNoSQLDB plan: Lite applications: - services: - conversation-service - weatherinsights-service - cloudantNoSQLDB-service name: text-bot command: npm start path: . memory: 512M
Connect to Bluemix by running the following commands in a terminal window:
cf api https://api.ng.bluemix.net cf login
Create and retrieve service keys to access the Conversation service by running the following command:
cf create-service conversation free conversation-service cf create-service-key conversation-service myKey cf service-key conversation-service myKey
Create and retrieve an API key to access the Alchemy Language service (if you already have instance skip this step) by running the following command:
cf create-service alchemy_api free alchemy-language-service cf create-service-key alchemy-language-service myKey cf service-key alchemy-language-service myKey
Create and retrieve service keys to access the Weather Insights service by running the following command:
cf create-service weatherinsights Free-v2 weatherinsights-service cf create-service-key weatherinsights-service myKey cf service-key weatherinsights-service myKey
Create an instance of the Cloudant NoSQL database service by running the following command:
cf create-service cloudantNoSQLDB Lite cloudantNoSQLDB-service cf create-service-key cloudantNoSQLDB-service myKey cf service-key cloudantNoSQLDB-service myKey
The Conversation service must be trained before you can successfully use this application. The training data is provided in the file
resources/conversation-training-data.json. To train the model used by the Conversation service, do the following:
Login to Bluemix
Navigate to upper left hand side and click on the 3 parallel lines and select Dashboard from the left hand navigation panel.
Scroll down and under "All Services" - select the instance of the Conversation service that you are using
Once on the Service details page, scroll down (if necessary) and click green Launch tool button on the right hand side of the page. (You may be asked to log in again. or you may see a blank screen - give it a few minutes and refresh the screen). This will launch the tooling for the Conversation service, which allows you to build dialog flows and train your chatbot. This should take you to your workspace in the Conversation service which represents a unique set of chat flows and training examples. This allows you to have multiple chatbots within a single instance of the Conversation service.
Once on the page, you will see the option to either “Create” a new workspace, or “import” an existing one. We are going to “import” a premade chatbot for this example, so select “Import".
Click Choose a file, navigate to the
resourcesdirectory of your clone of the repository for this project, and select the file
conversation-training-data.json. Once the file is selected, ensure that the “Everything (Intents, Entities, and Dialog” option is selected.
Click Import to upload the
.jsonfile to create a workspace and train the model used by the Conversation service.
To find your workspace ID once training has completed, click the three vertical dots in the upper right-hand corner of the Workspace pane, and select View details. Once the upload is complete, you will see a new workspace called “Weather Bot ASK”. In order to connect this workspace to our application, we will need to include the Workspace ID in our environment variables file “.env”.
Go back into your “.env” file, and paste the workspace ID next to the “WORKSPACE_ID=” entry.
.envfile in the root directory of your clone of the project repository by copying the sample
.env.examplefile using the following command:
cp .env.example .env
You will update the
.envwith the information you retrieved in steps 6 - 9.
.envfile will look something like the following:
USE_WEBUI=true ALCHEMY_API_KEY= #CONVERSATION CONVERSATION_URL=https://gateway.watsonplatform.net/conversation/api CONVERSATION_USERNAME= CONVERSATION_PASSWORD= WORKSPACE_ID= #WEATHER WEATHER_URL=https://twcservice.mybluemix.net/api/weather WEATHER_USERNAME= WEATHER_PASSWORD= #CLOUDANT CLOUDANT_URL= #FACEBOOK USE_FACEBOOK=false FACEBOOK_ACCESS_TOKEN= FACEBOOK_VERIFY_TOKEN= #TWILIO USE_TWILIO=false USE_TWILIO_SMS=false TWILIO_ACCOUNT_SID= TWILIO_AUTH_TOKEN= TWILIO_API_KEY= TWILIO_API_SECRET= TWILIO_IPM_SERVICE_SID= TWILIO_NUMBER=
Install the dependencies you application need:
- Start the application locally:
- Test your application by going to: http://localhost:3000/
Installing the bots
.envfile to add credentials for Facebook and Twilio. See the following links for information about where you can get the credentials required by the botkit for each service:
If you are integrating with Twilio, set the
USE_TWILIO_SMSvariables in your
true. If you are integrating with Facebook, set the
USE_FACEBOOKvariable in your
Modify the file
lib/bot/bot.jsto include your own bot handling code. If you would like to use a separate bot messaging service (such as
converse.ai, and so on ), you can add the middleware to each bot instance that you'd like for that service to use, and configure it with the single
Deploying your Bot to Bluemix
Push the updated application live by running the following command:
After completing the steps above, you are ready to test your application. Start a browser and enter the URL of your application.
<your application name>.mybluemix.net
You can also find your application name when you click on your application in Bluemix.
Begin entering questions such as “what is the weather for Austin, Texas?” If you don’t enter a state, it will ask you to clarify what state.
Debugging the application
To debug the application, go to
https://text-bot.mybluemix.net/debug.html to see a panel that shows metadata which contains details on the interaction with the services being used.
You have completed the instructions to create and configure the Text Bot!
About the Weather Conversation pattern
This Starter Kit uses weather information from the WeatherInsights service to demonstrate how to integrate a bot with the Conversation service available on Bluemix. It provides extension points for integration botkits from vendors such as Facebook and Twilio.
For a given input (e.g. question about weather in Austin, TX) , a trained Conversation service instance responds with weather forecast. The service is composed of a model trained with a set of intents and entities (in this case, the intent is to get the forecast and the entities are cities that the user might want to know the forecast for). The dialog agent of the Conversation service is responsible for interacting with the user and keeping track of the context of the conversation so that it can provide answers to follow up questions about the same topic.
Adapting/Extending the Starter Kit
The following image provides a general overview of how botkits from external services can interact with Watson services.
This Starter Kit uses weather data from the WeatherInsights service and can easily be extended to integrate with botkits from vendors such as Facebook and Twilio. However, the concepts used here are platform independent and can be applied to a use cases other than providing forecasts. To do so, define your use case in the Conversation service, configuring your Conversation by using the tool provided on the dashboard page for your instance of the Conversation service. You can also integrate other bots as mentioned on the Installing the bots section.
The following links provide more information about the Conversation, WeatherInsights, and Alchemy Language services.
- API documentation: Get an in-depth knowledge of the Conversation service
- API reference: SDK code examples and reference
- API Explorer: Try out the API
- Creating your own conversation service instance: How to use the API to create and use your own classifier
- API documentation: Get an in-depth understanding of the Weather Insights services
- API reference: Code examples and reference
- API Explorer: Try out the REST API
- API documentation: Get an in-depth understanding of the AlchemyAPI services
- AlchemyData News reference: API and query gallery
- API documentation: Get an in-depth understanding of the Cloudant services
- API reference: Code examples and reference
Most of the best practices associated with writing a conversational application are explained within the documentation for the Conversation service. These can be grouped into several general areas, as described in the next few sections.
- When defining intents, follow naming conventions to create consistent intents.
- Use "-" to separate multiple levels (Example : location-weather-forecast)
- Use "_" to separate multiple word intents (Example : business_center)
- Provide more variations of input via examples for each intent. The more variations the better.
- Avoid overlapping intents across examples. (Example : benefits_eligibility and benefits_elgibility_employee). To avoid this, group examples into a single intent and use entities to deal with subtle variations.
- Examples for intents should be representative of end user input
- Use entities from within the conversation tooling when dealing with a concise and well-defined set of entities (Example : days of the week). Refer to Entities section within the Watson Conversation Service documentation.
- Use synonyms to capture variations of the entity. This may include acronyms, abbreviations, multi-word variations.
- Use Alchemy Entity Extraction API to provide a more open set of entities (Examples : City names). For a more advanced cases or special domains, it may be necessary to create a custom model which is beyond the scope of this starter kit.
- Use context variables to maintain state or pass information between your bot and the application. Refer to Context variables section within the Watson Conversation Service Documentation.
- Use the Bot controller (controller.js) to maintain calls to external APIs such as Weather, Stocks or to enterprise systems such as HR, Payroll or CRM systems.
To troubleshoot your Bluemix application, use the logs. To see the logs, run:
cf logs <application-name> --recent
This sample application implements fairly narrow use cases. Abbreviations for cities are generally not supported - you will need to specify the full name of your city and state.
You may notice that the demo becomes unresponsive when you use the word "in" within a question, such as "What is the weather in Boston?". This simple application is designed to help you get started, and therefore does not implement detailed error checking or sophisticated question parsing.
This sample code is licensed under Apache 2.0. Full license text is available in LICENSE.
Open Source @ IBM
Find more open source projects on the IBM GitHub Page
This node sample web application includes code to track deployments to Bluemix and other Cloud Foundry platforms. The following information is sent to a Deployment Tracker service on each deployment:
- Application Name (
- Space ID (
- Application Version (
- Application URIs (
This data is collected from the
VCAP_APPLICATION environment variable in IBM Bluemix and other Cloud Foundry platforms. This data is used by IBM to track metrics around deployments of sample applications to IBM Bluemix. Only deployments of sample applications that include code to ping the Deployment Tracker service will be tracked.
Disabling Deployment Tracking
Deployment tracking can be disabled by removing
require('cf-deployment-tracker-client').track(); from the beginning of the
server.js file at the root of this repository.