Introduction

The following document outlines the Public API feature. This enhancement allows brands to takes actions directly on active conversations using provided API to give enriched experience for their customers. Using the API, Brands can take actions on the conversation that are not in direct response to a message passed to the bot. The API allows Brands to take proactive actions on a conversation and grow the usability of a bot in handling and owning the conversational flow with the consumer.

The API supports the following methods:

• Sending Messages
• Transfer Conversation
• Close Conversation
• Set SDEs
• Set Time to Response (TTR)

To use our API, your conversation/chat must be active/ongoing with bot(s) that are created via the Third-Party Bots. Otherwise, you will receive conversation not found the response from our API. Moreover, our API only retain the history of the last 200 commands. Furthermore, refer to the API Terms of Use.

Flow for using Public API

Step 1. Identify the Third-Party Bots API Domain

To identify the Third-Party Bots API endpoint for your account, first retrieve the domain information using the Domain Retrieval Tool. Enter your Account ID/Site ID in the tool, and it will display the relevant 'Service Names' and their Base URIs. Look for the thirdPartyBots service name in the list, then construct the API Base URI by using https:// followed by the retrieved domain information.

For example, if the thirdPartyBots domain is bot-platform-api.fs.liveperson.com, the corresponding API Base URI would be https://bot-platform-api.fs.liveperson.com.

Step 2. Create a Public API Bot User

In order to use Public API you must create a dedicated Public API bot agent/user via LivePerson User Management UI. You must not use this dedicated Public API agent/user user in any other LivePerson business process. For example, using the same Public API Bot Agent to create a Third-Party Bot or using this bot agent user to call other LivePerson APIs. The reason for this requirement is to ensure that the session created by the Public API is not invalidated by any other service/business process.

Figure 2.1 shows a simple scenario below where a dedicated Public API user is first making a login call and then sending message via Public API to an ongoing conversation connected happening in LP Messaging with a Third-Party bot.

Figure 2.1 Public API simple flow of sending messages command

Step 3. Get Bearer Token

To use our Public API you must perform a login request to Third-Party Bots API domain which will in response send you a Third-Party Bots bearer token. Moreover, you do not need to perform the login request multiple times. One successful login call will send a bearer that can be used with multiple commands of Public API. There are two ways in which you can perform the login.

• Bearer Token via Username/Password
• Bearer Token via API (OAuth)

To perform login requests you will need a valid and dedicated Public API bot user created via LivePerson User Management UI. User must be Enabled, have minimum Agent role and have the login method set either to Password or API Key as shown in Figure 3.1.

Please note LivePerson maintains one session per user, thus if you receive an invalid bearer token error from Public API, you can always generate a new bearer by performing the login request again. We require making a dedicated Public API Bot Agent user that is dedicated for your Public API call.

You should not use the same user that is already assigned to another bot since they would log each other out. If the user belongs to a bot that is active and running on Third-Party-Bots the login request will get rejected.

Figure 3.1 Showing two login methods of a Bot user

Bearer Token via Username/Password

In this method, a bot user must be created with Login method Password via the LivePerson User Management.

Request

Path Parameters

Query Parameters

Headers

Body

Example payload of the request. Please note the authType property is set to USER_PASS it is case-sensitive so should match exactly in your request.

{
    "authType": "USER_PASS",
    "credentials": {
        "username": "someuser",
        "password": "123456"
    }
}

Example cURL:

Make sure to replace {botDomain}, {accountId}, {userName} and {password} from the below command with your information

curl --location --request POST 'https://{botDomain}/api/v1/account/{accountId}/login?v=1.3' \
--header 'Content-Type: application/json' \
--data-raw '{
    "authType": "USER_PASS",
    "credentials": {
        "username": "{userName}",
        "password": "{password}"
    }
}'

Response:

{
  "bearer": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Bearer Token via API method (OAuth)

In this method, a bot user must be created with the Login method API Key via the LivePerson User Management. Moreover, make sure you have already generated your bot user's credentials before using them.

Request

Path Parameters

Query Parameters

Headers

Body

Example payload of the request. Please note the authType property is set to API_KEY it is case-sensitive so should match exactly in your request.

{
    "authType": "API_KEY",
    "credentials": {
      "username": "someusername",
      "appKey": "1234562ff0464127894f0",
      "secret": "1233f5bf456",
      "accessToken": "1233743ad8726e27456",
      "accessTokenSecret": "76d05123456"
  }
}

Example cURL:

Make sure to replace {botDomain}, {accountId}, {userName}, {appKey}, {secret}, {accessToken} and {accessTokenSecret} from the below command with your information

curl --location --request POST 'https://{botDomain}/api/v1/account/{accountId}/login?v=1.3' \
--header 'Content-Type: application/json' \
--data-raw '{
    "authType": "API_KEY",
    "credentials": {
        "username": "{username}",
        "appKey": "{appKey}",
        "secret": "{secret}",
        "accessToken": "{accessToken}",
        "accessTokenSecret": "{accessTokenSecret}"
    }
}'

Response:

{
  "bearer": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Step 4. Call API

Currently, the user is allowed to carry out following actions using our Public API

• Sending Messages
• Transfer Conversation
• Close Conversation
• Set SDEs
• Set Time to Response (TTR)

Send Messages

This API allows The user to send The message(s) to an ongoing conversation with bots created via Third-Party Bots. We support the sending of Text, Pause/Delay, Structured Content (more info), and Quick Replies. Moreover, We also allow sending of encodedMetadata and metadata/context information (more info) with the message(s) as well. Please note your conversation must be active and ongoing. You can't send messages to a closed conversation.

Request

Path Parameters

Query Parameters

Headers

Body

Example payload of the request with Simple Text, Pause/Delay, Private Text, Structured Content and Quick Replies messages with context information/metadata and encodedMetadata.

Quick Replies and encodedMetadata are only supported in messaging conversations. Moreover, You have to enable Private Message and Encoded Metadata feature for your account to successfully send such messages. Please contact LP administration if you need help in enabling Private Message and Encoded Metadata for your account. Moreover, If you want to send Structured Content make sure to follow the max size limit which is 15000 bytes.

{
  "context": {
    "intentId": "testId",
    "intentName": "test",
    "confidenceScore": 1
  },
  "messages": [
    "Hi I am a text message",
    {
      "delay": 4,
      "typing": true
    },
    {
      "structuredContent": {
        "quickReplies": {
          "type": "quickReplies",
          "itemsPerRow": 8,
          "replies": [
            {
              "type": "button",
              "tooltip": "yes I do",
              "title": "yes",
              "click": {
                "actions": [
                  {
                    "type": "publishText",
                    "text": "yep"
                  }
                ]
              }
            },
            {
              "type": "button",
              "tooltip": "No!",
              "title": "No!",
              "click": {
                "actions": [
                  {
                    "type": "publishText",
                    "text": "No!"
                  }
                ],
                "metadata": [
                  {
                    "type": "ExternalId",
                    "id": "No-4321"
                  }
                ]
              }
            }
          ]
        },
        "message": "Do you like bots?"
      },
      "metadata": [
        {
          "type": "ExternalId",
          "id": "1234566"
        }
      ],
      "encodedMetadata": "SGVsbG8gV29ybGQh"
    },
    {
     "text" :"this is a private message",
     "messageAudience": "AGENTS_AND_MANAGERS"
    },
    {
      "structuredContent": {
        "type": "vertical",
        "elements": [
          {
            "type": "button",
            "click": {
              "actions": [
                {
                  "text": "Recommend me a movie, please",
                  "type": "publishText"
                }
              ]
            },
            "title": "Recommend a movie"
          }
        ]
      },
      "metadata": [
        {
          "type": "ExternalId",
          "id": "123-YES"
        }
      ],
      "encodedMetadata": "SGVsbG8gV29ybGQh"
    }
  ]
}

Example cURL:

Make sure to replace {botDomain}, {accountId}, {conversationId} and {bearerToken} from the below command with your information

curl -X POST \
  'https://{botDomain}/api/v1/account/{accountId}/conversation/{conversationId}/messages' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {bearerToken}' \
  -d '{
  "context": {
    "intentId": "testId",
    "intentName": "test",
    "confidenceScore": 1
  },
  "messages": [
    "Hi I am a text message",
    "I am second message"
  ]
}'

Response Body

Transfer Conversation

This API allows an ongoing conversation to be transferred to another skill or an certain agent. User has to provide a skill name and optional an agentId that is created previously. The skill name is case-sensitive.

Request

Path Parameters

Query Parameters

Headers

Body

Example transfer to skill payload of the request with skill name human_skill.

The skill name is case-sensitive so provide with care

{
  "skill": "human_skill"
}

Example cURL:

Make sure to replace {botDomain}, {accountId}, {conversationId}, {bearerToken} and {skillName} from the below command with your information

curl -X POST \
  'https://{botDomain}/api/v1/account/{accountId}/conversation/{conversationId}/transfer' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {bearerToken}' \
  -d '{
  "skill": "{skillName}"
}'

Body

Example transfer to agent payload of the request with skill name human_skill and agentId 4129463410.

The skill name is case-sensitive so provide with care

{
  "skill": "human_skill",
  "agentId": "4129463410"
}

Example cURL:

Make sure to replace {botDomain}, {accountId}, {conversationId}, {bearerToken} and {skillName} from the below command with your information

curl -X POST \
  'https://{botDomain}/api/v1/account/{accountId}/conversation/{conversationId}/transfer' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {bearerToken}' \
  -d '{
  "skill": "{skillName}",
  "agentId": "4129463410"
}'

Response Body

Close Conversation

This API allows an ongoing conversation to be ended.

Request

Path Parameters

Query Parameters

Headers

Body

There is no request body for this API.

Example cURL:

Make sure to replace {botDomain}, {accountId}, {conversationId} and {bearerToken} from the below command with your information

curl -X POST \
  'https://{botDomain}/api/v1/account/{accountId}/conversation/{conversationId}/close' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {bearerToken}' \
  -d '{}'

Response Body

Set SDES

This API allows setting SDES of an ongoing conversation. More information about available SDES can be found here.

Request

Path Parameters

Query Parameters

Headers

Body

Example payload of the request with setting visitors name and gender

{
  "sdes": [
    {
      "type": "personal",
      "personal": {
        "firstname": "Muster",
        "lastname": "Mann",
        "gender": "MALE"
      }
    }
  ],
  "sharkVisitorId": "M0NG1231432YjgzZDcyN2U3",
  "sharkSessionId": "tx8LMk34242344yBHgrZ2qg"
}

Example cURL:

Make sure to replace {botDomain}, {accountId}, {conversationId}, {bearerToken}, {visitorId} and {sessionId} from the below command with your information

curl -X POST \
  'https://{botDomain}/api/v1/account/{accountId}/conversation/{conversationId}/sdes' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {bearerToken}' \
  -d '{
    "sdes": [
        {
            "type": "personal",
            "personal": {
                "firstname": "Muster",
                "lastname": "Mann",
                "gender": "MALE"
            }
        }
    ],
    "sharkVisitorId": "{visitorId}",
    "sharkSessionId": "{sessionId}"
}'

Response Body

Set Time to Response (TTR)

LivePerson Messaging uses 3 different types of priorities: URGENT, NORMAL, PRIORITIZED. This API allows setting TTR for the ongoing conversation.

Setting of TTR is supported only for messaging conversation

Request

Path Parameters

Query Parameters

Headers

Body

Example payload of the request with setting conversation ttr to Urgent

{
  "ttrType": "URGENT"
}

Example cURL:

Make sure to replace {botDomain}, {accountId}, {conversationId} and {bearerToken} from the below command with your information.

curl -X POST \
  'https://{botDomain}/api/v1/account/{accountId}/conversation/{conversationId}/ttr' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {bearerToken}' \
  -d '{
 "ttrType": "URGENT"
}'

Response Body

Make Bot join a Conversation

A Third-Party Bot can be added to existing on-going conversation with other Third-Party Bot

The bot needs agent manager permission to be able to join.

Request

Path Parameters

Headers

Body

Example payload of the request with setting agentMessage that will send on conversation join.

{
  "agentId": "1234567",
  "agentMessage": "Hi there i am there to assist you"
}

Example cURL:

Make sure to replace {botDomain}, {accountId}, {conversationId}, {agentId}, {agentMessage} and {bearerToken} from the below command with your information.

curl --location --request POST 'https://{botDomain}/api/v1/account/{accountId}/conversation/{conversationId}/joinConversation' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {bearerToken}' \
-d '{
  "agentId":"{agentId}",
  "agentMessage": "{agentMessage}"
  }'

Response Body

Remove Bot from a Conversation

A Third-Party Bots bot can be removed from a conversation

Request

Path Parameters

Headers

Body

The example payload of the request is as follows:

{
  "agentId": "1234567",
  "agentMessage": "I am glad i helped you. Goodbye"
}

agentMessage will be sent before leaving the conversation

Example cURL:

Make sure to replace {botDomain}, {accountId}, {conversationId}, {agentId}, {agentMessage} and {bearerToken} from the below command with your information.

curl --location --request POST 'https://{botDomain}/api/v1/account/{accountId}/conversation/{conversationId}/removeAgent' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {bearerToken}' \
-d '{
  "agentId":"{agentId}",
  "agentMessage": "{agentMessage}"
  }'

Response Body

Get Conversation Commands

This API allows returning of the commands that were sent to a conversation via Public API.

Our API only retains the history of last 200 commands per bot/agent. Only commands of ongoing conversation will be returned AND if they are found in the history of the last 200 commands. If a conversation is closed/ended or doesn't exist in history then commands will not be returned.

Request

Path Parameters

Headers

Example cURL:

Make sure to replace {botDomain}, {accountId}, {conversationId} and {bearerToken} from the below command with your information.

curl -X GET \
  https://{botDomain}/api/v1/account/{accountId}/conversation/{conversationId}/command \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {bearerToken}' \

Example Response

Example response of an request with Array of commands returned.

there could be three states of a command: waiting (command execution pending), failed (command execution caused an error) and completed (command executed successfully)

[
  {
    "id": "24",
    "data": {
      "type": "sdes",
      "payload": {
        "sdes": [
          {
            "type": "personal",
            "personal": {
              "gender": "Male"
            }
          }
        ],
        "sharkSessionId": "sadjkasdhi23D-P6BbaFRsBkA",
        "sharkVisitorId": "dladji38dsda"
      },
      "conversationId": "2312ed0e-662e-4c94-9022-f0991058b4a4",
      "isInternal": true,
      "timeoutTime": 1580396820804
    },
    "result": null,
    "state": "waiting"
  },
  {
    "id": "23",
    "data": {
      "type": "messages",
      "payload": [
        {
          "payload": "Hi I am a text message",
          "metadata": [],
          "type": "text"
        }
      ],
      "conversationId": "2312ed0e-662e-4c94-9022-f0991058b4a4",
      "isInternal": true,
      "timeoutTime": 1580474718054
    },
    "result": {
      "error": {
        "trace": [],
        "name": "com.liveperson.bot-connectors-worker.error.public-api.execution-failed"
      },
      "startTime": 1580637839412,
      "endTime": 1580637839412,
      "executionTime": 0
    },
    "state": "failed"
  },
  {
    "id": "21",
    "data": {
      "type": "sdes",
      "payload": {
        "sdes": [
          {
            "type": "personal",
            "personal": {
              "firstname": "Muster",
              "lastname": "Frau"
            }
          }
        ],
        "sharkSessionId": "sadjkasdhi23D-P6BbaFRsBkA",
        "sharkVisitorId": "dladji38dsda"
      },
      "conversationId": "2312ed0e-662e-4c94-9022-f0991058b4a4",
      "isInternal": true,
      "timeoutTime": 1580396820804
    },
    "result": {
      "executionTime": 405,
      "startTime": 1580396700808,
      "endTime": 1580396701213
    },
    "state": "completed"
  }
]

Get Conversation Command

This API allows returning of a single command that was sent to a conversation via Public API.

Our API only retains the history of last 200 commands per bot/agent. Only command of ongoing conversation will be returned AND if they are found in the history of the last 200 commands. If a conversation is closed/ended or doesn't exist in history then command will not be returned.

Request

Path Parameters

Headers

Example cURL:

Make sure to replace {botDomain}, {accountId}, {conversationId}, {bearerToken} and {commandId} from the below command with your information.

curl -X GET \
  https://{botDomain}/api/v1/account/{accountId}/conversation/{conversationId}/command/{commandId} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {bearerToken}' \

Example Response

Example response of a command returned by the API will look like this with state completed

there could be three states of a command: waiting (command execution pending), failed (command execution caused an error) and completed (command executed successfully). See example response of GET Commands API to see other examples of different states.

{
  "id": "21",
  "data": {
    "type": "sdes",
    "payload": {
      "sdes": [
        {
          "type": "personal",
          "personal": {
            "firstname": "Muster",
            "lastname": "Frau"
          }
        }
      ],
      "sharkSessionId": "sadjkasdhi23D-P6BbaFRsBkA",
      "sharkVisitorId": "dladji38dsda"
    },
    "conversationId": "2312ed0e-662e-4c94-9022-f0991058b4a4",
    "isInternal": true,
    "timeoutTime": 1580396820804
  },
  "result": {
    "executionTime": 405,
    "startTime": 1580396700808,
    "endTime": 1580396701213
  },
  "state": "completed"
}

Response Codes

Limitations

• To ensure the safety of the API we are using Reblaze. if the request throws Security Violation Error (403 — Forbidden) the reason could be that your request body contains information that caused Reblaze to mark your request positive as a security risk. To understand security concepts of Reblaze please refer to the official documentation here. You can also refer to the information on best practices to avoid the false positives marking of valid request here
• Our Public API only retains a maximum of last 200 commands per bot/agent. Thus, there could be a possibility that an ongoing conversation will not be able to fetch the commands due to this max. commands retention policy.