Overview

The following document outlines the configuration of the Custom Endpoint connector.

The Custom Endpoint feature of Third Party Bots allows brands to provide their REST API as a service of bot responses inside the Conversational Cloud. This is complementary to the LivePerson Functions integration and suited for solutions that are: too complex to be comfortably implemented in a LivePerson function, or need to be implemented in a different programming language or they are necessary to be fully controlled by the brand. Possible user-cases that can help brands leverage the custom endpoint feature are as follows:

  • Brands can provide a REST API service as an orchestration layer between the Conversational Cloud and the AI vendors of their choice that fulfills tasks like context enrichment, data sanitization, or routing.
  • Brands can connect their instance of the Conversational Cloud to AI vendors that are not supported out-of-the-box by LivePerson. AI vendors can provide a REST API service to get out-of-the-box support between the Conversational Cloud and their platform.

Configuration

See the Getting Started guide first to complete the necessary preparations for your account to use Third Party Bots

Prerequisites for Vendor Configuration

To complete the Custom Endpoint vendor configuration step, please ensure you have the following measures taken:

  • The Custom Endpoint service must be implemented according to the provided API specification defined by Third-Party Bots. A reference implementation of the API specification can be found on the public git repository here. Third-Party Bots connector will call the defined endpoint with the consumer message as payload.

  • The Custom Endpoint service domain must be whitelisted before it can be used in Third-Party Bots. If whitelisting is not done, then the bot will not start nor will it be able to perform a test connection. Please contact the Third-Party Bots team or LivePerson account representative (other contact options: chat with us on this page, or message Support) to set this up for you.

  • Third-Party Bots uses an App Installation to authenticate itself towards the Custom endpoint service. There is a guide available here on how to install an Application in the Conversational Cloud. Please contact the LivePerson account representative (other contact options: chat with us on this page, or message Support) to ensure you have already installed the app. The example payload for App Installation can be found below (Please note, the scope value as well, which should be thirdpartybots.customendpoint.bot. Third-Party Bots itself does not enforce the value yet. However, this is expected to change in a future release.)

{
  "client_name": "Custom Endpoint bot",
  "display_name": "Custom Endpoint bot",
  "enabled": true,
  "response_types": ["token"],
  "scope": "thirdpartybots.customendpoint.bot",
  "grant_types": ["client_credentials"]
}

Vendor Configuration

Once you have completed the prerequisite for Vendor configuration you can continue with the wizard.

Figure 1.1 Custom Endpoint Vendor Step

The following Custom Endpoint information should be provided to Third-Party Bots:

Item Description Example
Base URL Custom Endpoint service endpoint that will be called by Third-Party Bots. Read the Prerequisites for Vendor Configuration on this Page. Remove trailing / at the end of URLs. https://examplecustomendpoint.com/api
Client ID ID of the Installed App xxxxxxx-123e-xxxx-xxxx-xxxxxxx0441c
Client Secret Client Secret of the Installed App 1xxx2xxk7xxxx49r4xxxxx2qs
Bot ID Alphanumeric bot Identifier for the bot on the Custom Endpoint service. We recommend using UUIDs 1e9bebc6-0403-43a1-9a5e-2e17ca876568
Environment The environment of the bot that should be selected for communication with the Custom Endpoint service. Defaults to draft draft

You can also use the App Installation selector to fill-out the Client ID andClient Secret fields. If the selector contains no App Installations, then you have to install a Custom Endpoint Application. Contact your LivePerson account representative (other contact options: chat with us on this page, or message Support) for assistance if you need help in this regard.

You have to agree to the Data Disclaimer to use the services of the Third-Party Bots connector. For that, you can click on the checkbox "I agree to the Data Disclaimer"

Test Connection

For validation of the credentials provided, you can now perform a test connection request to see if everything that you have provided is working and reachable. You can click on the button "Test Connection" to see if the connection succeeds or fails.

Common use cases of the Custom Endpoint bot Test Connection failure can be the following:

  • Base URL is not responding as per the API Specification
  • Credentials provided are wrong e.g. wrong Client ID/Secret, Bot ID or Environment e.tc.
  • Bot state is not returned as online via the Get Bot State endpoint (defined in API Specification)

You will be able to save the configuration even if the test fails, but your bot will not be able to start successfully.

Figure 1.4 Showing the failure case when testing the connection.

Once you are done providing configuration you can save it by pressing "Done". Congratulations! You have completed the configuration of the Custom Endpoint bot.

Following guide is going to introduce how to implement functions for Custom Endpoint using reference of API Specification. Continue if you are familiar with how to implement a Custom Endpoint service.