My Customers

In the Frontline mobile application you can access a list of Customers and get their Customer Details. In order to populate the Customer Details and Customers List screens with data, the Frontline application needs information about your customers.

Configuring the CRM Callback URL

To grab the data for the Customers List and Customer Details screens, the app will make an API call to the configured CRM Callback URL to fetch customer data for each screen. Based on the Location parameter, your server can tell which information was requested.

To configure the CRM Callback URL, open the Frontline console and set the CRM Callback URL configuration option to a URL that will return customer data in JSON format:

For an example of a Customer object, check out the Node.js Quickstart section on populating the My Customers list.

Customer ID and Participant properties

Customer objects returned from the CRM callback URL contain the property customer_id. This ID is an important part of the Frontline application as some features, such as Customer Details, rely on it. It’s also a way to tie together the Conversations API and CRM data under the hood. A Customer ID is not restricted to any particular format, the only requirement is that it’s unique.

An additional property of the Customer object is the Participant. The Participant resource allows the user to navigate from the conversation screen to the Customer Details screen, which shows individual information for that particular Customer.

Responding to the CRM Callback

When the Frontline application makes a POST HTTP request to your server, it includes information about the action that triggered the callback to your Frontline Integration Service. Each action has its own Location type. The Location will be sent with the rest of the parameters in the request body in application/x-www-urlencoded format.

In addition to the location-specific parameters, each request also contains the following parameters and information:

In what follows, we'll describe two possible actions: GetCustomerDetailsByCustomerId and GetCustomersList.

GetCustomerDetailsByCustomerId

Gets details for an individual Customer using the customer_id attribute.

Request params

Response format

JSON response example

{
 "objects": {
   "customer": {
     "display_name": "Bobby S.",
     "customer_id": "1",
     "channels": [{ type: "sms", "value":"+123456789" }]
   }
 }
}

In App example

GetCustomersList

Gets a list of Customers and returns them as an array of objects based on a worker identity.

Request params

Response format

JSON response example

{
  "objects": {
    "customers": [
      {
        "display_name":"Bobby S.",
        "customer_id":"1"
      }
    ]
  }
}

Customer search

The Frontline app has built-in search functionality which filters customers locally. We recommend implementing your own search functionality for better performance, especially if your Frontline users have more than 100 customers, or if you’d like to search across additional fields in your CRM.

Frontline uses the GetCustomerList location for searching customers with an additional Query parameter. Your integration service can interpret that as a search operation by checking for the existence of this parameter. If your integration service handles the search, the response should contain the property searchable and set it equal to true.

Response payload example

{ 
  "objects": {
    "customers":[
      {
        "display_name":"Bobby S.",
        "customer_id":"1"
      }
    ],
    "searchable": true
  }
}

Contact addresses and Phone Number Masking

Phone number masking is a Frontline Administration feature that applies masking to the last four digits of any Channel Address supplied to Frontline from the CRM callback GetCustomerDetailsByCustomerId. Phone number masking applies to all channel addresses including phone numbers and WhatsApp numbers on the Frontline customer details screen.

In App example:

How to set up Phone Number Masking as an account owner or admin

You can follow the next steps to enable or disable Phone Number masking for all users in the account:

1. Sign in to the Twilio Console as an admin with the privilege to edit account settings.
2. In the Develop menu, navigate to the Frontline console. Go to the Manage > Callbacks section.
3. Under Contact phone number display setting, click Mask contact phone numbers to enable masking or click Show full contact phone numbers to disable masking.
4. Click Save.

Custom pagination

If the Anchor-based pagination in the Frontline Integration Service (see customers.js) doesn’t suit your needs, you can use the objects.next_page_token field to implement your custom pagination logic. It can be used for token/offset based pagination.

Example request

curl --location --request POST 'https://example.com/callbacks/crm' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'Location=GetCustomersList' \
  --data-urlencode 'Worker=alice' \
  --data-urlencode 'PageSize=30'

Example response

{
  "objects":{
    "customers":[
      {
        "display_name":"Bobby S.",
        "customer_id":"1"
      }
        ...
    ],
    "next_page_token": "PAGE_TWO_TOKEN"
  }
}

If next_page_token is defined, the app adds the passed next page token as the NextPageToken attribute to the payload, instead of Anchor, to every consecutive request after the first page load.

curl --location --request POST 'https://example.com/callbacks/crm' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'Location=GetCustomersList' \
  --data-urlencode 'Worker=alice' \
  --data-urlencode 'PageSize=30' \
  --data-urlencode 'NextPageToken=PAGE_TWO_TOKEN'

Response:

{
   "objects":{
      "customers":[
         {
            "display_name":"John S.",
            "customer_id":"31"
         }
        ...
      ],
      "next_page_token": "PAGE_THREE_TOKEN"
   }
}