This document explains how to invoke functions directly from your own systems. This external invocation capability allows you to trigger your functions from outside the LivePerson platform.

Authentication and Authorization

To invoke a function externally, your application must authenticate with the LivePerson platform using OAuth 2.0. This ensures only authorized clients can execute functions. While some internal LivePerson services might use OAuth 1.0, all external applications must use OAuth 2.0.

The overall authorization process is as follows:

1. Obtain API keys (client_id and client_secret) for your application.
2. Choose the appropriate OAuth 2.0 grant type for your use case.
3. Discover the correct domains for the LivePerson services you need to call.
4. Request an access_token from the LivePerson authorization server.
5. Use the access_token to authenticate your API requests to the Function's Invocation Gateway.

Step 1: Obtain API Keys

The client_id and client_secret are generated during the App Installation process. Since this is not a self-service process, please contact your LivePerson account representative to have an application configured. You will need to provide a configuration JSON based on one of the templates below.

Template for client_credentials grant type (for M2M communication):

{
  "client_name": "YOUR APP NAME",
  "description": "A short description",
  "grant_types": [
    "client_credentials"
  ],
  "response_types": ["token"],
  "scope": "faas.lambda.invoke"
}

Template for authorization_code grant type (for acting on behalf of a user):

{
  "client_name": "YOUR APP NAME",
  "description": "A short description",
  "grant_types": [
    "authorization_code"
  ],
  "response_types": ["code"],
  "scope": "faas.lambda.invoke",
  "redirect_uris": [
    "http://{YOUR_APPLICATION_DOMAIN}/{CALLBACK_PATH}"
  ]
}

Step 2: Choose an OAuth 2.0 Grant Type

We support the following grant types from the OAuth 2.0 specification:

1. Client Credentials: This is the preferred way to authorize machine-to-machine (M2M) communication. Choose this option if you are calling functions from an automated system or backend service.
2. Authorization Code: This is a redirect-based flow. Use this grant type if you want to call Functions on behalf of a Conversational Cloud user, such as an Agent or Administrator.

For a great introduction to OAuth 2.0, we recommend this YouTube Video.

Step 3: Discover Service Domains

Your application will need to interact with two main services: the Authorization Server (Sentinel) and the Invocation Gateway (FaaS Gateway). The recommended way to find the correct domains for your account is by using the Service Discovery API.

Invocation Gateway Domains (faasGW)

The Invocation Gateway is the main entry point for the invocation flow. Use the Service Discovery API to find the domain for the faasGW service.

Authorization Server Domains (sentinel)

The Authorization Server validates your API keys and issues access tokens. Use the Service Discovery API to find the domain for the sentinel service.

Step 4: Request an Access Token

With your API keys and the correct domains, you can now request an access token.

The Access Token has a fixed lifespan. To extend it, you will need to refresh it using the Refresh Token with the Refresh API.

Client Credentials Flow

1. Request an Access Token and Refresh Token using the Token API, your sentinel domain, client_id, and client_secret. Ensure the grant_type is set to client_credentials.
2. Use the returned Access Token to make authenticated calls to the Invocation Gateway.

Authorization Code Flow

1. Perform an Authorization Request using your sentinel domain, client_id, and redirect_uri.
2. A user with FaaS invocation privileges must log in to the Conversational Cloud.
3. After successful login, the user will be redirected to your redirect_uri with an Authorization Code.
4. Exchange this code for an Access Token and Refresh Token using the Token API.
5. Use the returned Access Token to make authenticated calls.

Our Authorization Code flow example application provides a helpful demonstration of the Authorization Code flow in JavaScript.

Invoking a Function

Once authenticated, you can invoke a function by sending a request to the Invocation Gateway.

Function UUID

To invoke a specific function, you must include its UUID in the request URL. You can find the UUID for any function on its "Invoke" screen in the LivePerson Functions UI.

Invocation API

To simplify interaction with our platform, we provide official client libraries for Java and JavaScript. These clients handle the complexities of authentication and request signing. See our Error Codes & HTTP Responses for details on handling responses.

Java Client

Our Java client is available on Maven Central. Add it to your project with the following snippet:

<dependency>
    <groupId>com.liveperson.faas</groupId>
    <artifactId>Functions-client</artifactId>
    <version>x.x.x</version>
</dependency>

The client exposes several methods:

• invokeByUUID: Invokes a productive function by its UUID.
• invokeByEvent: Invokes all productive functions listening to a specific event.
• isImplemented: Checks if a function (by UUID) or an event has a productive deployment. Verifying this before invoking is a best practice.
• getLambdas: Returns all functions and their states for the account.

Error Handling

Exceptions are typically wrapped in a FaaSException object.

• FaaSDetailedException occurs when the Functions service rejects a request (e.g., the function UUID does not exist). Use the getFaaSError() method for details.
• FaaSLambdaException is raised if the error is caused by the function's implementation (e.g., a timeout or a purposeful error response).

We recommend monitoring for FaaSException or FaaSDetailedException and logging the full stack trace for any resulting exception to get detailed information.

For detailed documentation and to report issues, please visit the Java Client GitHub repository.

JavaScript Client

Our JavaScript client is available on NPM. Install it using npm or yarn:

$ yarn add @liveperson/functions-client
# or
$ npm install @liveperson/functions-client

The client exposes the following methods:

• invoke: Invokes a function by its UUID or all functions listening to a specific event.
• isImplemented: Checks if a function (by UUID) or an event is implemented. Checking this before invoking is a best practice.
• getLambdas: Returns all functions and their states for the account.

Error Handling

Errors related to the function's implementation will be raised with the name FaaSLambdaError. The client uses verror internally; therefore, we recommend logging the full stack to get detailed information about the root cause. A list of possible error causes can be found in the error codes documentation.

try {
  // ... your invocation logic
} catch (error) {
  /**
   * FaaSLambdaErrors occur when the function fails due to its implementation.
   * These are not service issues and typically should not trigger alerts.
   */
  if (error.name === "FaaSLambdaError") {
    console.info(error.stack, "Error caused by function implementation.");
  } else {
    console.error(error.stack, "An unexpected error occurred.");
  }
}

For detailed documentation and to report issues, please visit the JavaScript Client GitHub repository.