# 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!

> \[!WARNING]
>
> 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.

> \[!WARNING]
>
> In order to get started with Frontline, your account must be part of an [Organization](/docs/iam/organizations).

## Sign up for a Twilio account and get a phone number

> \[!NOTE]
>
> If you already have a Twilio account with an SMS-capable phone number, you're ready to go! [Log in](https://www.twilio.com/login) and head over to the next step.

> \[!NOTE]
>
> 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](/docs/frontline/voice-integration) in the Frontline Console.

Before you create your first Conversation, you'll need to [sign up for a Twilio account](https://www.twilio.com/try-twilio) or sign in to your existing account and [purchase an SMS-capable phone number](https://www.twilio.com/console/phone-numbers). After navigating to the Buy a Number page in the Twilio Console, check the **SMS** box and click **Search**.

![Interface for buying a phone number with SMS capability selected.](https://docs-resources.prod.twilio.com/ee78706be8061688754e8e6d3d28c763d3399d6ff6900ef8c9ecb731c1f3edf5.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.

![List of available local phone numbers with SMS, MMS, and voice capabilities for purchase at $1.00 each.](https://docs-resources.prod.twilio.com/9a7985d3852289556db6b63fb1ff57d4cceca61bf8ead99610f1e11f9adf7d84.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

Navigate to the [Frontline section of the Twilio Console](https://www.twilio.com/console/frontline) and click on the **Create Frontline service** button. If you don't see Frontline listed in your Twilio Console, go to [Explore Products](https://console.twilio.com/develop/explore) and under the **Solutions** section select **Frontline**. Click on the pin icon to keep Frontline on your sidebar navigation.

![Button labeled 'Create Frontline service' with illustration of people using mobile devices.](https://docs-resources.prod.twilio.com/b8ee89562bb93eeda2dd442d4fa45ce954eb7c8c7641a93148914db2e69389c6.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.

![Dialog box to set Frontline as default Conversations service with confirm and cancel options.](https://docs-resources.prod.twilio.com/a7c07897eb726b87b81866226cd81fff2b9e8b922e3e73cf8877051d3905975e.png)

## Configure Twilio Conversations

> \[!NOTE]
>
> Frontline is built on top of [Twilio Conversations API](/docs/conversations/api). For more information, please see the [Conversations Fundamentals](/docs/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**](https://www.twilio.com/console/conversations/configuration/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.

![Twilio Console showing default messaging and conversation service settings with save button.](https://docs-resources.prod.twilio.com/332dc7ab6a847ae135d83fd8c469437ecf937d4ad9ced2177c010e74fc322bae.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.

![Integration settings for messaging service with options for handling incoming messages, including drop or autocreate conversation.](https://docs-resources.prod.twilio.com/7853a16f547e99ab2a57ffe51b76d403de65d0fa8740ef76acfdb6452d451d03.png)

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

![Sender Pool interface with 'Add Senders to Service' button highlighted.](https://docs-resources.prod.twilio.com/9c188589e46c34ac0949d6a3a6146ef7327ec0afdfc400502c006ecaf02e07e0.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**.

![Interface for adding phone numbers with options to select or bulk-add and a search function.](https://docs-resources.prod.twilio.com/99fc31dec7789cf0decbe3917f340375539813d3aae707b9eec9956c404cbe70.png)

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.

## 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](https://www.twilio.com/console)
* An installed version of the [twilio-cli](/docs/twilio-cli)
* An installed version of [ngrok](https://ngrok.com/docs)
* An installed version of [yarn](https://yarnpkg.com/getting-started/install)

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](https://github.com/twilio/frontline-demo-service)) that implements all of Twilio Frontline's core features.

### Configure ngrok

We will start by [downloading and setting up ngrok](https://ngrok.com/download). 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:

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

### Configure the Frontline Integration Service environment

Clone the [node.js Frontline Integration Service repository](https://github.com/twilio/frontline-demo-service) from Github.

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

```bash
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](https://www.twilio.com/console). 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](/docs/frontline/nodejs-demo-quickstart#sign-up-for-a-twilio-account-and-get-a-phone-number).

**Optional**: For `TWILIO_WHATSAPP_NUMBER`, use a Twilio phone number [enabled for WhatsApp](/docs/whatsapp/api#using-twilio-phone-numbers-with-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](/docs/frontline/sso/okta) and come back to this Quickstart when you're done.

> \[!NOTE]
>
> **Note**: You can use any of the following identity providers options: [Okta](/docs/frontline/sso/okta), [Salesforce](/docs/frontline/sso/salesforce), [Google](/docs/frontline/sso/google) or [Azure AD](/docs/frontline/sso/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](https://yarnpkg.com/getting-started/install) as the package manager for the integration service. Run the following command in the Frontline Integration Service directory to start the service.

```bash
yarn install && yarn start
```

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

## 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](/docs/frontline/sso/okta#7-configure-frontline-with-your-new-saml-credentials) 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](https://apps.apple.com/us/app/twilio-frontline/id1541714273) and the [Google Play store](https://play.google.com/store/apps/details?id=com.twilio.frontline) 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](https://www.twilio.com/console/frontline/sso) in the Frontline Console.

![Twilio Frontline workspace ID login screen with terms of service link.](https://docs-resources.prod.twilio.com/b5a4ce7cd13259b8826377623a16956a700cc4a9b1eab8d3bf947a4d5b4bba63.png)

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.

![User available with no active conversations, option to start a new conversation.](https://docs-resources.prod.twilio.com/64e11d8c079ee4ac0152b19f67973a7e0d69e5dfbfe37a8cd03acfc666ee4b8e.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.

```javascript
    {
       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` 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](https://www.twilio.com/console/frontline/configure) to set the **CRM Callback URL**. We will use the Forwarding HTTPS URL (i.e.: `https://5d70b0c7.ngrok.io`) that we jotted down [earlier](#configure-ngrok) after running the `ngrok http 5001` command.

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

![Configure callbacks page with CRM, outgoing conversations, and templates callback URLs.](https://docs-resources.prod.twilio.com/75d5159ac4cf34f780d81e9e58df27f275a33cd48a2c2f3878ead518b32217d6.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.

![Customer list showing two entries for Bobby Shaftoe with navigation bar at the bottom.](https://docs-resources.prod.twilio.com/ae94b7beff329a74700b98d7f18632c3e092640bf821bdeb1bb8e10093a4dbea.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](https://www.twilio.com/console/frontline/configure), 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](#configure-ngrok) after running the `ngrok http 5001` command. Add `/callbacks/outgoing-conversation` at the end of the URL.

![Frontline Configure Callbacks.](https://docs-resources.prod.twilio.com/b9de658993d5d83a77a2f1692071f68b566db599cb81177b655da17376734867.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](/docs/conversations/conversations-webhooks#onconversationadd) webhook will be called before creating a conversation and set a `friendly_name` and `avatar` of the conversation.\
The[onParticipantAdded](/docs/conversations/conversations-webhooks#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](https://console.twilio.com/us1/develop/conversations/manage/webhooks?frameUrl=%2Fconsole%2Fconversations%2Fconfiguration%2Fwebhooks%3Fx-target-region%3Dus1). 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**.

   ![Conversations API Webhook Configuration with pre and post-webhook URL settings and filtering options.](https://docs-resources.prod.twilio.com/f1b72fe33b3f0088145df7f828b38df19f810df1c8d1497b406723a9ddaba079.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](/docs/frontline/handle-incoming-conversations#2-custom-routing) and [Pool Routing](/docs/frontline/handle-incoming-conversations#3-pool-routing) pages.

Let's enable routing using the [Twilio Frontline Console](https://console.twilio.com/us1/develop/frontline/manage/routing?frameUrl=%2Fconsole%2Ffrontline%2Frouting%3Fx-target-region%3Dus1):

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

   ![Inbound routing options for managing conversations with pool routing selected.](https://docs-resources.prod.twilio.com/363d038280ae4e4e1d533038afc8ee88a416dcac450222f2948f854e11888e2a.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 Features and Callbacks section and API section to learn more about Twilio Frontline.

* [Create your first Conversation in Frontline](/docs/frontline/creating-conversation)
* Ready to make and receive calls with Frontline? Check out this [guide](/docs/frontline/voice-integration) to learn how to integrate Voice functionality in Frontline.
* Check out [how to automatically handle inbound messages](/docs/frontline/handle-incoming-conversations) from your customers.