calebsander/ftc-match-bot

Runs a Twilio SMS bot to send FTC match results

ftc-match-bot

Fetches match schedules, match results, and team rankings for FIRST Tech Challenge matches and uses Twilio to send results over SMS. Each user subscribes to a specific team and will receive results for that team only.

SMS commands

All commands are case-insensitive.

• rank: list top 10 teams in each division, plus your team (QP, RP, and matches played)
• done: stop receiving match results; stop also does this but permanently prevents you from receiving texts from the bot, per Twilio rules
• ?: sends information about commands
• Team number (e.g. 6055): list all matches and results for the team, and subscribe to future match results

Sample responses:

• rank:

   (QP, RP, Matches)
   Hopper
   1. 11115 (16, 3145, 9)
   2. 12538 (16, 2395, 9)
   3. 11362 (16, 2381, 9)
   4. 7182 (16, 2196, 9)
   5. 8644 (14, 2827, 9)
   6. 10030 (14, 2804, 9)
   7. 12970 (14, 2375, 9)
   8. 9794 (14, 2357, 9)
   9. 12377 (14, 2263, 9)
   10. 9927 (12, 2597, 9)
   36. 11180 (2, 2017, 9)
  
   Tesla
   1. 9867 (18, 2617, 9)
   2. 8397 (16, 2501, 9)
   3. 9971 (14, 3056, 9)
   4. 8645 (14, 2918, 9)
   5. 6347 (14, 2652, 9)
   6. 12833 (14, 2540, 9)
   7. 6055 (14, 2513, 9)
   8. 10358 (12, 2794, 9)
   9. 12601 (12, 2760, 9)
   10. 11100 (12, 2550, 9)
   Good luck! -The GearTicks
  

• done:

   Unsubscribed
  

• ?:

   Text "done" to disable. Text "rank" for rankings. Good luck! -The GearTicks
  

• 6549:

   5B w/ 5477 v. 6040 & 3032 (L 300-234)
   10R w/ 6217 v. 12538 & 7182 (L 190-583)
   20B w/ 7026 v. 9927 & 11362 (L 326-250)
   29B w/ 12787 v. 12970 & 1 (L 544-411)
   41R w/ 7468 v. 207 & 11754 (L 342-462)
   54B w/ 10030 v. 7350 & 9372 (W 350-362)
   63B w/ 11115 v. 2753 & 8644 (W 425-478)
   68R w/ 8297 v. 10582 & 3981 (L 197-207)
   75R w/ 4347 v. 8699 & 9794 (L 318-455)
   SF-1-1 (W 688-706)
   SF-1-2 (L 558-546)
   SF-1-3 (L 688-426)
   You will now be texted when team 6549's scores are announced. Text "done" to disable. Text "rank" for rankings. Good luck! -The GearTicks
  

• Match results:

   WON match F-2 (628-587).  Text "rank" for rankings. Good luck! -The GearTicks
  

How it works

All tournament data is fetched from the published HTML files generated by the FTC score system. There are 3 types of files that are used: match lists, detailed match results, and rankings. The match schedule is fetched at the start of the competition and match lists for each team are created in the matches directory, e.g. matches/6055.json for team 6055's matches. Subscribers to each team are kept in a registered-numbers.json file and match results that have been announced are kept in a recorded-matches.json file. The server reads from these files when it starts up, and will create them if they don't exist. Match results are fetched every 30 seconds (as well as when a team schedule is requested) and if a new result has been reported, it is texted to all subscribers to teams in the match. Rankings are newly fetched whenever they are requested. The SMS functionality is handled by Twilio. Incoming SMS messages are configured to send POST requests to the server, and the server's response gets texted back to the client. Match results are sent through Twilio's Node.js API because they are not direct responses to a client.

Using the bot

The bot runs on Node.js, so you will need to install Node.js (version 8.0 or higher). You can change the Good luck! -The GearTicks message that is appended to every message by changing the value of END in text.ts

Match results and rankings are scraped from the HTML files generated by the FTC score system. You will need to set the URLs for these files for each competition:

• MATCH_RESULTS_URLS in text.ts should be an array of MatchResultsDetails URLs, usually one per division and one for the inter-division finals. For example, http://scoring.ftceast.org/cache/MatchResultsDetails_East_Super-Regional_Hopper.html was the URL for the Hopper division at the East Super-Regionals
• RANKING_URLS in text.ts should be an object mapping division names to Rankings URLS, usually one per division. For example, http://scoring.ftceast.org/cache/Rankings_East_Super-Regional_Tesla.html was the URL for the Tesla division at ESR, so RANKING_URLS would have Tesla: 'http://scoring.ftceast.org/cache/Rankings_East_Super-Regional_Tesla.html'
• MATCH_LIST_URLS in make-match-lists.ts should be an array of Matches URLs, usually one per division. For example, http://scoring.ftceast.org/cache/Matches_East_Super-Regional_Hopper.html was the URL for the Hopper Division at ESR

You will need to purchase a number capable of SMS from Twilio (make an account and then visit https://www.twilio.com/console/phone-numbers/search). Set NUMBER in text.ts to the phone number you choose, for example [phone] (meaning [phone]). Put your authentication information (account SID and auth token, which you can find at https://www.twilio.com/console) in twilio-account.json, e.g. {"sid":"ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","authToken":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}.

Choose a port to run the bot on (e.g. 6055). Set PORT in text.ts to this value and make the Twilio number point to this URL:

• Suppose you are hosting the bot at abc.com using HTTPS on port 6055
• Go to the Phone Numbers tab on Twilio and click on the number you are using for the bot to change its settings
• Under Messaging, set the A message comes in field to Webhook, with URL https://abc.com:6055 using HTTP POST

The code is currently set up to run an HTTPS server rather than an HTTP server. If you want to use HTTPS, configure the filepaths to the private key, certificate, and certificate authority at the bottom of text.ts to match your configuration. I highly recommend Let's Encrypt for generating free HTTPS certificates. If you want to use HTTP instead, remove the certificate-loading code and replace it with http.createServer(httpRespond).listen(PORT).

To run the bot, execute the following commands:

npm i #install modules
npm run build #compile the TypeScript code into JavaScript
node text.js #start the server

Once match schedules are posted, run node make-match-lists.js to populate the matches directory with match lists for each team. Your text bot should now be ready to use!