Twilio Frontline Node.js Quickstart

Before you create your first Conversation, you'll need to sign up for a Twilio account or sign in to your existing account and purchase an SMS-capable phone number. After navigating to the Buy a Number page in the Twilio Console, check the SMS box and click Search.

Expand image

You'll then see a list of available phone numbers and their capabilities. Find a number that suits your fancy and click Buy to add it to your account.

Expand image

Now that you have a Twilio account and an SMS-capable phone number, you're ready to create a Twilio Frontline instance.

Navigate to the Frontline section of the Twilio Console and click on the Create Frontline service button. If you don't see Frontline listed in your Twilio Console, go to Explore Products and under the Solutions section select Frontline. Click on the pin icon to keep Frontline on your sidebar navigation.

Expand image

You'll see a pop-up that asks if you want to set Frontline services as your default Conversation service. Select the checkbox and then click the Confirm button.

Expand image

Now that you've created a new Frontline instance, let's configure Twilio Conversations with the phone number you selected earlier. For these steps, you'll be navigating between the Conversations and the Programmable Messaging sections of the Twilio Console.

1. Navigate to Conversations > Defaults.
2. From the Default Conversation Service dropdown menu, ensure Frontline Service is selected.
3. Unlock the Handle Inbound Messages with Conversations feature with the toggle button. Importantly, click the Save button to apply the new settings!
4. After that, click on the View Service button next to the Default Messaging Service dropdown menu to navigate to the Default Messaging Service configuration page.

Expand image

Under the Programmable Messaging > Default Messaging Service for Conversations page, follow these steps:

1. Click the Autocreate a Conversation setting.
2. Importantly, save the new settings by clicking the Save button.
3. Click Sender Pool from the sidebar.

Expand image

On the Sender Pool page, click the Add Senders button.

Expand image

Select the Phone Number for the Sender Type and click Continue. Then, select the phone number you purchased at the start of this guide and click Add Phone Numbers.

Expand image

Now that we have a Twilio account, a programmable phone number, and Twilio Conversations all set up, let's configure the Frontline Integration Service and Single Sign-On, so that you can securely log in to Frontline.

To launch the integration service and Twilio Frontline here's what you will need:

• Your Twilio credentials (Twilio Account SID and Auth Token) found in the Twilio Console
• An installed version of the twilio-cli
• An installed version of ngrok
• An installed version of yarn

Now it's time to get the Frontline Integration Service behind Twilio Frontline up and running. For your convenience, we've created an integration service written in Node.js (available on GitHub) that implements all of Twilio Frontline's core features.

We will start by downloading and setting up ngrok. Ngrok is a tunneling service that will allow us to expose our local development server to the internet securely.

Once you have ngrok installed and working, run the following command:

ngrok http 5001 

Copy down the Forwarding HTTPS URL (e.g. https://5d70b0c7.ngrok.io). This will be the route that loads our customer data and will be used later in this Quickstart when we populate our customer list.

Clone the node.js Frontline Integration Service repository from Github.

Once you've cloned the repository, go to its root directory and run the following command to rename the example environment file:

mv .env.example .env 

Then open the .env file in the text editor of your choice. Inside the .env file you'll see four environment variables. Let's assign them to the proper values from your Twilio account.

For TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN, use your account credentials, which can be found on the Twilio Console dashboard. These credentials will be used to create a new instance of Twilio Node SDK which will be used to call the Twilio Conversations API.

For TWILIO_SMS_NUMBER, use the Twilio phone number which you purchased during this step.

Optional: For TWILIO_WHATSAPP_NUMBER, use a Twilio phone number enabled for WhatsApp (if you have one).

And with that, we're done editing our .env file.

Now that we have our environment variables configured, the next step is to configure single sign-on. This will allow you to securely authenticate end users who wish to access your Frontline mobile app.

To set up SSO, follow this guide to create an Okta web application and configure it and come back to this Quickstart when you're done.

After configuring single sign-on, our Frontline Integration Service is all set and ready to go! If you don't already have it, install yarn as the package manager for the integration service. Run the following command in the Frontline Integration Service directory to start the service.

yarn install && yarn start

We can now launch the Frontline app and start using it.

To log in to the Frontline mobile app you'll need:

• Your workspace ID from the Frontline Console. This was created when you set up Okta SSO.
• The username and password to your Okta developer account.

First, we'll have to install the Frontline App. Download the Frontline mobile app which is available in both the iOS App Store and the Google Play store respectively.

Once downloaded, open the Frontline app on your device and type in your workspace ID. You can view or change your workspace ID on the SSO configuration page in the Frontline Console.

Expand image

You will then be prompted for your Okta credentials — enter the username and password that you used to sign up for your Okta developer account.

Once you see the Conversations screen with the text "No Active Conversations", you know that you have successfully logged into Twilio Frontline.

Expand image

Finally, if you click the My Customers button on the Frontline App, you'll notice that we're not retrieving any customer data. Let's fix that!

Currently, our Frontline App is configured, but it doesn't have any information about our customers. To fetch that customer data, we'll have to make an API call to a CRM Callback URL that we configure. This call will return a list of customers for a specific Frontline user (worker).

For this Quickstart, we'll mock out the CRM as part of the Frontline Integration Service we're running, but a full-scale application could use a CRM like Salesforce.

Head over to the integration service code and open the src/providers/customers.js file in a text editor. Add your customer data as objects in the customers array like in the code snippet below.

1
    {
2
       customer_id: 1,
3
       display_name: 'Bobby Shaftoe',
4
       channels: [
5
           { type: 'email', value: 'bobby@example.com' },
6
           { type: 'sms', value: 'YOUR_PERSONAL_PHONE_NUMBER' },
7
           { type: 'whatsapp', value: 'YOUR_WHATS_APP_NUMBER' }
8
       ],
9
       links: [
10
           { type: 'Facebook', value: 'https://facebook.com', display_name: 'Social Media Profile' }
11
       ],
12
       worker: 'worker@example.com'
13
    }

In our Frontline Integration Service, the worker field needs to match with the user identity. If you had used Okta as instructed above, this is the username that you used to log in to the Frontline mobile app (in the previous screenshot, this would be johnsmith@example.com).
Then navigate to the Manage page in the Frontline console to set the CRM Callback URL. We will use the Forwarding HTTPS URL (i.e.: https://5d70b0c7.ngrok.io) that we jotted down earlier after running the ngrok http 5001 command.

In the CRM Callback URL input box, add your Forwarding URL and append /callbacks/crm to it.

Expand image

Close the Frontline mobile app and reopen it, then tap the My Customers button. You'll now see a list of the customers you added to the Frontline Integration Service.

Expand image

You can initiate a new conversation from the Customer Details screen and Frontline has an Outgoing Conversations callback for just that. This callback is a URL that will respond back with a proxy number.
The Frontline app will make an API request to the configured callback URL to facilitate the process. To configure this URL, open the Frontline console, go to the Callbacks section, and in the Outgoing Conversations Callback URL configuration option use the forwarding URL (e.g.: https://5d70b0c7.ngrok.io) that we jotted down earlier after running the ngrok http 5001 command. Add /callbacks/outgoing-conversation at the end of the URL.

Expand image

Congratulations! Now, you can have a fun conversation using the Frontline app. 🎉

To be able to receive conversations from customers through the Frontline App, you need to enable inbound routing.
Since the Frontline App is built on the top of the Conversations API, to prepare incoming conversations for Frontline by connecting CRM information to conversation, we need to call and configure onConversationAdd and onParticipantAdded webhooks.
The onConversationAdd webhook will be called before creating a conversation and set a friendly_name and avatar of the conversation.
TheonParticipantAdded webhook will be called when a participant has been added to the conversation. This webhook sets the customer_id, avatar and display_name for customers in a conversation.

Let's take a look at the configuration of the Conversations API Webhook in the Twilio Console:

1. Set the two webhooks in the Twilio Conversations Console. First, set the Pre-Event URL and Post-Event URL to target your ngrok URL. Now, select the onConversationAdd and onParticipantAdded options under Webhook Filtering and click on Save.

   Expand image

   Twilio will call our integration service's /callbacks/conversations endpoint for onConversationAdd and onParticipantAdded events.

After setting the Conversations webhooks, you can now manage inbound conversations. To handle routing for incoming conversations, you have three options:

• Do not route: incoming conversations won't be routed to workers.
• Custom routing: the Custom routing callback URL will be called.
• Pool routing: incoming conversations will be distributed to available Twilio Frontline Users automatically.

Note: For more detailed information on how to enable inbound routing, go to our Custom routing and Pool Routing pages.

Let's enable routing using the Twilio Frontline Console:

1. Navigate to the Manage tab and select Routing. You can find the three routing methods for inbound conversations. Select the one you prefer and click on Save.

   Expand image

Now, you can try to create a new conversation by texting to a Twilio phone number. 🎉

You're all set! From here, you can start building your own application. Continue tweaking the Frontline Integration Service to fit your needs, or rewrite it in your desired programming language. Explore the Twilio Frontline Features and Callbacks section and API section to learn more about Twilio Frontline.

• Create your first Conversation in Frontline
• Ready to make and receive calls with Frontline? Check out this guide to learn how to integrate Voice functionality in Frontline.
• Check out how to automatically handle inbound messages from your customers.