The Messaging Agent SDK for node.js was built to provide a fully custom way of programmatically building a bot with LivePerson. This SDK provides access to an Agent Messaging API and enables the bot to handle consumer conversations, escalate to a human when needed, and perform all agent actions.

The code for this SDK is hosted on GitHub.

Here are the API terms of use.


Currently the API behind this SDK starts sending MessagingEventNotifications immediately upon connection, but this subscription will exclude some notifications.

A new version of the API will be released soon in which there is no automatic subscription, and you must explicitly subscribe to these events for each conversation in order to receive them.

In order to guarantee compatibility with future versions of the API, and to ensure that no notifications are missed even with the current API version, it is highly recommended that your bot explicitly subscribe to MessagingEventNotifications for all relevant conversations, as demonstrated in the Agent-Bot example's MyCoolAgent.js.

Getting Started


  • Option 1 - npm install (does not include sample apps)

     npm i node-agent-sdk --save
  • Option 2 - Clone this repository (includes sample apps)

      git clone https://github.com/LivePersonInc/node-agent-sdk.git

    Run the greeting bot example (see how in Running The Sample Apps).

Agent class

new Agent({
    accountId: String,  // required
    username: String,  // required for username/password authentication and OAuth1 authentication
    password: String,  // required for username/password authentication
    appKey: String, // required for OAuth1 authentication
    secret: String, // required for OAuth1 authentication
    accessToken: String, // required for OAuth1 authentication
    accessTokenSecret: String, // required for OAuth1 authentication
    token: String, // required for token authentication
    userId: String, // required for token authentication
    assertion: String, // required for SAML authentication
    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 as username and password
  • Bearer token as token with user id as userId
  • SAML assertion as assertion
  • OAuth1 with username, appkey, secret, accessToken, and accessTokenSecret


You can get your agentId from the SDK using agent.agentId.

Quick Start Example

Create index.js

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', () => {

    // subscribe to all conversations in the account
        'convState': ['OPEN']
    }, (err, resp) => {
        console.log('subscribed successfully', err, resp);

// log all conversation updates
agent.on('cqm.ExConversationChangeNotification', notificationBody => {

Run it:

Unix Shell
LP_ACCOUNT=(YourAccountNumber) LP_USER=(YourBotUsername) LP_PASS=(YourBotPassword) node index.js
Windows Shell
set LP_ACCOUNT=(YourAccountNumber)
set LP_USER=(YourBotUsername)
set LP_PASS=(YourBotPassword)
node index.js

Next Steps

See example bots and dive deeper into the SDK's methods and events.