This repository showcases the Third Party Bots Custom Endpoint API. It also represents the single point of truth for the API specification.

Note: code in this repository is for demonstration purpose ONLY please do not use this code in production scenario. We have used local caching for storing/retrieving information which can effect the server memory usage.

The OpenAPI specification can be found under the directory docs/v1.json. Furthermore, service implementation also contains Interfaces defined at locations src/controllers/requestBodies and src/controllers/responseBodies for Request and Response bodies respectively.

Note: Detailed concepts of Service Implementation can be found in the official documentation of Custom Endpoint here

This section define some basic concepts of Custom Endpoint Reference Service specification. The specification describes a REST API that can support different versions of multiple bots. The URL for a bot instance looks like the following example:

{BaseUrl}/v1/bots/{BotId}/environments/{EnvironmentId}

Api versions as part of the URL are following the schema "v{x}" without any leading zeros. For the time being only v1 has been defined and needs to be supported. We enforce that it should be included in all endpoints.

Third-Party Bots will authenticate its requests to the Custom Endpoint API by sending a signed JWT generated using private conversational cloud applications.

A bot is identified by its UUID or a similar alphanumeric identifier. A service implementation can restrict access to bots based on the accountId provided as the 'aud' field on the authentication WebToken

Every bot can have multiple versions with different conversational flows and intents. To address this the API should provide at least one standard environment named draft for each bot. Further environments can be provided as needed. A bot environment will report the currently deployed bot version and its state. A bot environment should report it's state as online or otherwise the bot connection test will fail in Third-Party Bots. A bot environment should report a Semantic Version that describes what version of the bot (conversational flow, intents, etc) is deployed on this environment

Conversation will be created for a specific bot on an environment and are addressed by the LP conversation id. Additional context like SDES and conversation details are provided on the creation of the conversation.

An Event describes content send by a participant on a conversation (only the customer at this point) or events generated by the conversation itself (started/ended/(transferred))

A Bot response itself does not have its own resource. It is expected to be sent by the API on the response body at the creation of a new event resource. At the moment getting historic data on the conversation or any details on the conversation are not considered part of the specification and might only be optionally implemented by services.

• 📂 third-party-bots-custom-endpoint-reference-service-public
  • 📄 Dockerfile Docker definition
  • 📄 nodemon.json Nodemon configuration
  • 📄 package.json Packages definitions
  • 📂 docs
    • 📄 v1.json Swagger OpenAPI 3.0 Schema definition
  • 📂 src
    • 📂 configs
      • 📄 app.ts ...Contains the Application configs
    • 📂 controllers ...Contains Routes definitions
      • 📂 requestBodies ...Contains Request bodies definition
      • 📂 responseBodies ...Contains Response bodies definition
    • 📄 index.ts Service entry point file
    • 📂 helpers
      • 📄 AuthorizationChecker.ts Authorization Checker module
    • 📂 middlewares
      • 📄 SecurityMiddleware.ts Security Middleware for Auth
    • 📂 models ...Contains service interface definitions and Bots models
    • 📂 services
      • 📄 BotService.ts Implements Bot related CRUD methods using Cache
      • 📄 LivePersonService.ts LivePerson APIs call
    • 📂 utils
      • 📄 Cache.ts Implements a simple Cache Singleton Class
      • 📄 Response.ts Implements a mapping of responses for Events
  • 📄 tsconfig.json TypeScript configuration file
  • 📄 yarn.lock lock files of dependencies

This service requires Node.js v16+ to run, TypeScript v4.7.3+ to compile and run and nodemon v 2.0.16+ to run locally in development mode.

Note: Please make sure your application configurations are valid. For Example, You must check if your Sentinel V1 OAuth Public key is valid for the zone in which you are developing service Check the src/configs/app.ts file fore more information. Currently, The public key in configuration will work for all production enviorments. If you are working with Alpha or QA you need to change those keys. Contact LivePerson representative in case you need assistance with other enviorments keys.

Install the dependencies and devDependencies and start the server in development mode.

yarn install
yarn dev

For production environments

yarn install
yarn start

For building the package

yarn build

For cleaning the old build

yarn clean

Service is very easy to install and deploy in a Docker container.

By default, the Docker will expose port 4004, so change this within the Dockerfile if necessary. When ready, simply use the Dockerfile to build the image.

docker build -t tpb_custom_endpoint_service .

Once done, run the Docker image and map the port to whatever you wish on your host. In this example, we simply map port 4004 of the host to port 4004 of the Docker (or whatever port was exposed in the Dockerfile):

docker run -d -p 4004:4004 tpb_custom_endpoint_service

• Contains implementation of v1 of the Custom Endpoint API specification
• Contains supported Bot response examples.
• Contains the OpenAPI specification (found under /src/docs/)
• Contains local caching for the calls to the LivePerson APIs

in this service implementation we have configured some example bots manually that can be used in Vendor config setup (please make sure to use bot with online state). Implementation of such model generation can be found here. List of available bots is as follows:

• 5809777a-e548-4bd2-bc5f-a1003c132a28 - Bot with online state
• 36d5de7f-6c83-41ba-836d-28ca1062c1ef - Bot with offline state
• 42773157-adcf-4ec1-a2ae-9b935d80cb81 - Bot with error state
• 213aa6c6-f6d9-11ec-b939-0242ac120002 - Bot with draft state
• bfb807d6-f6d8-11ec-b939-0242ac120002 - Bot with maintenance state

In this service implementation we have configured some Bot Responses that are supported by Third-Party Bots. These responses are defined in src/utils/Response.ts. On sending customer utterances (as shown in below table) this service will send response:

Note: You will need to change response configuration as per your use case in method getTransferAction present in the src/utils/Response.ts. You will need to add your own skillName to which transfer action should happen.

Following utterances will generate Transfer Action

• escalate
• transfer
• i want to talk to human
• i want to speak to a human

Following utterances will generate Close Action

• bye
• close
• close conversation
• goodbye

Following utterances will generate Change TTR Action

• urgent help
• urgent
• need help now
• need help

Note: You will need to change response configuration as per your use case in method getInvokeFunctionAction present in the src/utils/Response.ts. You will need to add your own lambdaUuid and payload for the function you want to invoke with this method

Following utterances will generate FaaS Action

• faas
• invoke function
• invoke
• function call

Following utterances will generate Structured Content response

• structured content
• rich content

Following utterances will generate delay response

• delay
• send delay
• delay response

Note: This response is only supported in Messaging Conversation

• quick replies
• quick replies example

• private text
• private text example

Note: This response is only supported in Messaging Conversation. More information on this can be found here

Any Rich Content passed via customer will be rendered with all the raw data

Note: This response is only supported in Messaging Conversation. More information on this can be found here

When the Welcome Message option is enabled in the Conversation Type step of the bot creation wizard, the service will receive an event labeled as START. This event includes the lastConsumerMessage within the lpEvent property, located in the context.

Note: This response is only supported in Survey Bots Conversation

Event with type CLOSE_CONVERSATION will cause changes to respond with Survey Close event

This mostly happen if you are using Sentinel V1 for auth implementation. If you are receiving the invalid signature error on request to the service this usually means you need to update the V1_PUBLIC_KEY config in app.ts file.

Please keep in mind that public keys are different for accounts zone (Alpha, QA, Production). If you are developing Custom Endpoint Service please ensure that you are using valid Public Key for your zone. If Public API Key is not valid you will get 401 error response and SecurityMiddleware.ts implementation will not be able to verify the JWT. The current v1 public key in the code is of Production enviorment. You will need to change it to test against QA and Alpha. If you are not sure about this please ask Customer Representative of LivePerson for your account to help you with this.

MIT