How to embed Twilio Conversations in a Retool app for bidirectional messaging

How to embed Twilio Conversations in a Retool app for bidirectional messaging

Twilio Conversations makes it easy to add messaging to your applications using Twilio's SDKs and APIs. But presenting a chat dialogue in your product or on your website is only half of the battle. You also need to build a chat interface for your agents to interact with.

In this tutorial, you’ll use the Twilio Conversations JS SDK to add bidirectional messaging capabilities to an agent portal built in Retool. Retool is a development platform for internal tools. Together, Twilio Conversations and Retool provide a powerful and easy-to-use toolkit to build custom chat-enabled internal applications.

Prerequisites

In order to complete this tutorial, you will need the following:

• A Twilio account. If you haven't signed up yet, sign up for a free Twilio trial.
• A Twilio phone number. Learn how to buy a Twilio phone number here.
• A Retool account. If you haven’t signed up yet, sign up for a free-forever Retool account.
• A high-level understanding of Retool. If this is your first time using Retool, check out our 5-minute quickstart for an orientation.

Twilio Setup

Before you can start building in Retool, you’ll need to do some pre-work in the Twilio Console.

1. Verify your SMS-enabled phone number

In this tutorial, you’ll build an application that sends and receives SMS-messages. Twilio Conversations can also support a variety of other channels (including in-app messaging, Facebook Messenger, and WhatsApp).

Verify your phone number to enable outbound SMS to that number. Note that this is only necessary with trial Twilio accounts.

2. Create an API Key

Create an API Key and note the API Key SID (string identifier) and Secret for later. The API Key will authenticate and authorize you to interact with Twilio APIs.

3. Create a Twilio Conversations Service

Create a Conversation Service and note the Conversation Service SID for later. A Conversation Service is a top-level container for other resources in the Twilio Conversations REST API.

4. Create a Twilio Functions Service

A Twilio Service is a container for the serverless functions which make it possible for your Retool app to get a chat access token. Your Retool app will use this token to initialize the Conversations SDK.

5. Set Twilio Service environment variables

In your new Twilio Service, set the following environment variables:

Learn how to set environment variables for your Twilio Service here.

6. Configure Twilio Service dependencies

The serverless functions running in Twilio need access to a few software libraries to function properly. Import the following NPM modules:

Learn how to import NPM modules and manage node.js dependencies in your Twilio Service here.

7. Create a Twilio Function to issue chat tokens

In order for the embedded Twilio Conversations client to authenticate with Twilio's services, it needs a valid access token. To create a function for issuing voice tokens:

1. Add a function named /chat-token.
2. Set the visibility of the function to Public.
3. Copy and paste the contents of chat_token.js into the function and save.
4. Copy the URL for this function for later use. You can copy the URL by clicking on the three dots-icon of your function, and then clicking Copy URL.

8. Deploy your Twilio Service

Publish your Twilio Function by clicking Deploy All. This finalizes all the changes you've made.

Retool setup

Now that your Twilio account is set up, let's set up the Retool app.

1. Create a Retool REST API Resource to retrieve chat tokens

In order for your Retool app to authenticate with Twilio, you'll need to get a valid chat token. You’ll configure a REST API resource in your Retool project to query the chat token Twilio Function from your app.

To set this up:

1. Navigate to the /resources page in your Retool instance and click "Create new > Resource".
2. Select REST API as the resource type.
3. Name the resource “Twilio Conversations Chat Token”.
4. Set the Base URL field to the URL of your /chat_token Twilio Function as noted in step eight of the Twilio setup.
5. Specify a header with a key of identity and a value of {{current_user.email}}. This is used to pass the email address of the Retool user to Twilio for use in the token identity.
6. Click Create resource.

2. Create a Twilio API Resource to manage Conversations and Participants

Your Retool app will need to delete previously created Conversations in order to start new Conversations with the same SMS number, as well as add new participants to the Conversation.

To set this up:

1. Navigate to the /resources page in your Retool instance and click "Create new > Resource".
2. Select Twilio as the resource type.
3. Name the resource “Twilio Conversations API”.
4. Specify your Twilio API Key SID as the value of Account SID and your Twilio API Key Secret as the value of Auth Token. These credentials were created in step two of the Twilio Setup. (Note that the current version of the Twilio Resource in Retool doesn’t correctly validate API Keys, so the “Test Connection” button won’t work.)
5. Click Create resource.

3. Import the Retool app code

First, download twilio-conversations-retool-app.json from the Retool app exchange. To import the app code, navigate to the Retool main page and click Create new and select From JSON. Upload the JSON file containing the app code, and name the app.

You may need to connect the existing Resource Queries included in the app to the Resources you created previously. To do this, edit the Retool app and:

1. Open the bottom panel to view the Resource Queries.
2. For each query, select the following Resources from the Resource Dropdown

1. Save each Resource Query.

4. Explore the Retool app

If everything is working as expected, you should now be able to send and receive messages between the Retool app and the phone number you registered! To use the app:

1. When first loading the app, you'll be prompted to enter your Twilio Conversations Service SID. This is the Service SID you retrieved in step three of the Twilio setup.
2. Once the app has initialized, fill out the SMS settings:
   1. Enter the phone number you were assigned when you set up your Twilio account as “Twilio outbound number”
   2. Enter the SMS-enabled phone number that you verified in step one of the Twilio setup as “Customer #” and click Submit.
3. Enter some text in the chat box and press the enter key to send!

 Click the Preview button on the top right to try out the application in end-user mode.

5. Learn about how the custom component works

The Twilio Conversations component has been built as a Retool custom component. You can view the code used in the Twilio Conversations component in Retool by clicking on the twilioConversationsCustomComponent component and inspecting the IFrame Code field. You can also find the same code at retool-custom-component.html for easy reading!

If you want to go deeper, check out our in-depth video walkthrough of how this app is put together!

Wrap up

We hope you enjoyed this introduction to Retool, and have a better understanding of how to use Retool Custom Components to extend the functionality of your internal tools. To learn more, check out Retool University!

Evan Weiss is a Sales Engineer at Retool, where he enjoys teaching customers about how to build custom internal software. You can find him at evan[at]retool.com, as well as on LinkedIn and Twitter.