logo
API docs by Redocly

Messaging REST API V1 (1.0.0)

Download OpenAPI specification:Download

Introduction

Welcome to the API Documentation of Messaging REST API. This API provides a broad set of endpoints to access and manage Conversation lifecycle resources.

Usage Guidelines

Base Domain

Use the LivePerson Domain API to retrieve this information by providing the following service name messagingRestApiDomain. The base path for all calls to this API should be https://{messagingRestApiDomain}/messaging.

Authentication

consumerJWTBearerAuth

This mode of authentication is for Consumer clients. It uses the same JWT token as the consumer window currently uses for authentication on the UMS Websocket API. It requires the Authorization header be set in the following format:

  • Bearer <JWT Token>

Follow this documentation for details on how to generate these tokens.

Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer
Bearer format: JWT

appJWTandConsumerJWSAuth

This mode of authentication is meant for server-to-server authorization, where the client is calling on behalf of a Consumer. It is the same authentication method currently used for the SendAPI. It requires two headers to be set

  • Authorization - should contain the AppJWT,
  • LP-On-Behalf - should contain the ConsumerJWS.

Follow this documentation for details on how to generate these headers.

Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer
Bearer format: JWT

agentBearerAuth

This mode of authentication is for Agent/Bot clients. It uses the same bearer token that agents currently use for authentication on the UMS Websocket API. It requires the Authorization header be set in the following format

  • Bearer <Agent Bearer Token>
Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer

Required Headers

All API endpoints require the following headers to be present

  • Authorization - see Authentication section for supported Authentication/Authorization modes supported
  • Brand-ID - Brand or Account ID
  • Client-source - Specifies the client source. This is a free-text field used to describe the client application, such as its name or type (e.g., "mobile-banking-app")

In addition we also recommend that you pass the Request-ID header with every request. This helps with traceability and troubleshooting failures

Rate Limits

All REST API endpoints have quotas per brand. When any brand exceeds the configured quota, the API will return a 429 response code. Follow the LivePerson Retry Policy Recommendation for handling 429 or any error response in general.

Consumers and Agents

Consumers and Agents are the actors or Participants in a Conversation. This group of API endpoints are for operations on Consumers and Agents resources.

Create or Replace Consumer

Saves the Consumer user profile in UMS.
This is equivalent to the SetUserProfile API for WebSockets.

Authorizations:
consumerJWTBearerAuthappJWTandConsumerJWSAuth
path Parameters
consumer_id
required
string

The Consumer ID

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Content-Type
required
string
Example: application/json

The Content-Type header is used to indicate the media type of the resource.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

If-Match
string
Example: {{ConsumerEtag}}

Required if this is an update rather than first time creation.
Should match the 'Etag' header from the last GET or PUT.

Request Body schema: application/json
firstName
string (firstName)

The Consumer's first name

lastName
string (lastName)

The Consumer's last name

nickName
string (nickName)

The Consumer's nick name

brandId
string (brandId)

LivePerson account or site ID for this brand

description
string (description)

Brief description about the Consumer or additional information

avatarUrl
string (avatarUrl)

Pending

backgndImgUrl
string (backgndImgUrl)

Pending

email
string (email)

The Consumer's email

mobileNumber
string (mobileNumber)

The Consumer's mobile number

object (claims)

Claims associated with this Consumer set by the Brand. This includes SDEs.

acr
string (acr)

The Authentication Context Class Reference (or authentication level) of this Consumer. A value '0' means Unauthenticated, and a value of 'loa1' means Authenticated.

object (PNData)

PushNotificationData

Responses

Request samples

Content type
application/json
Example
{
  • "firstName": "John",
  • "lastName": "Smith",
  • "brandId": "b123456789",
  • "mobileNumber": "5551234560",
  • "email": "john.smith@liveperson.com",
  • "claims": {
    },
  • "pnData": {
    },
  • "acr": "l01",
  • "createdTs": "2023-05-24T06:07:11.767+00:00",
  • "lastUpdatedTs": "2023-05-24T06:07:11.775+00:00"
}

Response samples

Content type
application/json
Example
{
  • "firstName": "John",
  • "lastName": "Smith",
  • "brandId": "b123456789",
  • "mobileNumber": "5551234560",
  • "email": "john.smith@liveperson.com",
  • "claims": {
    },
  • "pnData": {
    },
  • "acr": "l01",
  • "createdTs": "2023-05-24T06:07:11.767+00:00",
  • "lastUpdatedTs": "2023-05-24T06:07:11.775+00:00"
}

Get Consumer By Id

Fetches the Consumer user profile persisted in UMS.
This is equivalent to the GetUserProfile API for WebSockets.

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
consumer_id
required
string

The Consumer ID

query Parameters
fields
string
Examples:
  • fields=id - Get ID field only
  • fields=id,pnData.token - Get nested fields

List of fields to include in the response. Fields must be separated by a comma.

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
Example
{
  • "firstName": "John",
  • "lastName": "Smith",
  • "brandId": "b123456789",
  • "mobileNumber": "5551234560",
  • "email": "john.smith@liveperson.com",
  • "claims": {
    },
  • "pnData": {
    },
  • "acr": "l01",
  • "createdTs": "2023-05-24T06:07:11.767+00:00",
  • "lastUpdatedTs": "2023-05-24T06:07:11.775+00:00"
}

Get Agent By Id

Authorizations:
agentBearerAuth
path Parameters
agent_id
required
string

The Agent ID

query Parameters
fields
string
Examples:
  • fields=id - Get ID field only
  • fields=id,pnData.token - Get nested fields

List of fields to include in the response. Fields must be separated by a comma.

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "id": "b123456789.1234567890",
  • "firstName": "John",
  • "nickName": "Doe",
  • "brandId": "b123456789",
  • "email": "john.doe@gmail.com",
  • "maxSlots": 4,
  • "skillIds": [
    ],
  • "permissionGroups": [ ],
  • "memberOf": 4120323310,
  • "managerOf": [ ],
  • "employeeId": 12345,
  • "userTypeId": 1,
  • "active": false,
  • "pnData": {
    },
  • "lpa": false
}

Conversations

A Conversation captures a messaging interaction between a Consumer and a Brand. Typically the Consumer is on one end of the Conversation, and the Brand is represented by either an Agent, Bot, or both.

Consumer Create Conversation

Creates a new Conversation in UMS with the Consumer as a participant.

Authorizations:
consumerJWTBearerAuthappJWTandConsumerJWSAuth
path Parameters
consumer_id
required
string

The Consumer ID

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Content-Type
required
string
Example: application/json

The Content-Type header is used to indicate the media type of the resource.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

LP-Metadata
string
Example: [{"type":"ActionReason","reason":"some reason","reasonId":"some reason Id"}]

Needs to conform to the metadata json schema.

Request Body schema: application/json
skillId
string (skillId)

The Skill ID

CustomContext (object) or FacebookContext (object) or MobileAppContext (object) or ProactiveContext (object) or SharkContext (object) or SMSContext (object) or VoiceContext (object)

Describes the conversation environment, like where from it was created and by whom

channelType
string (channelType)
Enum: "MESSAGING" "LIVE_CHAT" "COBROWSE"

The Channel Type

object (campaignInfo)

The Campaign Information contains the campaignId and engagementId

Responses

Request samples

Content type
application/json
Example
{
  • "skillId": "4119939010",
  • "context": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "f798af10-c64f-47fa-ab39-4928d3271a40",
  • "createdTs": "2022-06-10T19:16:09.947+00:00",
  • "lastUpdatedTs": "2022-06-10T19:16:09.947+00:00",
  • "brandId": "le84625337",
  • "skillId": "4119939010",
  • "state": "OPEN",
  • "stage": "OPEN",
  • "note": "",
  • "dialogs": [
    ],
  • "context": {
    },
  • "ttr": {
    },
  • "csat": {
    },
  • "conversationRollOverHandler": {
    }
}

Get Conversations of Consumer

Returns all conversations where the given Consumer was a participant.

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
consumer_id
required
string

The Consumer ID

query Parameters
limit
integer

Number of records to return (default 100)

offset
integer

The number of items to skip before starting to collect the result set (default 0)

sortBy
string
Default: "createdTs"
Enum: "createdTs" "lastUpdatedTs"

Name of the field by which to sort the result set.

sortOrder
string
Default: "DESC"
Enum: "ASC" "DESC"

Allows to order the result set in ascending or descending order

filters
string
Examples:
  • filters=%7B%22stage%22%3A%22OPEN%22%7D - Get OPEN Conversations only

Any filters to apply on the collection. This needs to be in a URL encoded json string. For example {"stage":"OPEN"} should be passed as %7B%22stage%22%3A%22OPEN%22%7D

fields
string
Examples:
  • fields=id - Get ID field only
  • fields=id,dialogs.state - Get nested fields

List of fields to include in the response. Fields must be separated by a comma.

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get Consumer Conversation Count

Returns conversation count where the given Consumer was a participant.

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
consumer_id
required
string

The Consumer ID

query Parameters
filters
string
Examples:
  • filters=%7B%22stage%22%3A%22OPEN%22%7D - Get OPEN Conversations only

Any filters to apply on the collection. This needs to be in a URL encoded json string. For example {"stage":"OPEN"} should be passed as %7B%22stage%22%3A%22OPEN%22%7D

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
"Empty Body"

Get Conversation By Id

Returns a single Conversation with given ID.

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

query Parameters
fields
string
Examples:
  • fields=id - Get ID field only
  • fields=id,dialogs.state - Get nested fields

List of fields to include in the response. Fields must be separated by a comma.

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "brandId": "string",
  • "skillId": "string",
  • "state": "OPEN",
  • "stage": "OPEN",
  • "closeReason": "CONSUMER",
  • "note": "string",
  • "dialogs": [
    ],
  • "context": {
    },
  • "channelType": "MESSAGING",
  • "ttr": {
    },
  • "campaignInfo": {
    },
  • "csat": {
    },
  • "delay": {
    },
  • "manualETTR": 0,
  • "conversationRollOverHandler": {
    },
  • "createdTs": "2019-08-24T14:15:22Z",
  • "lastUpdatedTs": "2019-08-24T14:15:22Z"
}

Update Conversation

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

If-Match
required
string
Example: {{ConversationEtag}}

Should match the 'Etag' header from the last POST, GET or PUT.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
One of
note
string (note)

Additional Information

Responses

Request samples

Content type
application/json
Example
{
  • "note": "New note for conversation"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "brandId": "string",
  • "skillId": "string",
  • "state": "OPEN",
  • "stage": "OPEN",
  • "closeReason": "CONSUMER",
  • "note": "string",
  • "dialogs": [
    ],
  • "context": {
    },
  • "channelType": "MESSAGING",
  • "ttr": {
    },
  • "campaignInfo": {
    },
  • "csat": {
    },
  • "delay": {
    },
  • "manualETTR": 0,
  • "conversationRollOverHandler": {
    },
  • "createdTs": "2019-08-24T14:15:22Z",
  • "lastUpdatedTs": "2019-08-24T14:15:22Z"
}

Agent Resume/Create Conversation

Resumes a closed Conversation in UMS with the given Consumer and Agent as participants. A new conversation will always be created even if the origin conversation does not exist.

Authorizations:
agentBearerAuth
path Parameters
agent_id
required
string

The Agent ID

query Parameters
consumerId
required
string

Consumer's ID from the origin conversation

optInRequired
boolean

Pending

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Content-Type
required
string
Example: application/json

The Content-Type header is used to indicate the media type of the resource.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

LP-Metadata
string
Example: [{"type":"ActionReason","reason":"some reason","reasonId":"some reason Id"}]

Needs to conform to the metadata json schema.

Request Body schema: application/json
skillId
string (skillId)

The Skill ID

object (ProactiveContext)

Responses

Request samples

Content type
application/json
{
  • "skillId": "4119939010",
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "id": "f798af10-c64f-47fa-ab39-4928d3271a41",
  • "createdTs": "2022-06-10T19:16:09.947+00:00",
  • "lastUpdatedTs": "2022-06-10T19:16:09.947+00:00",
  • "brandId": "le84625337",
  • "skillId": "4119939010",
  • "state": "OPEN",
  • "stage": "OPEN",
  • "note": "",
  • "dialogs": [
    ],
  • "context": {
    },
  • "ttr": {
    },
  • "csat": {
    },
  • "conversationRollOverHandler": {
    }
}

Get Conversations of Agent

Returns all conversations where the given Agent was a participant.

Authorizations:
agentBearerAuth
path Parameters
agent_id
required
string

The Agent ID

query Parameters
limit
integer

Number of records to return (default 100)

offset
integer

The number of items to skip before starting to collect the result set (default 0)

sortBy
string
Default: "createdTs"
Enum: "createdTs" "lastUpdatedTs"

Name of the field by which to sort the result set.

sortOrder
string
Default: "DESC"
Enum: "ASC" "DESC"

Allows to order the result set in ascending or descending order

filters
string
Examples:
  • filters=%7B%22stage%22%3A%22OPEN%22%7D - Get OPEN Conversations only

Any filters to apply on the collection. This needs to be in a URL encoded json string. For example {"stage":"OPEN"} should be passed as %7B%22stage%22%3A%22OPEN%22%7D

fields
string
Examples:
  • fields=id - Get ID field only
  • fields=id,dialogs.state - Get nested fields

List of fields to include in the response. Fields must be separated by a comma.

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get Agent Conversation Count

Returns conversation count where the given Agent was a participant.

Authorizations:
agentBearerAuth
path Parameters
agent_id
required
string

The Agent ID

query Parameters
filters
string
Examples:
  • filters=%7B%22stage%22%3A%22OPEN%22%7D - Get OPEN Conversations only

Any filters to apply on the collection. This needs to be in a URL encoded json string. For example {"stage":"OPEN"} should be passed as %7B%22stage%22%3A%22OPEN%22%7D

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
"Empty Body"

Get Conversations of Brand

Returns all conversations for the given Brand.

Authorizations:
agentBearerAuth
query Parameters
limit
integer

Number of records to return (default: 100, max: 1000)

offset
integer

The number of items to skip before starting to collect the result set (default 0)

sortBy
string
Default: "createdTs"
Enum: "createdTs" "lastUpdatedTs"

Name of the field by which to sort the result set.

sortOrder
string
Default: "DESC"
Enum: "ASC" "DESC"

Allows to order the result set in ascending or descending order

filters
string
Examples:
  • filters=%7B%22stage%22%3A%22OPEN%22%7D - Get OPEN Conversations only

Any filters to apply on the collection. This needs to be in a URL encoded json string. For example {"stage":"OPEN"} should be passed as %7B%22stage%22%3A%22OPEN%22%7D

fields
string
Examples:
  • fields=id - Get ID field only
  • fields=id,dialogs.state - Get nested fields

List of fields to include in the response. Fields must be separated by a comma.

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get Brand Conversation Count

Returns the conversation count for the given Brand.

Authorizations:
agentBearerAuth
query Parameters
filters
string
Examples:
  • filters=%7B%22stage%22%3A%22OPEN%22%7D - Get OPEN Conversations only

Any filters to apply on the collection. This needs to be in a URL encoded json string. For example {"stage":"OPEN"} should be passed as %7B%22stage%22%3A%22OPEN%22%7D

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
"Empty Body"

Dialogs and Participants

A Dialog is a bounded exchange of messages between Participants within the context of a Conversation. A conversation can have multiple Dialogs. For example a MAIN dialog (which contains the exchange of messages between the Consumer and Agent), then a second POST_SURVEY dialog for collecting the Customer Satisfaction score.

Add Participant to Dialog

Add a Participant, with the specified role, to the specified Dialog. This endpoint also works for the Consumer Step Up flow.

Authorizations:
agentBearerAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

dialog_id
required
string (dialogId)

The Dialog ID

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
id
required
string

The User ID of the Participant. If Agent, the ID should be sent as {brand_id}.{agent_id}

role
required
string
Enum: "CONSUMER" "ASSIGNED_AGENT" "AGENT" "MANAGER" "READER" "BRAND_BOT" "CONTROLLER"

The Role that this Participant should assume. Sending the CONSUMER role will be considered as a request for the Consumer Step Up flow.

state
string (participantState)
Enum: "ACTIVE" "SUGGESTED"

The Participant State

Responses

Request samples

Content type
application/json
Example
{
  • "id": "1000001.1000001",
  • "role": "ASSIGNED_AGENT",
  • "state": "ACTIVE"
}

Response samples

Content type
application/json
Example
{
  • "id": "1000001.1000001",
  • "role": "ASSIGNED_AGENT",
  • "state": "ACTIVE"
}

Get Participants In Dialog

Get all participants in a Dialog.

Authorizations:
agentBearerAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

dialog_id
required
string (dialogId)

The Dialog ID

query Parameters
limit
integer

Number of records to return (default 100)

offset
integer

The number of items to skip before starting to collect the result set (default 0)

sortBy
string
Default: "role"
Enum: "id" "role"

Name of the field by which to sort the result set.

sortOrder
string
Default: "DESC"
Enum: "ASC" "DESC"

Allows to order the result set in ascending or descending order

filters
string
Examples:
  • filters=%7B%22roles%22%3A%5B%22CONSUMER%22%5D%7D - Get Consumer only

Any filters to apply on the collection. This needs to be in a URL encoded json string. For example {"roles":["CONSUMER"]} should be passed as %7B%22roles%22%3A%5B%22CONSUMER%22%5D%7D

fields
string
Examples:
  • fields=id - Get ID field only

List of fields to include in the response. Fields must be separated by a comma.

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{}

Get Participants Count in Dialog

Returns participant count in a Dialog.

Authorizations:
agentBearerAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

dialog_id
required
string (dialogId)

The Dialog ID

query Parameters
filters
string
Examples:
  • filters=%7B%22roles%22%3A%5B%22CONSUMER%22%5D%7D - Get Consumer only

Any filters to apply on the collection. This needs to be in a URL encoded json string. For example {"roles":["CONSUMER"]} should be passed as %7B%22roles%22%3A%5B%22CONSUMER%22%5D%7D

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
"Empty Body"

Get Single Participant in Dialog

Returns a single Participant resource with the given ID within a Dialog

Authorizations:
agentBearerAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

dialog_id
required
string (dialogId)

The Dialog ID

participant_id
required
string

The Participant ID

query Parameters
fields
string
Examples:
  • fields=id - Get ID field only

List of fields to include in the response. Fields must be separated by a comma.

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "id": "54e5384b-e37d-4fee-b361-b54ce8affdc0",
  • "role": "CONSUMER",
  • "state": "ACTIVE"
}

Update Participant in Dialog

Updates the role of a single participant in a Dialog. If the Participant in the request is an Agent that updates its role to AGENT_ASSIGNED and an agent with this role already exists in the conversation, the existing agent with the role will be replaced by the one in the request.

Authorizations:
agentBearerAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

dialog_id
required
string (dialogId)

The Dialog ID

participant_id
required
string

The Participant ID

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

If-Match
required
string
Example: {{Etag}}

Should match the 'Etag' header from the last POST, GET or PUT.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
id
required
string

The User ID of the Participant. If Agent, the ID should be sent as {brand_id}.{agent_id}

role
required
string
Enum: "CONSUMER" "ASSIGNED_AGENT" "AGENT" "MANAGER" "READER" "BRAND_BOT" "CONTROLLER"

The Role that this Participant should assume. Sending the CONSUMER role will be considered as a request for the Consumer Step Up flow.

state
string (participantState)
Enum: "ACTIVE" "SUGGESTED"

The Participant State

Responses

Request samples

Content type
application/json
Example
{
  • "id": "1000001.1000001",
  • "role": "READER",
  • "state": "ACTIVE"
}

Response samples

Content type
application/json
Example
{
  • "id": "1000001.1000001",
  • "role": "READER",
  • "state": "ACTIVE"
}

Remove Participant from Dialog

Removes a single Participant from a Dialog. If the removed Participant was an ASSIGNED_AGENT, this action will trigger the "back to queue" flow for matching another available Agent.

Authorizations:
agentBearerAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

dialog_id
required
string (dialogId)

The Dialog ID

participant_id
required
string

The Participant ID

query Parameters
transferToSkillId
string

The Skill ID to which the conversation would be changed

transferToAgentId
string

The Agent ID to transfer the conversation

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

If-Match
required
string
Example: {{Etag}}

Should match the 'Etag' header from the last POST, GET or PUT.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
"Empty Body"

Add Dialog to Conversation

Authorizations:
agentBearerAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
required
Array of objects (participants)

List of Participants

dialogType
required
string (dialogType)
Enum: "MAIN" "AGENTS" "OTHER" "POST_SURVEY" "PRE_CONVERSATION_OPT_IN"

The Dialog Type

channelType
string (channelType)
Enum: "MESSAGING" "LIVE_CHAT" "COBROWSE"

The Channel Type

state
string (dialogState)
Enum: "OPEN" "CLOSE"

The Dialog State

Responses

Request samples

Content type
application/json
{
  • "participants": [
    ],
  • "dialogType": "AGENTS",
  • "channelType": "MESSAGING",
  • "state": "OPEN"
}

Response samples

Content type
application/json
{
  • "id": "yDLvflnpT66SNTL06YcT0w",
  • "lastUpdatedTs": "2022-12-16T05:03:09.903+00:00",
  • "conversationId": "616cb657-1f63-43b8-aa48-78dfd1f3e749",
  • "participants": [
    ],
  • "dialogType": "AGENTS",
  • "channelType": "MESSAGING",
  • "state": "OPEN"
}

Get Dialog By Id

Returns a single Dialog resource within a Conversation

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

dialog_id
required
string (dialogId)

The Dialog ID

query Parameters
fields
string
Examples:
  • fields=id - Get ID field only
  • fields=id,participants.id - Get nested fields

List of fields to include in the response. Fields must be separated by a comma.

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "id": "616cb657-1f63-43b8-aa48-78dfd1f3e749",
  • "createdTs": "2022-12-16T05:02:47.709+00:00",
  • "lastUpdatedTs": "2022-12-16T05:03:09.903+00:00",
  • "conversationId": "616cb657-1f63-43b8-aa48-78dfd1f3e749",
  • "participants": [
    ],
  • "dialogType": "MAIN",
  • "channelType": "MESSAGING",
  • "state": "OPEN"
}

Update Dialog

Update a field on a Dialog. For example dialog metadata, or dialog State (to close the dialog)

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

dialog_id
required
string (dialogId)

The Dialog ID

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

If-Match
required
string
Example: {{DialogEtag}}

Should match the 'Etag' header from the last POST, GET or PUT.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
One of
metadata
object (dialogMetadata)

The Dialog Metadata

Responses

Request samples

Content type
application/json
Example
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "616cb657-1f63-43b8-aa48-78dfd1f3e749",
  • "createdTs": "2022-12-16T05:02:47.709+00:00",
  • "lastUpdatedTs": "2022-12-16T05:03:09.903+00:00",
  • "conversationId": "616cb657-1f63-43b8-aa48-78dfd1f3e749",
  • "participants": [
    ],
  • "dialogType": "MAIN",
  • "channelType": "MESSAGING",
  • "state": "OPEN"
}

Messages

A Message is a single block of text posted by any participant within a Dialog. UMS supports different types of Messages like PLAIN_TEXT, RICH_CONTENT, HOSTED_FILE, EXTERNAL_FILE, ACKNOWLEDGEMENT, etc.

Publish Message

Publish a message to a Dialog in a Conversation

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

dialog_id
required
string (dialogId)

The Dialog ID

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Content-Type
required
string
Example: application/json

The Content-Type header is used to indicate the media type of the resource.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
type
required
string (messageType)
Enum: "PLAIN_TEXT" "EXTERNAL_FILE" "HOSTED_FILE" "RICH_CONTENT" "SECURE_FORM_INVITATION" "SECURE_FORM_SUBMISSION" "ACKNOWLEDGEMENT" "CHAT_STATE"

Message Type

required
PLAIN_TEXT (object) or RICH_CONTENT (object) or HOSTED_FILE (object) or EXTERNAL_FILE (object) or SECURE_FORM_INVITATION (object) or SECURE_FORM_SUBMISSION (object) or ACKNOWLEDGEMENT (object) or CHAT_STATE (object) (messageContent)
object (ClientProperties)

Properties of the Client device

metadata
Array of objects (messageMetadata)

Needs to conform to the metadata json schema.

messageAudience
string (messageAudience)
Enum: "ALL" "AGENTS_AND_MANAGERS"

Message Audience

Responses

Request samples

Content type
application/json
Example
{
  • "type": "PLAIN_TEXT",
  • "content": {
    },
  • "metadata": [
    ],
  • "messageAudience": "ALL"
}

Response samples

Content type
application/json
Example
{
  • "id": "14e4d43d-081c-4d40-81c0-37893f63dfad_1",
  • "type": "PLAIN_TEXT",
  • "sequence": "1",
  • "dialogId": "14e4d43d-081c-4d40-81c0-37893f63dfad",
  • "content": {
    },
  • "originator": {
    },
  • "metadata": [
    ],
  • "messageAudience": "ALL"
}

Get Messages In Dialog

Returns a paginated list of messages in a dialog. This is equivalent to the Query Messages WebSocket API. Messages are sorted in descending order of sequence (oldest first).

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

dialog_id
required
string (dialogId)

The Dialog ID

query Parameters
limit
integer

Number of records to return (default 100)

offset
integer

The number of items to skip before starting to collect the result set (default 0)

sortBy
string
Value: "sequence"

Name of the field by which to sort the result set.

sortOrder
string
Default: "DESC"
Enum: "ASC" "DESC"

Allows to order the result set in ascending or descending order

filters
string
Examples:
  • filters=%7B%22types%22%3A%5B%22PLAIN_TEXT%22%2C%22RICH_CONTENT%22%5D%7D - Get messages of type 'PLAIN_TEXT' and 'RICH_CONTENT' only
  • filters=%7B%22originatorRoles%22%3A%5B%22CONSUMER%22%5D%7D - Get messages from 'CONSUMER' only
  • filters=%7B%22messageAudiences%22%3A%5B%22AGENTS_AND_MANAGERS%22%5D%7D - Get private messages only

Any filters to apply on the collection. This needs to be in a URL encoded json string. For example {"types":["PLAIN_TEXT","RICH_CONTENT"]} should be passed as %7B%22types%22%3A%5B%22PLAIN_TEXT%22%2C%22RICH_CONTENT%22%5D%7D

fields
string
Examples:
  • fields=id - Get ID field only
  • fields=id,content.text - Get nested fields

List of fields to include in the response. Fields must be separated by a comma.

newerThanSequence
integer

Only return messages with sequence number greater than or equal to this value

olderThanSequence
integer

Only return messages with sequence number smaller than or equal to this value

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get Message Count In Dialog

Returns the message count in a dialog.

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

dialog_id
required
string (dialogId)

The Dialog ID

query Parameters
filters
string
Examples:
  • filters=%7B%22types%22%3A%5B%22PLAIN_TEXT%22%2C%22RICH_CONTENT%22%5D%7D - Get messages of type 'PLAIN_TEXT' and 'RICH_CONTENT' only
  • filters=%7B%22originatorRoles%22%3A%5B%22CONSUMER%22%5D%7D - Get messages from 'CONSUMER' only
  • filters=%7B%22messageAudiences%22%3A%5B%22AGENTS_AND_MANAGERS%22%5D%7D - Get private messages only

Any filters to apply on the collection. This needs to be in a URL encoded json string. For example {"types":["PLAIN_TEXT","RICH_CONTENT"]} should be passed as %7B%22types%22%3A%5B%22PLAIN_TEXT%22%2C%22RICH_CONTENT%22%5D%7D

newerThanSequence
integer

Only return messages with sequence number greater than or equal to this value

olderThanSequence
integer

Only return messages with sequence number smaller than or equal to this value

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
"Empty Body"

Get Unread Message Count for Participant

Returns the unread message count in a dialog for a participant.

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
conv_id
required
string (conversationId)

The Conversation ID

dialog_id
required
string (dialogId)

The Dialog ID

participant_id
required
string

The Participant ID

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
"Empty Body"

Subscriptions

A Subscription resource encapsulates an Agent's or Consumer's intent to receive notifications on future updates to certain UMS resources that match a specified criteria. UMS supports two types of Subscriptions

  • Conversation Subscription - Subscription on updates to Conversation resources
  • Message Subscription - Subscription on messaging events on a Dialog

Before creating a Subscription, the client needs to ensure a webhook endpoint is set up to receive notifications. See the Webhooks section for more details.

Create Message Subscription for Consumer

Authorizations:
consumerJWTBearerAuthappJWTandConsumerJWSAuth
path Parameters
consumer_id
required
string

The Consumer ID

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Content-Type
required
string
Example: application/json

The Content-Type header is used to indicate the media type of the resource.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
required
object (MessageSubscriptionFilter)

Filter criteria for this Subscription. Specify filters to narrow the scope of events that qualify for this Subscription.

required
object (SubscriptionNotifications)

Describes how notifications against this Subscription should be delivered

Responses

Callbacks

Request samples

Content type
application/json
{
  • "filters": {
    },
  • "notifications": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ab86d53a-0d11-4495-b941-542a0b05bcd5",
  • "brandId": "51574755",
  • "subscriber": {
    },
  • "filters": {
    },
  • "notifications": {
    },
  • "createdTs": "2022-06-14T06:48:10.987+00:00"
}

Callback payload samples

Callback
POST: /your/webhook-path
Content type
application/json
[
  • {
    }
]

Create Message Subscription

Authorizations:
agentBearerAuth
header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Content-Type
required
string
Example: application/json

The Content-Type header is used to indicate the media type of the resource.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
required
object (MessageSubscriptionFilter)

Filter criteria for this Subscription. Specify filters to narrow the scope of events that qualify for this Subscription.

required
object (SubscriptionNotifications)

Describes how notifications against this Subscription should be delivered

Responses

Callbacks

Request samples

Content type
application/json
{
  • "filters": {
    },
  • "notifications": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ab86d53a-0d11-4495-b941-542a0b05bcd5",
  • "brandId": "51574755",
  • "subscriber": {
    },
  • "filters": {
    },
  • "notifications": {
    },
  • "createdTs": "2022-06-14T06:48:10.987+00:00"
}

Callback payload samples

Callback
POST: /your/webhook-path
Content type
application/json
[
  • {
    }
]

Get Single Message Subscription By Id

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
subscription_id
required
string

The Subscription ID

query Parameters
fields
string
Examples:
  • fields=id - Get ID field only
  • fields=id,subscriber.userId - Get nested fields

List of fields to include in the response. Fields must be separated by a comma.

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "brandId": "string",
  • "subscriber": {
    },
  • "filters": {
    },
  • "notifications": {
    },
  • "createdTs": "2019-08-24T14:15:22Z",
  • "lastUpdatedTs": "2019-08-24T14:15:22Z",
  • "expirationTs": "2019-08-24T14:15:22Z"
}

Delete Message Subscription

Equivalent to an Unsubscribe request.

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
subscription_id
required
string

The Subscription ID

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

If-Match
required
string
Example: {{SubscriptionEtag}}

Should match the 'Etag' header from the last POST, GET or PUT.

Content-Type
required
string
Example: application/json

The Content-Type header is used to indicate the media type of the resource.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Create Conversation Subscription for Consumer

Authorizations:
consumerJWTBearerAuthappJWTandConsumerJWSAuth
path Parameters
consumer_id
required
string

The Consumer ID

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Content-Type
required
string
Example: application/json

The Content-Type header is used to indicate the media type of the resource.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
required
object (ConversationSubscriptionFilter)

Filter criteria for this Subscription. Specify filters to narrow the scope of events that qualify for this Subscription.

required
object (SubscriptionNotifications)

Describes how notifications against this Subscription should be delivered

Responses

Callbacks

Request samples

Content type
application/json
{
  • "filters": {
    },
  • "notifications": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ab86d53a-0d11-4495-b941-542a0b05bcd5",
  • "brandId": "le84625337",
  • "subscriber": {
    },
  • "filters": {
    },
  • "notifications": {
    },
  • "createdTs": "2022-06-14T06:48:10.987+00:00",
  • "lastUpdatedTs": "2022-06-14T06:48:41.843+00:00",
  • "expirationTs": "2022-07-14T06:48:41.843+00:00"
}

Callback payload samples

Callback
Content type
application/json
[
  • {
    }
]

Create Conversation Subscription

Authorizations:
agentBearerAuth
header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Content-Type
required
string
Example: application/json

The Content-Type header is used to indicate the media type of the resource.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
required
object (ConversationSubscriptionFilter)

Filter criteria for this Subscription. Specify filters to narrow the scope of events that qualify for this Subscription.

required
object (SubscriptionNotifications)

Describes how notifications against this Subscription should be delivered

Responses

Callbacks

Request samples

Content type
application/json
Example
{
  • "filters": {
    },
  • "notifications": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ab86d53a-0d11-4495-b941-542a0b05bcd5",
  • "brandId": "le84625337",
  • "subscriber": {
    },
  • "filters": {
    },
  • "notifications": {
    },
  • "createdTs": "2022-06-14T06:48:10.987+00:00",
  • "lastUpdatedTs": "2022-06-14T06:48:41.843+00:00",
  • "expirationTs": "2022-07-14T06:48:41.843+00:00"
}

Callback payload samples

Callback
POST: /your/webhook-path
Content type
application/json
[
  • {
    }
]

Get Single Conversation Subscription By Id

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
subscription_id
required
string

The Subscription ID

query Parameters
fields
string
Examples:
  • fields=id - Get ID field only
  • fields=id,subscriber.userId - Get nested fields

List of fields to include in the response. Fields must be separated by a comma.

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "brandId": "string",
  • "subscriber": {
    },
  • "filters": {
    },
  • "notifications": {
    },
  • "createdTs": "2019-08-24T14:15:22Z",
  • "lastUpdatedTs": "2019-08-24T14:15:22Z",
  • "expirationTs": "2019-08-24T14:15:22Z"
}

Update Conversation Subscription

Subscriptions created via the REST API do not live indefinitely. By default, Subscriptions of type MessageSubscription auto-expire with the Conversation after the dialog closes. Subscriptions of type ConversationSubscription accept a client provided expirationTs at the time of creation (if this field is absent in the create request, a default, system configured expiration is set). The client application is responsible to call this endpoint to extend the expiration of the Subscription if they would like to keep it active.

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
subscription_id
required
string

The Subscription ID

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

If-Match
required
string
Example: {{SubscriptionEtag}}

Should match the 'Etag' header from the last POST, GET or PUT.

Content-Type
required
string
Example: application/json

The Content-Type header is used to indicate the media type of the resource.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
expirationTs
string <date-time>

The new expiration time for this Subscription

Responses

Request samples

Content type
application/json
{
  • "expirationTs": "2023-08-24T14:15:22Z"
}

Delete Conversation Subscription

Equivalent to an Unsubscribe request.

Authorizations:
consumerJWTBearerAuthagentBearerAuthappJWTandConsumerJWSAuth
path Parameters
subscription_id
required
string

The Subscription ID

header Parameters
Authorization
required
string
Example: {{AppJWT}}

Check the different authentication types available in the AUTHORIZATIONS section

LP-ON-BEHALF
string
Example: {{ConsumerJWS}}

The ConsumerJWS. This header is required only for appJWTandConsumerJWSAuth authorization, where Authorization header has an AppJWT.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

If-Match
required
string
Example: {{SubscriptionEtag}}

Should match the 'Etag' header from the last POST, GET or PUT.

Content-Type
required
string
Example: application/json

The Content-Type header is used to indicate the media type of the resource.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Webhooks

A Webhook Endpoint resource encapsulates an HTTP service hosted by the client application calling the REST API (specifically the subscriptions API), capable of receiving notifications via HTTP requests from UMS. This section covers two types of resources

  • Webhook Endpoints - Encapsulates a single webhook endpoint set up by the client
  • Webhook Credentials - Encapsulates the authorization scheme and related settings used by the webhook endpoint

Create Webhook Credentials

Authorizations:
agentBearerAuth
header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Content-Type
required
string
Example: application/json

The Content-Type header is used to indicate the media type of the resource.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
One of
scheme
required
string (LPSignatureScheme)
Value: "LP_SIGNATURE"

A name of the scheme used for authentication and authorization.

required
object (LPSignatureSettingsCreate)

LivePerson digital signature settings.

Responses

Request samples

Content type
application/json
Example
{
  • "scheme": "LP_SIGNATURE",
  • "settings": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "scheme": "LP_SIGNATURE",
  • "settings": {
    }
}

Get Webhook Credentials for Brand

Returns all webhook credentials available for the given Brand.

Authorizations:
agentBearerAuth
query Parameters
limit
integer

Number of records to return (default: 100, max: 1000)

offset
integer

The number of items to skip before starting to collect the result set (default 0)

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get Webhook Credentials Count for brand

Returns webhook credentials count for the brand provided in the Brand-ID header.

Authorizations:
agentBearerAuth
header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Get Single Webhook Credentials By Id

Authorizations:
agentBearerAuth
path Parameters
credentials_id
required
string

The Webhook Endpoint ID

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "id": "f798af10-c64f-47fa-ab39-4928d3271a40",
  • "scheme": "LP_SIGNATURE",
  • "settings": {
    }
}

Update Webhook Credentials

Authorizations:
agentBearerAuth
path Parameters
credentials_id
required
string

The Webhook Endpoint ID

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

If-Match
required
string
Example: {{WebhookCredentialsEtag}}

Should match the 'Etag' header from the last POST, GET or PUT.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
One of
scheme
required
string (LPSignatureScheme)
Value: "LP_SIGNATURE"

A name of the scheme used for authentication and authorization.

required
object (LPSignatureSettingsCreate)

LivePerson digital signature settings.

Responses

Request samples

Content type
application/json
Example
{
  • "scheme": "LP_SIGNATURE",
  • "settings": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "scheme": "LP_SIGNATURE",
  • "settings": {
    }
}

Delete Webhook Credentials

Authorizations:
agentBearerAuth
path Parameters
credentials_id
required
string

The Webhook Endpoint ID

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

If-Match
required
string
Example: {{WebhookCredentialsEtag}}

Should match the 'Etag' header from the last POST, GET or PUT.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Create Webhook Endpoint

Authorizations:
agentBearerAuth
header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Content-Type
required
string
Example: application/json

The Content-Type header is used to indicate the media type of the resource.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
brandId
string (Brand ID)

The Brand ID that this webhook endpoint belongs to. A value of '*' here denotes that it is a brand agnostic webhook endpoint (reserved for LP internal backend applications).

name
string (Webhook Endpoint Name)

For brands or applications using multiple webhook endpoints, this field can be used to easily recognize and distinguish between the webhook endpoint resources.

uri
required
string (Webhook Endpoint URI)

The URI of the webhook endpoint. This is where the client will receive the HTTP requests containing notifications.

method
required
string (Webhook Endpoint HTTP method.)
Enum: "POST" "PUT" "PATCH"

HTTP method that should be used when invoking this webhook endpoint.

object (HTTP Request Headers)

Additional HTTP headers to be send with the request to the webhook endpoint. Expressed as key-value pairs, key being the header name, and value being the header value.

batchSize
integer <int32> (Batch Size) [ 1 .. 100 ]
Default: 10

The maximum number of events that can be sent with one request to the webhook endpoint. There is no guarantee that the specified number of events will be sent with every request. The actual number of events may vary. This setting only defines the maximum possible size of the batch.

The default batch size is 10. The batch size cannot exceed 100 events.

connectTimeout
integer <int32> (Connect Timeout) [ 1 .. 3000 ]
Default: 1000

The amount of time in milliseconds the client will wait for the connection to be established with the webhook endpoint's host. This parameter should have a reasonable value considering the route to the host and performance of the system, the webhook endpoint is hosted in. Otherwise, if the webhook endpoint's system is unstable, it may affect the overall performance of the event processing pipeline.

Please note that the maximum allowed connect timeout is 3 seconds. The webhook endpoint must satisfy this requirement. The default value is 1 second.

readTimeout
integer <int32> (Read Timeout) [ 1 .. 5000 ]
Default: 3000

The amount of time in milliseconds the client will wait for the reply from the webhook endpoint. This parameter should have a reasonable value considering the performance of the system, the webhook endpoint is hosted in. Otherwise, if the webhook endpoint's system is unstable, it may affect the overall performance of the event processing pipeline.

Please note that the maximum allowed read timeout is 5 seconds. The webhook endpoint must satisfy this requirement. The default value is 3 seconds.

object (Resilience Settings)

The configuration of the webhook client's behavior in case when the webhook endpoint is unstable. Enabled resilience mechanisms may increase the reliability of the entire system.

required
object

Responses

Request samples

Content type
application/json
{
  • "name": "Webhook Endpoint for brand 51574755",
  • "uri": "https://your.domain.com/webhooks/receiver",
  • "method": "POST",
  • "headers": {
    },
  • "connectTimeout": 1000,
  • "security": {
    }
}

Response samples

Content type
application/json
{
  • "id": "fe6ef683-6499-43fe-bd6f-cc41d13527e2",
  • "name": "Webhook Endpoint for brand 51574755",
  • "brandId": 51574755,
  • "uri": "https://your.domain.com/webhooks/receiver",
  • "method": "POST",
  • "headers": {
    },
  • "batchSize": 1,
  • "connectTimeout": 1000,
  • "readTimeout": 3000,
  • "resilience": {
    },
  • "security": {
    },
  • "createdTs": "2022-06-14T06:48:10.987+00:00",
  • "lastUpdatedTs": "2022-06-14T06:48:41.843+00:00"
}

Get Webhook Endpoints for Brand

Returns all webhook endpoints available for the given Brand.

Authorizations:
agentBearerAuth
query Parameters
limit
integer

Number of records to return (default: 100, max: 1000)

offset
integer

The number of items to skip before starting to collect the result set (default 0)

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get Webhook Endpoints Count for brand

Returns webhook endpoints count for the brand provided in the Brand-ID header.

Authorizations:
agentBearerAuth
header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Get Single Webhook Endpoint By Id

Authorizations:
agentBearerAuth
path Parameters
endpoint_id
required
string

The Webhook Endpoint ID

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses

Response samples

Content type
application/json
{
  • "id": "fe6ef683-6499-43fe-bd6f-cc41d13527e2",
  • "name": "Webhook Endpoint for brand 51574755",
  • "brandId": 51574755,
  • "uri": "https://your.domain.com/webhooks/receiver",
  • "method": "POST",
  • "headers": {
    },
  • "batchSize": 1,
  • "connectTimeout": 1000,
  • "readTimeout": 3000,
  • "resilience": {
    },
  • "security": {
    },
  • "createdTs": "2022-06-14T06:48:10.987+00:00",
  • "lastUpdatedTs": "2022-06-14T06:48:41.843+00:00"
}

Update Webhook Endpoint

Authorizations:
agentBearerAuth
path Parameters
endpoint_id
required
string

The Webhook Endpoint ID

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

If-Match
required
string
Example: {{WebhookEndpointEtag}}

Should match the 'Etag' header from the last POST, GET or PUT.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Request Body schema: application/json
brandId
string (Brand ID)

The Brand ID that this webhook endpoint belongs to. A value of '*' here denotes that it is a brand agnostic webhook endpoint (reserved for LP internal backend applications).

name
string (Webhook Endpoint Name)

For brands or applications using multiple webhook endpoints, this field can be used to easily recognize and distinguish between the webhook endpoint resources.

uri
required
string (Webhook Endpoint URI)

The URI of the webhook endpoint. This is where the client will receive the HTTP requests containing notifications.

method
required
string (Webhook Endpoint HTTP method.)
Enum: "POST" "PUT" "PATCH"

HTTP method that should be used when invoking this webhook endpoint.

object (HTTP Request Headers)

Additional HTTP headers to be send with the request to the webhook endpoint. Expressed as key-value pairs, key being the header name, and value being the header value.

batchSize
integer <int32> (Batch Size) [ 1 .. 100 ]
Default: 10

The maximum number of events that can be sent with one request to the webhook endpoint. There is no guarantee that the specified number of events will be sent with every request. The actual number of events may vary. This setting only defines the maximum possible size of the batch.

The default batch size is 10. The batch size cannot exceed 100 events.

connectTimeout
integer <int32> (Connect Timeout) [ 1 .. 3000 ]
Default: 1000

The amount of time in milliseconds the client will wait for the connection to be established with the webhook endpoint's host. This parameter should have a reasonable value considering the route to the host and performance of the system, the webhook endpoint is hosted in. Otherwise, if the webhook endpoint's system is unstable, it may affect the overall performance of the event processing pipeline.

Please note that the maximum allowed connect timeout is 3 seconds. The webhook endpoint must satisfy this requirement. The default value is 1 second.

readTimeout
integer <int32> (Read Timeout) [ 1 .. 5000 ]
Default: 3000

The amount of time in milliseconds the client will wait for the reply from the webhook endpoint. This parameter should have a reasonable value considering the performance of the system, the webhook endpoint is hosted in. Otherwise, if the webhook endpoint's system is unstable, it may affect the overall performance of the event processing pipeline.

Please note that the maximum allowed read timeout is 5 seconds. The webhook endpoint must satisfy this requirement. The default value is 3 seconds.

object (Resilience Settings)

The configuration of the webhook client's behavior in case when the webhook endpoint is unstable. Enabled resilience mechanisms may increase the reliability of the entire system.

required
object

Responses

Request samples

Content type
application/json
{
  • "brandId": "string",
  • "name": "string",
  • "uri": "string",
  • "method": "POST",
  • "headers": { },
  • "batchSize": 10,
  • "connectTimeout": 1000,
  • "readTimeout": 3000,
  • "resilience": {
    },
  • "security": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "brandId": "string",
  • "name": "string",
  • "uri": "string",
  • "method": "POST",
  • "headers": { },
  • "batchSize": 10,
  • "connectTimeout": 1000,
  • "readTimeout": 3000,
  • "resilience": {
    },
  • "security": {
    },
  • "createdTs": "2019-08-24T14:15:22Z",
  • "lastUpdatedTs": "2019-08-24T14:15:22Z"
}

Delete Webhook Endpoint

Authorizations:
agentBearerAuth
path Parameters
endpoint_id
required
string

The Webhook Endpoint ID

header Parameters
Authorization
required
string
Example: Bearer {{AgentBearerToken}}

The Agent Bearer Token.

Brand-ID
required
string (brandId)
Example: {{account}}

LivePerson account or site ID for this brand

If-Match
required
string
Example: {{WebhookEndpointEtag}}

Should match the 'Etag' header from the last POST, GET or PUT.

Request-ID
string
Example: {{UUID}}

A unique tracking/correlation id (in UUID format) for this request.

Responses