This repository will not be updated. The repository will be kept available in read-only mode.
Read this in other languages: 한국어.
Watson Conversation is now Watson Assistant. Although some images in this code pattern may show the service as Watson Conversation, the steps and processes will still work.
In this developer journey we will build a TJBot that knows baseball. Using Watson Discovery, TJBot will give you insight about your favorite teams, such as their current league standing, their upcoming shedule, and links to a few relevant articles from Watson News.
When the reader has completed this journey, they will understand how to:
- Build a TJBot that converses using Watson Assistant
- Use Watson Text to Speech and Speech to Text services to converse with TJBot
- Use Watson Tone Analyzer to determine your sentiment about your favorite teams
- Use Watson Discovery News to find news articles about your favorite teams
- Query 3rd party data sources to get the latest Major League Baseball (MLB) data
- Use Twilio to send SMS text messages with team schedules and news article links
Want to take your Watson app to the next level? Looking to leverage Watson Brand assets? Join the With Watson program which provides exclusive brand, marketing, and tech resources to amplify and accelerate your Watson embedded commercial solution.
- Watson Assistant: Build, test and deploy a bot or virtual agent across mobile devices, messaging platforms, or even on a physical robot.
- Watson Discovery: A cognitive search and content analytics engine for applications to identify patterns, trends, and actionable insights.
- Watson Text to Speech: Converts written text into natural sounding audio in a variety of languages and voices.
- Watson Speech to Text: A service that converts human voice into written text.
- Watson Tone Analyzer: Uses linguistic analysis to detect communication tones in written text.
- Twilio: Integrate voice, messaging, and VoIP into your web and mobile apps.
- MLB Fantasy Data: A leading provider of real time sports data and content across multiple sports, serving fantasy, media and mobile clients worldwide.
- Node.js: An asynchronous event driven JavaScript runtime, designed to build scalable applications.
This app is designed to be run on a TJBot, but it can work on any standard workstation or laptop that supports audio controls - specifically a microphone input device and an output speaker. It may be simplier to first get this working on your laptop. If you would like to go directly to building this on a TJBot, jump to the section entitled Build a TJBot before completing the following steps.
- Clone the repo
- Create IBM Cloud services
- Configure Watson Assistant
- Enable Watson Discovery
- Enable Watson Speech to Text
- Enable Watson Text to Speech
- Enable Watson Tone Analyzer
- Register for Twilio Service
- Register for MLB Fantasy Data Service
- Run the application
Clone the tjbot-sports-buddy
locally. In a terminal, run:
git clone https://github.com/ibm/tjbot-sports-buddy
We’ll be using the file data/workspace.json
Create the following services:
Launch the Watson Assistant tool. Use the import icon button on the right
Find the local version of data/workspace.json
and select
Import. Find the Workspace ID by clicking on the context menu of the new
workspace and select View details. Save this ID for later.
Optionally, to view the conversation dialog select the workspace and choose the Dialog tab, here's a snippet of the dialog:
Launch the Watson Discovery tool. Select the Watson Discovery News Collection.
From the details panel, save the environment_id and collection_id values.
Select the Watson Speech to Text service. Select the Service credentials menu item.
Click View Credentials and save the username and password values.
Select the Watson Text to Speech service. Select the Service credentials menu item.
Click View Credentials and save the username and password values.
Select the Watson Tone Analyzer service. Select the Service credentials menu item.
Click View Credentials and save the username and password values.
One of the main functions of the tjbot-sports-buddy
is to text upcoming
games and news headlines about the users favorite baseball teams. To send
SMS text messages, we use the Twilio service. Register for a free trial account at https://www.twilio.com/try-twilio.
As part of the service, you will be assigned the following values, which you will need to save, they are accessible through your user account settings:
- Account SID
- Authentication Token
Lastly, you will need a Twilio supplied phone number, where all texts will originate from. To create one, navigate to the Programmable SMS option in the context menu.
- Twilio supplied phone number
By default, you will only be able to send SMS text messages to the phone number you provided to create your account. To send messages to other numbers, you need to add them at https://www.twilio.com/console. For each number you enter, the user of the number will be asked to verify and then be sent a verification code. You will then need to enter this verification code to complete the registration process.
Another feature of the tjbot-sports-buddy
is being able to provide up to
the minute Major League Baseball (MLB) stats. Specifically, schedules and
standings. To retrieve this data, we use APIs supplied by FantasyData.
Register for a free trial account at https://developer.fantasydata.com.
Once registered, save the supplied subscription key, available through your profile.
First, copy the env.sample
file to .env
and then update the file with the credentials created in the previous steps:
cp env.sample .env
Note: Depending on the region that you provision your Watson Services, you will either be given a user/password or IAM apikey values for your credentials. The .env file will accomodate both. Just remember to comment out or remove all of the key-value pair entry lines that you do not use.
Second, install dependencies by running the following command from the cloned repo location:
npm install
NOTE: you may need to install other dependencies, refer to the Troubleshooting section below.
Lastly, run the application:
npm start
Textual version of a sample conversation with TJBot:
You: "Hello Watson"
TJBot: "Hello. I'm Watson and I love baseball. Who's your favorite team?"
You: "The Yankees"
TJBot: "The New York Yankees are currently in first place. How do you think they will do this year?"
You: "Great!"
TJBot: "I agree, if they can stay healthy"
TJBot: "Would you like me to text you the New York Yankees upcoming schedule and some headling links from Watson News?"
You: "Sure"
TJBot: "What number should I use?"
You: "One two three four five six seven eight nine ten zero"
TJBot: "Your text has been sent. Are you interested in any other teams?"
You: "No thank you"
TJBot: "OK. Have a nice day"
Here is a recap of the services used to perform this conversation:
- Watson Assistant: The conversation flow.
- Watson Speech-To-Text: Converts user input to text.
- Watson Text-To-Speech: Converts TJ Bot replies to sound.
- Watson Tone Analyzer: Determines an appropriate reply to the users sentiment about his favorite team.
- Watson Discovery: Generates headline links about the team.
- Fantasy Data: Retrieves the current standing and upcoming schedule for the team.
- Twilio: Texts team schedule and news to the user.
To build your TJBot, follow the tutorial entitled: Build a Chatbot That Cares - Part2.
It provides a comprehensive guide for:
- Raspberry Pi setup
- TJBot Carboard assembly
- Node.js setup
- Audio support and trouble-shooting
Once your TJBot is running and functional, perform steps 1-10 above to setup and run the TJBot Sports Buddy app.
You may need to install a few audio related dependencies if you're seeing the following error:
events.js:163
throw er; // Unhandled 'error' event
Use brew
to install:
- mplayer
- sox
- ffmpeg
brew install sox mplayer ffmpeg
And use NPM to install:
- node-ffprobe
npm install node-ffprobe
Use apt-get
to install:
- ffmpeg
sudo apt-get install ffmpeg
And use NPM to install:
- node-ffprobe
npm install node-ffprobe
We have seen this error on Ubuntu, and it is due to microphone issues.
The first step is to diagnose the problem. In run.js, go to the following object and modify debug
to true:
const MIC_PARAMS = {
rate: 44100,
channels: 2,
debug: true,
exitOnSilence: 6
};
If you get the error:
Received Info: arecord: main:722: audio open error: No such file or directory
Try this:
arecord -l // locate your microphone card and device number
**** List of CAPTURE Hardware Devices ****
card 0: Intel [HDA Intel], device 0: ALC262 Analog [ALC262 Analog]
Subdevices: 1/1
Subdevice #0: subdevice #0
card 0: Intel [HDA Intel], device 2: ALC262 Alt Analog [ALC262 Alt Analog]
Subdevices: 2/2
Subdevice #0: subdevice #0
Subdevice #1: subdevice #1
card 2: C320M [Plantronics C320-M], device 0: USB Audio [USB Audio]
Subdevices: 1/1
Subdevice #0: subdevice #0
Then add the card and device (hw:card,device
) number to your microphone params. For example to use the Plantronics
card above:
const MIC_PARAMS = {
rate: 44100,
channels: 2,
device: 'hw:2,0',
debug: true,
exitOnSilence: 6
};
If you get the error:
Received Info: arecord: main:722: audio open error: Device or resource busy
It means your device is being used by another process. Try the following:
- Exit any volume control applications that may be running, such as
PulseAudio
. - Exit any open browsers.
If you still get the error, reboot.
NOTE: make sure you set
debug:false
after everything is working, otherwise too many log messages will be output to the console.
This is most likely due to the baseball season being over, or your config file specifies the wrong baseball season.
If the baseball season is over (runs from early April to late September), set the following flag in config.js
:
exports.offSeason = true;
NOTE: the data returned by TJBot will come from an archived version of previous season data and and will not be accurate, but at least you will be able to interact with it.
If the baseball season isn't over, make sure the following variable is set correctly in config.js
:
exports.MLBSeason = '2017';
If you see this error:
TJBot is listening, you may speak now.
/Users/rhagarty/journeys/tjbot-sports-buddy/run.js:538
pauseDuration = probeData.format.duration + 0.2;
^
TypeError: Cannot read property 'format' of undefined
The problem is assoicated with the Text-to-Speech service. Check that:
- The credentials in your
.env
file are correct. - The service has not reached it's
character
limit for the month.
If you have run into the limit issue with your plan, simply delete and re-create a new instance of the service. And remember to update the .env file with your new credentials.
Ensure that the basic microphone functionality is working:
sox -d test.wav // speak into mic, then ctrl-c to exit
sox test.wav -d // playback
This code pattern is licensed under the Apache Software License, Version 2. Separate third party code objects invoked within this code pattern are licensed by their respective providers pursuant to their own separate licenses. Contributions are subject to the Developer Certificate of Origin, Version 1.1 (DCO) and the Apache Software License, Version 2.