Menu

Expand
Rate this page:

Twilio Frontline Node.js Quickstart

Twilio Frontline is a mobile application that allows deskless employees to connect with their customers, anywhere at any time.

This Frontline Quickstart will guide you through the entire process of configuring your Twilio Frontline application and populating your app with customer data.

In this Quickstart, you will learn how to:

  1. Sign up for Twilio and get an SMS-enabled phone number
  2. Create a new Frontline instance and configure Conversations
  3. Configure a Frontline Integration Service
  4. Populate your list of customers in the Frontline mobile app

Let's get started!

A Frontline app cannot co-exist with a Flex app in the same Twilio Project. If you want to run both Flex and Frontline, you'll need to create separate Twilio projects for each.

In order to get started with Frontline, your account must be part of an Organization.

Sign up for a Twilio account and get a phone number

If you already have a Twilio account with an SMS-capable phone number, you're ready to go! Log in and head over to the next step.

If you’d like to integrate Voice functionality into your Frontline Mobile Application, you will need to have a Twilio phone number with voice capabilities and configure the Voice calling functionality in the Frontline Console.

Before you create your first Conversation, you'll need to sign up for a Twilio account or sign into 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.

Buy a Number.png

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.

Available Numbers.png

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

Create a new Twilio Frontline instance

Visit the Frontline section of the Twilio Console and click on the Create Frontline service button.

Create Twilio Frontline Instance.png

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.

Set Frontline service as default.png

Configure Twilio Conversations

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

(Frontline is built on top of Twilio Conversations. For more information, please see Conversations Fundamentals in the Conversations documentation.)

First, in the Conversations console under Manage, open the "Defaults" page

  1. From the Default Conversation Service dropdown menu, ensure Frontline Service is selected.
  2. Next, unlock the "Handle Inbound Messages with Conversations" feature with the toggle button.
  3. Importantly, save the new settings by clicking the Save button now!
  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.

configure-conversations.png

On the Default Conversations Service page in the Programmable Messaging console;

  1. Click the "Autocreate a Conversation" setting. Don't forget to hit Save!
  2. Next, navigate to the Sender Pool page by following the link in the sidebar.

Messaging-Service-Integration.png

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

Frontline Sender Pool.png

Select Phone Number for the Sender Type and click Continue.

  1. Now select the phone number you purchased at the start of this guide and
  2. Click Add Phone Numbers.

Add-Senders.png

Now that we have a Twilio account, a programmable phone number, and Twilio Conversations all set up, we can start configuring Twilio Frontline features with a Frontline Integration Service.

Configure the Twilio Frontline Integration Service

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 (i.e. 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.

Inside the Frontline Integration Service directory, run the following command to copy the example evironment file. Then open the .env file in the text editor of your choice:

mv .env.example .env 

Inside the .env file you'll see four environment variables. Let's assign them to the proper values from your Twilio account.

For the 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 HelperLibrary which will be used to call the Twilio Conversations API.

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

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

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

Configure Single Sign-on

Now that we have our environment variables configured, the last 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.

Note: You can use any of the following identity providers options: Okta, Salesforce, Google or Azure AD to configure SSO with Frontline.

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.

My demo service is set up. I'm ready log in to the Frontline app!

Log in to the App

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

  • Your workspace ID from the Frontline Console.
  • 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 set your workspace ID on the SSO configuration page in the Frontline Console.

Frontline Workspace ID sign in

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.

frontline-conversations-screen.png

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!

Populate the My Customers List

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.

    {
       customer_id: 1,
       display_name: 'Bobby Shaftoe',
       channels: [
           { type: 'email', value: 'bobby@example.com' },
           { type: 'sms', value: 'YOUR_PERSONAL_PHONE_NUMBER' },
           { type: 'whatsapp', value: 'YOUR_WHATS_APP_NUMBER' }
       ],
       links: [
           { type: 'Facebook', value: 'https://facebook.com', display_name: 'Social Media Profile' }
       ],
       worker: 'worker@example.com'
    }

In our Frontline Integration Service, the worker needs to match with the user identity (i.e. the email).

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 5000 command.

In the CRM Callback URL input box add your Forwarding url with /callbacks/crm at the end of the url.

frontline-crm-callback.png

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.

Frontline-customer-list.png

Start your first Outgoing Conversation

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 (i.e.: https://5d70b0c7.ngrok.io) that we jotted down earlier after running the ngrok http 5000 command, with /callbacks/outgoing-conversation at the end of the url.

Frontline Configure Callbacks.png

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

How to enable incoming messages?

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.

The onParticipantAdded 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.
    webhooks-conversations.png

    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.
    manage-inbound-conversations.png


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

What's Next?

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 Feature & API section to learn more about Twilio Frontline.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more