Table of Contents
Architecture #
From a high-level, the Lookup Adaptor functions like this:
Auto-Linking, Basic Search and Detailed Lookup requests
- Each of these requests is sent as a POST request over HTTPS to the Lookup Adaptor(s) you configured, with a JSON body of a specific format.
- When a Lookup Adaptor receives these POST requests, it must parse and process them (e.g.: search your OMS for orders associated with this Customer).
- The Lookup Adaptor must then respond back to Gladly with a JSON body of a specific format so Gladly can present that information to Agents & use it for routing purposes.
- Gladly stores information returned by your Lookup Adaptor under certain scenarios (e.g.: a Detailed Lookup’s valid response).
Watch Out – Implementing Actions
Free shippingActions build on top of a Detailed Lookup, so if you’d like to build Actions, you’ll first need to build a Lookup Adaptor capable of processing and responding to Auto-Linking, Basic Search, and Detailed Lookup requests. on all orders
Actions
- Actions may be returned as part of a response to a Detailed Lookup request.
- Actions on the Profile level display as part of the Plus Menu button on the bottom of the Customer Profile screen. Actions on the transaction level will display as buttons underneath a transaction.
- When an Agent clicks these buttons, Gladly issues a GET request to your Lookup Adaptor asking it to provide information on what form fields Gladly should display for the Agent to fill in before performing this Action.
- When the Agent fills in the form fields and submits the Action, Gladly will issue a POST request to your Lookup Adaptor with information on their form entries. Your Lookup Adaptor must then process this Action and then respond back to Gladly with a status.
- Upon completion of an Action, Gladly will then issue another Detailed Lookup request.
Tip – Transaction-level Actions
Actions at the transaction-level are only available for ORDER type transactions.
Gladly Requests Made #
IP Addresses #
Gladly requests will be made from these set of IP addresses.
Request Headers and Authentication #
Every request that Gladly makes to your Lookup Adaptor will come with a set of headers, some of which you can configure.
Headers may include the following:
| Header Name | Value | Is Always Sent? |
|---|---|---|
| content-type | application/json | yes |
| accept | application/json | yes |
| gladly-time | timestamp of request. format is YYYYMMDDTHHMMSSZ | yes |
| gladly-correlation-id | A string indicating the Gladly request ID | yes |
| user-agent | Go-http-client/1.1 | yes |
| content-length | The POST body content length | yes, if a POST request is made |
| gladly-authorization | Gladly-signed authorization string. More information on how requests are signed can be found here. | yes |
| authorization | OPTIONAL Basic auth header that can be set when configuring Lookup Adaptor in Gladly | no – can be configured in app settings |
| www-authenticate | OPTIONAL Basic Auth realm that can be set when configuration Lookup Adaptor in Gladly | no – can be configured in app settings |
| CUSTOM_HEADER | OPTIONAL custom headers whose names and values can be set when configuring the Lookup Adaptor in Gladly | no – can be configured in app settings |
Note – Authentication
Gladly currently supports sending Basic Auth headers, custom static headers, and the gladly-authorization signed string in requests.
Requests Sent #
Tip – Where are requests made?
All Auto-Linking, Basic Search and Detailed Lookup requests are made to the URL you configured in the App page on Gladly. The Action Button Clicked and Action Form Submitted URLs can be lightly customized, which we will delve into in the Actions tutorial.
| Event Name | HTTP Method | Purpose | When | Agent Experience | Developer Experience | Code Samples |
|---|---|---|---|---|---|---|
| Auto-Linking | POST | Automaticaly link a Profile in Gladly with another Profile in your system without Agent intervention | Lookup Adaptor will receive a POST request from Gladly. If Lookup Adaptor responds with the correctly formatted response, Gladly will automatically link the Profile and then issue a Detailed Lookup request. | If successful, the Gladly customer profile will display detailed information returned from your system. | Lookup Adaptor will receive a POST request from Gladly. If Lookup Adaptor responds with correctly formatted response, Gladly will automatically link the Profile and then issue a Detailed Lookup request. | Sample |
| Basic Search | POST | If auto-linking is not successful (or is turned off), an Agent can use Basic Search to search your system and manually choose a customer record to link to a Gladly Customr Profile | Triggered when Agent manuallly searches for another Profile in your system to link to within Gladly | Agent populates search fields and clicks “Search.” If successful, results display for Agent to link. | Lookup Adaptor will receive a POST request for a Basic Search. If Lookup Adaptor responds with correctly formatted responses, Gladly will display a set of results to Agent to select from. If Agent selects a profile to link to, Gladly will issue a Detailed Lookup request | Sample |
| Detailed Lookup | POST | Show extended information about a linked Customer Profile on Gladly | Agent views a linked Profile for the first time after logging into Gladly or after refreshing their browser Triggered when Profile is linked Triggered after an Action is performed Triggered when an Agent makes an edit on a linked Customer Profile Triggered when a non-phone Contact comes into a linked Profile or an Agent views the Profile after accepting call Triggered when Agent manually clicks on Refresh Data button on linked Profile | Agent sees extended information/actions | Lookup Adaptor will receive a POST request for a Detailed Lookup. If Lookup Adaptor responds with correctly formatted response, Gladly will display extended information for Agents | Sample |
| Action Button Clicked | GET | Display form that Agent can enter custom values into to perform an Action on the Profile within Gladly This is only available after the Profile has been linked! Actions at the transaction level are only available for ORDER-type transactions | Triggered when an Agent clicks on an Action button in Gladly | Form displays for Agent to fill in and submit | Lookup Adaptor will receive a GET request asking for form settings to display. If response is correctly formatted, form will display for Agent. | Sample |
| Action Form Submitted | POST | Perform an Action on Gladly on behalf of Customer (e.g.: cancel an order; award loyalty points) This is only available after Profile has been linked! Actions at the transaction level are only available for ORDER-type transactions | Triggered when an Agent submits Action form on Gladly | Action status / results shown to Agent in Gladly | Lookup Adaptor will receive a POST request with values Agent submitted in the form generated by “Action Button Clicked” event to process. Lookup Adaptor needs to return back status, after which a Detailed Lookup request will be issued. |
