Overview

The Context Services API is a REST interface to a cloud based repository for storing and retrieving session state attributes that can be carried over and used throughout the conversational journey. This allows continuity in conversations as context can be transferred between agents and bots enabling a true warm handoff. The context service can be used for several purposes. For example:

  1. Save the conversation session state data in LiveEngage (e.g. agent notes), and then retrieve them later in a different conversation session with a different agent.

  2. Save contextual attributes in a concierge bot (e.g. intents or customer information) and carry this context over to another bot or human skill.

The Context APIs are part of Maven, LivePerson’s AI engine, that allows brands to store, retrieve, and manage custom attributes programmatically. The context store provides a system of hierarchically organizing your data.

Each brand can have multiple namespaces for different business use cases. Typically a namespace may group together related attributes, for example customer information such as name, email, phone number etc. which are stored as Key-Value Pairs. Brands can define as many attributes they need per namespace. To group together the attributes in a namespace for example a conversation session brands can use the Session ID. Each object in the hierarchical structure (Namespace, Session ID, KVPs) comes with CRUD (Create, Read, Update, Delete) operations using the REST APIs.

Example Use Cases

  • Passing context (intent, customer info) and customer routing / escalation path between bots.

  • Use shared context across different agents in a single conversation

  • Carry over attributes and information collected in a multi-step conversational journey for continuity and warm handoffs between bots and human agents.

Developer Key

To use Context Session store APIs you will need to create and use an API key. To get your unique key:

  1. Login to Maven with your LiveEngage credentials and then navigate to Developer Key.

  2. Copy and paste the key you see in the experience and use it in your API headers.

  3. To generate a new key, click on the **Regenerate Key **button. Please note that this will invalidate the previous key. The key is shared for all Maven APIs and therefore you will have to use the new key wherever the APIs are being called.

Methods

Every API call to the Maven Context service requires the following Auth Headers to be accepted

Content-Type : application/json

maven-api-key : <INSERT YOUR API KEY HERE>

Base URL per environment

AMERICAS : https://z1.context.liveperson.net
EMEA: https://z2.context.liveperson.net
APAC: https://z3.context.liveperson.net

Create a custom namespace

To use the Maven Context API, you will first need to create a Namespace.

You will use the namespace value that is returned in the response in all other Context API methods.

Method Path Description Request Payload Example Response Payload Example
POST /v1/account/{accountId} Create a custom namespace { "name": "someCustomNamespace" } Empty body; status code = 204
Example:

Note: the accountId and API key in these examples are fake - please replace it with your accountID and developer key that you generated

curl --request POST \

  --url https://z2.context.liveperson.net/v1/account/577089 \

  --header 'content-type: application/json' \

  --header 'maven-api-key: CEl7KSCf59IQEAFTQ1H2uCGv0yr4Hxyz' \

  --data '{

    "name": "myCoolNamespace"

}'

Set custom namespace properties

This will override the value if an existing key is used. If a new key is used then it will be added. If a key is omitted it will not be removed.

Method Path Description Request Payload Example Response Payload Example
PATCH /v1/account/{accountId}/{customNamespace}/properties Set custom namespace properties JSON object of properties and values: {"a":1,"b":"hello","c":true}
Example:

Note: the accountId and API key in these examples are fake - please replace it with your accountID and developer key that you generated

curl --request PATCH \

  --url https://z3.context.liveperson.net/v1/account/739483/myCoolNamespace/properties \

  --header 'content-type: application/json' \

  --header 'maven-api-key: CEl7KSCf59IQEAFTQ1H2uCGv0yr4Hxyz' \

  --data '{

    "minutesSinceLastConversation": 720,

    "salesforceId": "xyz@test.com",

    "isSomething": true

}'

Set custom namespace properties within a session

This will override the value if an existing key is used. If a new key is used then it will be added.

Method Path Description Request Payload Example Response Payload Example
PATCH /v1/account/{accountId}/{customNamespace}/{sessionId}/properties Set custom namespace properties JSON object of properties and values: {"a":1,"b":"hello","c":true}

Example: Note: the accountId and API key in these examples are fake - please replace it with your accountID and developer key that you generated

curl --request PATCH \
  --url https://z3.context.liveperson.net/v1/account/739483/myCoolNamespace/session100/properties \
  --header 'content-type: application/json' \
  --header 'maven-api-key: LkhR5UPv03zP4xrwacy6wx7LYCverxyz' \
  --data '{
	"a": 720,
	"b": "jeff@test.com",
	"c": true
}'

Get list of namespaces created

Method Path Description Request Payload Example Response Payload Example
GET /v1/account/:accountId List of namespaces created [{"name":"myCoolNamespace","createdAt":"2019-08-02T19:41:52.017Z"},{"name":"myTestNamepsace","createdAt":"2019-08-08T06:12:23.204Z"}
Example:

Note: the accountId and API key in these examples are fake - please replace it with your accountID and developer key that you generated


curl --request GET \
  --url https://z2.context.liveperson.net/v1/account/362095 \
  --header 'maven-api-key: DigxAZB4lO9M0XCaW1DphiwW4Tz9Uxyz'

Get all namespace variables or properties

This will get all Key/value pairs for all requested properties that are available, prefixed with the namespace.

Method Path Description Request Payload Example Response Payload Example
GET /v1/account/{accountId}/{customNamespace}/properties Get all Key/value pairs for all requested properties that are available {"a":1000,"b":"mm@virtuoz.com","c":false,"d":1000}
Example:

Note: the accountId and API key in these examples are fake - please replace it with your accountID and developer key that you generated

curl --request GET \
  --url https://z3.context.liveperson.net/v1/account/739483/myCoolNamespace/properties \
  --header 'maven-api-key: LkhR5UPv03zP4xrwacy6wx7LYCverxyz'

Get all properties within a session

We recommend to use Namespace to group related attributes (KVPs), and use the sessionID to store as a session state variable. You can put anything you want in the sessionId. If you want to put consumer and conversation data in the same namespace, you can as long as the sessionIDs are unique across the two. And it's optional – if omitted, the system will use a default sessionId of __default__

Method Path Description Request Payload Example Response Payload Example
GET /v1/account/{accountId}/{customNamespace}/{sessionId}/properties/ Get all properties {"a":1000,"b":"mm@virtuoz.com","c":false,"d":1000}
Example:

Note: the accountId and API key in these examples are fake - please replace it with your accountID and developer key that you generated


curl --request GET \
  --url https://z2.context.liveperson.net/v1/account/362095/myCoolNamespace/session100/properties \
  --header 'maven-api-key: DigxAZB4lO9M0XCaW1DphiwW4Tz9Uxyz'

Get one property

Method Path Description Request Payload Example Response Payload Example
GET /v1/account/{accountId}/{customNamespace}/{sessionId}/properties/{propertyName} Get one property {"d":1000}
Example:

Note: the accountId and API key in these examples are fake - please replace it with your accountID and developer key that you generated

curl --request GET   --url https://z2.context.liveperson.net/v1/account/90233/myCoolMamespace2/properties/{propertyName}   --header 'maven-api-key:  BEnAcoA2p4OTAyMzM1Nxyz'


Update multiple properties within a session group

Method Path Description Request Payload Example Response Payload Example
PATCH /v1/account/{accountId}/{customNamespace}/{sessionId}/properties/ Update multiple properties { "a": 1, "b": 2, "c": 3 }
Example:

Note: the accountId and API key in these examples are fake - please replace it with your accountID and developer key that you generated


curl --request PATCH \
  --url https://z2.context.liveperson.net/v1/account/362095/myCoolNamespace/session100/properties \
  --header 'content-type: application/json' \
  --header 'maven-api-key: DigxAZB4lO9M0XCaW1DphiwW4Tz9Uxyz' \
  --data '{
	"a": 1,
	"b": 2,
	"c": 3
}'


Pass multiple propertyName to the GET properties

Method Path Description
GET /v1/brand/{accountID}/{customNamespace}/{sessionId}/properties?include=prop1,prop2,prop3 pass multiple propertyName to the GET properties
Example:

Note: the accountId and API key in these examples are fake - please replace it with your accountID and developer key that you generated


curl --request GET \
  --url https://z2.context.liveperson.net/v1/account/362095/myCoolNamespace/properties?include=minutesSinceLastConversation,salesforceId \
  --header 'maven-api-key: DigxAZB4lO9M0XCaW1DphiwW4Tz9Uxyz'

Delete a sessionID (Group of properties)

Delete sessionID would be used if brands wants to delete a set of session attributes within a namespace. For instance after the attributes have been used in a conversational journey they may decide to delete the values at the logical end of the conversation.

Method Path Description
DELETE /v1/account/{accountId}/{customNamespace}/{sessionId}/properties Delete a group of properties
Example:

Note: the accountId and API key in these examples are fake - please replace it with your accountID and developer key that you generated


curl --request DELETE \
 --url https://z2.context.liveperson.net/v1/account/362095/myCoolNamespace/session100/properties \
 --header 'maven-api-key: 04UQXk21ZDmKdN9jTwP8ty1sSoTLFxyz'

Delete a property

Method Path Description
DELETE /v1/account/{accountId}/{customNamespace}/properties/{propertyName} Delete a property
Example:

Note: the accountId and API key in these examples are fake - please replace it with your accountID and developer key that you generated

curl --request DELETE \
  --url https://z2.context.liveperson.net/v1/account/362095/myCoolNamespace/properties/isSomething \
  --header 'maven-api-key: DigxAZB4lO9M0XCaW1DphiwW4Tz9Uxyz'

Delete a custom namespace

Delete namespace may be used if brand wants to retire a namespace. This would really be quite rare, and may happen if entire set of attributes are not used any more, such as an entire use case is being retired.

Method Path Description
DELETE /v1/account/{accountId}/{customNamespace} Delete a custom namespace
Example:

Note: the accountId and API key in these examples are fake - please replace it with your accountID and developer key that you generated

curl --request DELETE \
  --url https://z2.context.liveperson.net/v1/account/362095/myCoolNamespace \
  --header 'maven-api-key: DigxAZB4lO9M0XCaW1DphiwW4Tz9Uxyz'