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

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.

I've got an account! What's next?

Create a new 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.

Create a Frontline Service.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

Frontline is built on top of Twilio Conversations API. For more information, please see the Conversations Fundamentals guide.

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.

Conversational Messaging Twilio Console.png

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.

Default Conversation Service Autocreate

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

Frontline Sender Pool.png

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.


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.

Great! Show me how it's done!

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.

Configure ngrok

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. This will be the route that loads our customer data and will be used later in this Quickstart when we populate our customer list.

Configure the Frontline Integration Service environment

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 evironment 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 Helper Library 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.

Configure Single Sign-on

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.

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 to 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. 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.

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.


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: '' },
           { type: 'sms', value: 'YOUR_PERSONAL_PHONE_NUMBER' },
           { type: 'whatsapp', value: 'YOUR_WHATS_APP_NUMBER' }
       links: [
           { type: 'Facebook', value: '', display_name: 'Social Media Profile' }
       worker: ''

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

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.: 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.


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.


I'm ready to talk to my customers. Show me how!

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 (e.g.: that we jotted down earlier after running the ngrok http 5001 command. Add /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.

    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.

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 Features and Callbacks section and 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!