LivePerson Agent Messaging SDK for NodeJS
The SDK provides a simple node JS wrapper for the LivePerson messaging API.
- Disclaimer
- Getting Started
- Example Usage
- Example Sending Rich Content (Structured Content)
- API Overview
- Further documentation
- Running The Sample App
- Contributing
A new major version of the SDK will be released soon with a breaking change:
The current SDK will start sending notifications once connected.
The next version will require explicit registration.
-
Install:
npm i node-agent-sdk --save
-
Run the greeting bot example (see how in Running The Sample App).
const Agent = require('node-agent-sdk').Agent;
const agent = new Agent({
accountId: process.env.LP_ACCOUNT,
username: process.env.LP_USER,
password: process.env.LP_PASS
});
agent.on('connected', () => {
console.log(`connected...`);
agent.subscribeExConversations({
'convState': ['OPEN']
}, (err, resp) => {
console.log('subscribed successfully', err, resp);
});
});agent.publishEvent({
dialogId: 'MY_DIALOG_ID',
event: {
type: 'RichContentEvent',
content: {
"type": "vertical",
"elements": [
{
"type": "image",
"url": "http://cdn.mos.cms.futurecdn.net/vkrEdZXgwP2vFa6AEQLF7f-480-80.jpg?quality=98&strip=all",
"tooltip": "image tooltip",
"click": {
"actions": [
{
"type": "navigate",
"name": "Navigate to store via image",
"lo": 23423423,
"la": 2423423423
}
]
}
},
{
"type": "text",
"text": "product name (Title)",
"tooltip": "text tooltip",
"style": {
"bold": true,
"size": "large"
}
},
{
"type": "text",
"text": "product name (Title)",
"tooltip": "text tooltip"
},
{
"type": "button",
"tooltip": "button tooltip",
"title": "Add to cart",
"click": {
"actions": [
{
"type": "link",
"name": "Add to cart",
"uri": "http://www.google.com"
}
]
}
},
{
"type": "horizontal",
"elements": [
{
"type": "button",
"title": "Buy",
"tooltip": "Buy this product",
"click": {
"actions": [
{
"type": "link",
"name": "Buy",
"uri": "http://www.google.com"
}
]
}
},
{
"type": "button",
"title": "Find similar",
"tooltip": "store is the thing",
"click": {
"actions": [
{
"type": "link",
"name": "Buy",
"uri": "http://www.google.com"
}
]
}
}
]
},
{
"type": "button",
"tooltip": "button tooltip",
"title": "Publish text",
"click": {
"metadata": [
{
"type": "ExternalId",
"id": "MY_ACTION_ID"
}
],
"actions": [
{
"type": "publishText",
"text": "my text"
}
]
}
},
{
"type": "button",
"tooltip": "button tooltip",
"title": "Navigate",
"click": {
"actions": [
{
"type": "publishText",
"text": "my text"
},
{
"type": "navigate",
"name": "Navigate to store via image",
"lo": 23423423,
"la": 2423423423
}
]
}
}
]
}
}
}, null, [{type: 'ExternalId', id: 'MY_CARD_ID'}]);For more information on how this example was built, please refer to the Structured Content Templates document on the Developers' Community.
new Agent({
accountId: String,
username: String,
password: String,
token: String, // a bearer token instead of username and password
userId: String, // the user id - mandatory when using token as authentication method
assertion: String, // a SAML assertion to be used instead of token or username and password
appKey: String,// oauth1 keys needed (with username) to be used instead of assertion or token or username and password
secret: String,
accessToken: String,
accessTokenSecret: String,
csdsDomain: String, // override the CSDS domain if needed
requestTimeout: Number, // default to 10000 milliseconds
errorCheckInterval: Number, // defaults to 1000 milliseconds
apiVersion: Number // Messaging API version - defaults to 2 (version 1 is not supported anymore)
});The Agent Messaging SDK support the following authentication methods:
- username and password
- Barear token as
tokenwith user id asuserId - SAML assertion as
assertion
agent.on('connected', msg => {
// socket is now connected to the server
});
agent.on('notification', message => {
// listen on all notifications
});
agent.on('ms.MessagingEventNotification', body => { // specific notification type
// listen on notifications of the MessagingEvent type
});
agent.on('GenericSubscribeResponse', (body, requestId) => { // specific response type
// listen on notifications of the specified type, do something with the requestId
});
agent.on('closed', reason => {
// socket is now closed
});
agent.on('error', err => {
// some error happened
//might get error.code
//if code === 401 should call reconnect
});Some notifications support helper methods to obtain the role and to identify if the message event is from "me".
This method is deprecated. please use agent.agentId instead
A method to understand on each change on the messaging event if it is from the agent connected right now or not.
agent.on('ms.MessagingEventNotification', body => {
body.changes.forEach(change => {
change.isMe();
});
});This method is deprecated. please use agent.agentId instead
A method to understand on each change on the conversation change notification conversation details the current agent role in the conversation or undefined if he is not participant.
agent.on('cqm.ExConversationChangeNotification', body => {
body.changes.forEach(change => {
change.result.conversationDetails.getMyRole();
});
});in the cqm.ExConversationChangeNotification the field firstConversation is deprecated
All request types are dynamically assigned to the object on creation. The supported API calls are a mirror of the LiveEngage Messaging Agent API - please read the documentation carefully for full examples.
The available API calls are:
getClock
agentRequestConversation
subscribeExConversations
unsubscribeExConversations
updateConversationField
publishEvent
queryMessages
updateRingState
subscribeRoutingTasks
updateRoutingTaskSubscription
getUserProfile
setAgentState
subscribeAgentsState
Will reconnect the socket with the same configurations - will also regenerate token by default.
Use if when socket closed unexpectedly or on token revocation.
use skipTokenGeneration = true if you want to skip the token generation
Call reconnect on error with code 401
Will dispose of the connection and unregister internal events.
Use it in order to clean the agent from memory.
You can dynamically add functionality to the SDK by registering more requests. For example:
registerRequests(['.ams.AnotherTypeOfRequest']);
// ... will register the following API:
agent.anotherTypeOfRequest({/*some data*/}, (err, response) => {
// do something
});You can call any request API functionality as follows:
agent.request('.ams.aam.SubscribeExConversations', {
'convState': ['OPEN']
}, null, [{type: 'ExternalId', id: 'MY_CARD_ID'}], (err, resp) => {
console.log('subscribed successfully', err, resp);
});Note: It is also possible to add a 'metadata' field to your JSON. Using the conversation metadata will enable you to enjoy the advanced analytics and reporting provided by LP - report on your intents, MCS per intent, containment rate, escalation reasons per intent and more. To learn more on how to deploy conversation metadata please review the full Metadata guide.
You can get your agentId from the SDK using agent.agentId.
The following code snippet will allow you to transfer an ongoing conversation to a different skill of agents
agent.updateConversationField({
conversationId: "THE CONVERSATION ID",
conversationField: [
{
field: "ParticipantsChange",
type: "REMOVE",
role: "ASSIGNED_AGENT"
},
{
field: "Skill",
type: "UPDATE",
skill: "TARGET SKILL ID"
}]
}, function(err) {
if(err)....
})When creating a request through the request builder you should provide only the body to the sdk request method
To run the greeting bot example:
-
Provide the following
envvariables:LP_ACCOUNT- Your LivePerson account IDLP_USER- Your LivePerson agent usernameLP_PASS- Your LivePerson agent password
-
If you are consuming the Agent Messaging SDK as a dependency, switch to the package root:
cd ./node_modules/node-agent-sdk
If you are a developer, the package root is the same as the repository root. There is therefore no need to change directories.
-
Run with npm:
npm start
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality, lint and test your code.
-
To run the tests:
npm test -
To run the greeting bot example, see Running The Sample App.