node-agent-sdk

LivePerson Agent Messaging SDK for NodeJS

The SDK provides a simple node JS wrapper for the LivePerson messaging API.

Disclaimer
Getting Started
Example Usage
API Overview
Further documentation
Running The Sample App
Contributing

Disclaimer

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.

Getting Started

Install:
```
npm i node-agent-sdk --save
```
Run the bot example (see how in Running The Sample App).

Example Usage

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);
    });
});

API Overview

Agent class

new Agent({
    accountId: String,
    username: String,
    password: String,
    token: String, // a bearer token instead of username and password
    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)
});

Events

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
});

Specific notifications additions

Some notifications support helper methods to obtain the role and to identify if the message event is from "me".

MessagingEventNotification isMe()

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(); 
    });
});

ExConversationChangeNotification getMyRole()

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();  
    });
});

Messaging Agent API (backend)

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

registerRequests(arr)

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
});

request(type, body[, headers], callback)

You can call any request API functionality as follows:

agent.request('.ams.aam.SubscribeExConversations', {
        'convState': ['OPEN']
    }, (err, resp) => {
        console.log('subscribed successfully', err, resp);
    });

Further documentation

When creating a request through the request builder you should provide only the body to the sdk request method

Running The Sample App

To run the bot example:

Provide the following env variables:
- LP_ACCOUNT - Your LivePerson account ID
- LP_USER - Your LivePerson agent username
- LP_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
```

Contributing

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 bot example, see Running The Sample App.

pavlonadolynskyi/node-agent-sdk