The purpose of this project is to demonstrate how Trello can be integrated with Twilio. The application built here is to help a restaurant manage a wait list for their customers. Using Trello as an interface the restaurant can manage customers on the wait list. The integration with Twilio helps facilitate communications between the restaurant and customers.
Together this application:
- Allows customers to use SMS to signup, cancel, and get their position on the wait list.
- Certain card movements prompt automatic messages to be sent to the affected customer.
- Common messages can be sent to a customer with the click of a button.
- Messages are personalized to the customer.
- Can be deploy in a few commandline commands.
The rest of the documentation walks through the prerequisites for the application and each of the quick deploy steps. Once you have the prerequisites completed a majority of the app can be deployed in just a few commandline commands.
While this app is specific to managing a restaurant wait list there are a number of derivative use cases! If you build something yourself tell me about it! Also, if something isn't clear in the documentation or in some behavior of the application let me know and I can help you work through it.
A majority of this app was built via live coding on Twitch. I'm a big proponent of building in public. If this application interests you find me on Twitch (matty_v_codes) to follow along on my next project!
Before getting started you will need the following to complete the setup of the app:
- A Twilio account. If you don't have an account already you can sign up with this link for a free $10 to get started (more than enough for this app!)
- A Trello account. You will need to have a Trello Gold account to support some of the functionality we're using here. You can get started creating your Trello account here.
- Download and install the Twilio CLI and Autopilot Plugin. We'll use this to help deploy some of our Twilio resources. The Twilio CLI Quickstart has fantastic instructions for installing and setting up the CLI. Those instructions are also summarized in the Setting up the Twilio CLI section of this documentation.
- Have ngrok installed.
- Install the packages in
requirements.txt.
Twilio Autopilot will handle your customer interactions. With Autopilot you can define all the different actions your bot will perform. To deploy the bot we're going to use the Twilio CLI that provides the ability to manage your bots from the commandline a snap.
If you don't have the Twilio CLI installed already on a Mac you can install it through HomeBrew:
brew tap twilio/brew && brew install twilioOn Windows you can install the Twilio CLI through Node. Make sure you have Node version 10.12 or above and enter the following command. Otherwise you will have to update your version of Node before proceeding.
npm install twilio-cli -gOnce you have installed the Twilio CLI you can login with your Twilio credentials you used to populate the .env file earlier. Enter the following command:
twilio loginThe last step is to install the Autopilot plugin that will give you the ability to manage your Autopilot bots.
twilio plugins:install @dabblelab/plugin-autopilotYou can test the install with the following command:
twilio autopilotAfter setting up your Trello and Twilio accounts the app can be deployed largely through the terminal. Make sure you have cloned the mimosa repo. Open a terminal window and make sure your working directory is in the mimosa directory.
To setup the app you will:
- Add your account information to the
.envfile - Start the ngrok server
- Create the Autopilot bot
- Run the
deployscript to setup Trello and Twilio resources - Setup the Card Rules / Buttons on your Trello Board
Create a .env file in the project directory. You can use .env.sample as a template for what needs to be provided in the .env file. If you are going to save your code with git make sure you add the .env to your .gitignore file to protect your API keys and tokens!
You will need to provide information about both your Trello and Twilio accounts so that you can access the APIs.
For Twilio you are going to need the TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKENassociated with your account. You can find these values in the upper right corner on the main page of the Twilio console. Copy these values into your .env file.
Next, you need to purchase a Twilio phone number that customers can text. From the console select "Phone Numbers" from the menu of services on the left. Make sure you choose a phone number with texting capability!
Once you have purchased your phone number enter the phone number in the E.164 format (i.e. +14155552671 format) in the TWILIO_FROM_NUMBER option in the .env file. Also, find the SID for your phone number and enter it in the TWILIO_PHONE_NUMBER_SID option in .env.
Next, you need to setup the Trello variables in .env so that you can access the Trello API. Follow the Trello API Introduction to generate your API key and API Token.
Once you have your Trello API Key and API Token you can populate TRELLO_API_KEY and TRELLO_TOKEN in the .env file.
For testing and development we're going to use ngrok to connect our Autopilot bot to the internet.
If you don't have ngrok installed you can download it for free from their website.
Once ngrok is installed run the following from the Terminal to start ngrok.
ngrok http 5000You will see a HTTPS forwarding address. Keep that handy as you'll need that in the upcoming steps.
We're going to use Twilio Autopilot to build a bot to process customer messages. Autopilot will interpret customer messages and direct them to the correct task they request.
The project contains a file schema_template.json defining the behavior of the Autopilot bot. The JSON file has details about Throughout the template there are placeholders for the appropriate ngrok address to make sure requests get forwarded to the correct location to be processed. Instead of having to replace these instances with your own ngrok address there is a function in assets.py called update_autopilot_endpoints
that will make those replacements and generate a new schema file you can use for deployment. You can call this through a terminal call replacing NGROK_URL with the HTTPS forwarding address of your ngrok server.
python3 assets.py update-autopilot-endpoints NGROK_URL
The output is a new file schema.json that has the correct ngrok address. You can now use schema.json to create your Autopilot bot using the Twilio CLI.
In the commandline enter:
twilio autopilot:create --schema schema.json
The command will create your Autopilot bot according the schema defined in your JSON file. If you already have an existing bot and would just like to update the bot you can enter:
twilio autopilot:update --schema schema.json
After creating the Autopilot bot you need to get the SID identifying the bot and add it to your .env file. From the commandline enter the following command to get a list of your Autopilot bots.
twilio autopilot:list
Find your Autopilot bot from the list and column containing the SID. Copy the SID and paste it in your .env file for the TWILIO_AUTOPILOT_SID value.
Now the Trello assets and the remaining Twilio assets need to be setup. The setup for all these assets is completed through a single commandline call deploy. The deploy function will:
- Create a new Trello board
- Create lists in the Trello board
- Create custom labels on the Trello board
- Enable the Custom Fields Power-Up on the board (NOTE: this step will fail if you don't have at least a Trello Gold account)
- Create Custom Fields for customer name and phone number
- Setup a Twilio Sync Map Service for mapping customer phone numbers to their Trello card
- Build a Twilio Studio Flow to manage different workflows
- Connect the Twilio Studio Flow to your phone number
All of the above is done through one commandline call where you have to provide a name for the Trello board and the ngrok URL:
python3 assets.py deploy "Board Name" NGROK_URL
Now if you log into your Trello account you should see your board created with all of the lists included.
The last step is to setup the Trello Card Buttons and Card Rules. Unlike the previous steps that were packaged into command line scripts these have to be setup manually using Trello's Butler feature. Butler allows you to set up board automation tasks and other board functionality including capturing card movements and creating card buttons.
Log into your Trello account and find the board you created in the previous step. Click the Butler button in the upper right corner.
Click Rules from the menu on the left. Our board is going to need to capture two different actions as cards are moved around.
The first rule captures when a card is dragged from Wait List to the Table is Ready list. When this happens we want to trigger a text message to be sent to the customer alerting them the table is ready.
Click Create Rule and then + Add Trigger.
Under Select Trigger choose Card Move.
In the second box select moved into then Table is Ready and finally by anyone then click the green + sign to create the trigger.
Next the action for when the trigger executes needs to be defined.
Under Select an Action choose Content.
Scroll to the bottom where you can define a HTTP request.
Select the post to option. As the URL enter NGROK_URL/table-is-ready substituting your ngrok URL.
Finally enter the following into the payload:
{"name": "{{%name}}", "phone_number": "{{%phone_number}}"}
The payload will send the customer name and phone number entered into the fields of the customer card to our endpoint so that a more personal message can be sent to the customer.
The second rule captures when a card is removed from the board. When this happens we want to make sure the customer is also removed rom the Twilio Sync Map to avoid any future conflicts.
Click Create Rule and then + Add Trigger.
Under Select Trigger choose Card Move.
We're going to capture when a card is archived. Go to the third box and select the options so that it reads:
"when a card is archived by anyone"
Click the green + sign to create the trigger.
Similar to before the action will be another HTTP request.
Under Select an Action choose Content.
Scroll to the bottom where you can define a HTTP request.
Select the post to option. As the URL enter NGROK_URL/remove-sync-map-entry substituting your ngrok URL.
Finally enter the following into the payload:
{"phone_number": "{{%phone_number}}"}
In this rule we only need the phone number in the payload to delete the entry.
Card Buttons can be added to our Cards to provide the user with access to quick functionality. Customers don't always come when their table is ready, so the first button we're going to add will send follow-up reminders if the customer's table is ready and they haven't shown up.
From the Butler menu select Card Button from the menu on the left.
Click Create Button.
Give the button a title, Table Reminder and choose an icon for the button then check the box next to Close card when action performed.
Click Add Action.
Choose the Content option and scroll to the bottom to create the HTTP request.
Select the post to option. As the URL enter NGROK_URL/table-reminder substituting your ngrok URL.
Finally enter the following into the payload:
{"name": "{{%name}}", "phone_number": "{{%phone_number}}"}
Now when you open a card on your board there will be a button to quickly send a reminder the customer's table is ready.
The second button is used to handle workflows where the customer is a walk-in. As a business you want to make sure the phone number can be confirmed so that messages about when their table is ready can be delivered.
From the From the Butler menu select Card Button from the menu on the left.
Click Create Button.
Give the button a title, Confirm Phone and choose an icon for the button then check the box next to Close card when action performed.
Click Add Action.
Choose the Content option and scroll to the bottom to create the HTTP request.
Select the post to option. As the URL enter NGROK_URL/confirm-phone substituting your ngrok URL.
Finally enter the following into the payload:
{"name": "{{%name}}", "phone_number": "{{%phone_number}}", "card_id": "{cardid}"}
The last step is to start your Flask server by entering the following in the commandline:
python3 bot.py
Text your phone number and see what happens! Now that everything is setup you should be able to text your phone number and interact with the application.