Getting Started With the Lookup Adapter

Overview

With the lookup adapter, you can pull key customer details from custom sources—like customer address and real-time order history—into Gladly to give your Agents the context they need.

Core Concepts

Customer master — Your internal database or application that contains information about your customers. Ideally, each customer has a unique identifier.

Customer profile — Gladly's representation of a customer that contains information such as name, address, email, phone, and custom attributes (see definition below).

Custom attributes — Custom fields (configured by Gladly) to store and display data about your customers (e.g. Loyalty Points).

Transactions — Purchases (e.g. orders, flights, or stays) made by your customers.

External customer ID — A customer ID is a unique identifier from a customer record in your customer master. This ID is stored in the Gladly profile as a foreign key for future lookups.

Initial search — The first phase of the lookup process that adds the External customer ID to the customer profile.

Data refresh — The second phase of the Customer Lookup process that retrieves the latest customer information—including name, email, phone number, address, custom attributes, and transactions—from your customer master and caches it in the Gladly customer profile.

How It Works

The Gladly customer profile is first linked with the record in your customer master during the initial search phase. This process involves searching your customer master for matching records based on customer profile attributes—like email address, phone number, name, or any custom attribute—and sending back all matches. The Agent selects the correct record, which saves the external customer ID (generated from your customer master) into the customer profile.

Once the Gladly customer profile is linked to a record in your customer master, Gladly does a data refresh. This process involves retrieving the latest customer data, caching it, and displaying it in the customer profile.

Setup Your Local Environment

To get a local version of the lookup adapter running, you will need:

  • A secure tunnel to your localhost (consider ngrok)
  • User account with an administrator role in a Gladly sandbox or use Postman (if you just want to get the responses formatted properly)

Configuring Gladly

To configure the Lookup API, you will need to access the Integrations menu (located under Settings). If you are configuring the lookup adapter locally, you will need to put your public ngrok URL in the URL field of the Customer Lookup configuration.

Parsing Gladly Requests

Every request that you receive from Gladly will have a lookup level. This helps distinguish what kind of query is coming in:

Initial search = lookupLevel: "BASIC"

Data refresh = lookupLevel: "DETAILED"

req = requestObjectFromGladly;

if (req.body.lookupLevel == 'BASIC') {
    // Call your intitial search function and pass it the request body
    lookupService.basicLookup(req.body);
} else if (req.body.lookupLevel == 'DETAILED') {
    // Call your data refresh function and pass it the request body
    lookupService.detailedLookup(req.body);
} 

Initial Search

During initial search, Gladly will send all attributes from the customer profile in a request. Your endpoint will use the attributes to determine a list of possible matches to send back to Gladly.

Note that there are two ways an Agent can kick off initial search: 1. The Agent opens the customer profile and Gladly automatically sends a request with an array of the Customer's email addresses, phone numbers, name, and custom attributes, or 2. The Agent manually attempts to link customer in Gladly UI.

Automatic Initial Search
You can configure which fields you would like Gladly to send in the initial search request by selecting the Auto-Link boxes in the Customer Lookup menu (under Settings).

Example Automatic Initial Search Request
If Customer email was the only box selected in the Auto-Link menu, then the request payload would look like this:

{
    "lookupLevel": "BASIC",
    "query": {
        "emails": ["juliechang@gladly.com"],
        "id": "KPo4R27eQAyhb8WbkKA1qQ",
    },
    "uniqueMatchRequred": "false"
}   

Matching records that are returned will be displayed to the Agent as suggestions.

Manual Initial Search
Agents have the option to search manually as well. After clicking on the Link to a Customer button from the customer profile, they will be presented with a list of search boxes. You may work with Gladly to configure which fields that Agents can search on.

Example Manual Initial Search Request
If the Agent searched by email, then the request payload would look like this:

{
    "lookupLevel":"BASIC",
    "query": {
        "email":"juliechang@gladly.com"
    },
    "uniqueMatchRequired":"false"
}

The Code
Your endpoint must be able to receive and parse either query during initial search. For the sake of simplicity, this tutorial will provide pseudocode using the Customer's email as the search parameter.

query = requestBodyQuery;
lookupEmail = '';
results = [];

// check to see if the query is a automatic or manual
// if there is an emails field, it is automatic
// if there is an email field, it is manual

if (query.emails && query.emails.length > 0) {
    // automatic request
    // use first email from array of emails for search
    lookupEmail = query.emails[0];
} else if (query.email) {
    // manual request
    lookupEmail = query.email;
}

// if no email was sent, nothing to search; send back empty results
if (lookupEmail == '') {
    return {results};
}

customers = yourCustomerDb;

for each customer in customers: {
    if (customer.email == lookupEmail) {
        // Be sure to format each object in your results array as Gladly expects
        results.push({
            externalCustomerId: customer.id,
            emails: [{ original: customer.email }],
            name: customer.name,
        });
    }
}

return {results}

Expected Response to Gladly

Gladly expects the returned results to be an array of objects. Each object should be a matching customer record that is required to have an externalCustomerId. We recommend also adding additional information for the Agent to use to match to the Gladly customer profile, like name, email, or phone number. See the Customer Lookup API docs for a more detailed response sample.

Note that Gladly recommends not including transaction data in the initial search response.

{
    "results": [
        {
            "externalCustomerId":"1234",
            "name":"Julie Chang",
            "emails": [{"original": "juliechang@gladly.com"}],
        },
        {
            "externalCustomerId":"6789",
            "name":"J Chang",
            "emails": [{"original": "juliechang@gladly.com"}],
        }
    ]
}

Your response will be displayed to the Agent so they can link the right customer master record to the Gladly customer profile.

Once the Agent selects the matching record, the externalCustomerId from the response will be stored on the customer profile as a foreign key to be used for future data refreshes.

Data Refresh

Once the Agent has linked the customer profile with the record in your customer master during the initial search phase, Gladly will perform a data refresh to retrieve important information to be displayed in the customer profile.

Example Data Refresh Request:

{
    "lookupLevel":"DETAILED",
    "query": {
        "emails": ["juliechang@gladly.com","j.chang@gmail.com"],
        "phones": ["+15013299800"],
        "externalCustomerId":"1234",
        "id":"KPo4R27eQAyhb8WbkKA1qQ",
        "name":"Julie Chang"
    },
    "uniqueMatchRequired":true
}

Upon receiving a data refresh request from Gladly, use the externalCustomerId to find the matching record from your customer master.

query = requestBodyQuery;
customers = yourCustomerDb;
customerObjectToReturn = {};

for each customer in customers: {
    if (query.externalCustomerId == customer.id) {
        customerObjectToReturn = customer;
    }
}

if (customerObjectToReturn == {}) {
    return ({results: []});
} else {
    return ({
        results: [{
            externalCustomerId: customerObjectToReturn.id,
            emails: [{ original: customerObjectToReturn.email }],
        phones: [{ original: customerObjectToReturn.phone }],
        name: rcustomerObjectToReturn.name,
        }];
    });

Expected Response to Gladly:

{
    "results": [{
        "externalCustomerId":"1234",
        "name":"Julie Chang",
        "emails": [{"original": "juliechang@gladly.com"}],
        "phones": [{"original": "+1-555-555-5555"}],
    }]
}

The expected response should be formatted like the Gladly Customer object. See the Customers API for more details.

Error States

If you receive a request with unexpected payload from Gladly:

While Gladly will receive and log your error code into our third party systems, we do not currently support errors from your system.

If you return a malformed response to Gladly:

If Gladly receives a malformed response or hits a 500 error, our frontend will fail gracefully. If the agent is trying to link a profile, they will receive no matching records. If the customer profile is trying to refresh, Gladly will use what is already cached.

If your endpoint does not respond within 15 seconds:

Gladly does not retry requests. Your system has 15 seconds to respond before the request times out.

See the Customer Lookup API developer docs for more information.