Messaging Platform SDK

An SDK to facilitate agent and consumer interactions on LivePerson's Messaging Platform from Node.js and web applications. Can be used to create bots, system tests, or custom UIs.

For more information about specific classes, functions, or enums see the API Reference.

Messaging Platform SDK has replaced Messaging Agent SDK (aka Node Agent SDK) as the recommended method for interacting with Messaging Platform from a node.js application. See the Feature Comparison for more information. For information about converting a Node Agent SDK based project to use Messaging Platform SDK, see our Conversion Guide.

How To Install
Quick Start
- A simple consumer conversation
- A simple agent conversation listener bot
Commonly Used Features
Advanced Topics
Features Not yet supported

How To Install

To install as a dependency, run the following from a terminal window:

npm install lp-messaging-sdk

Quick Start

A simple consumer conversation

const lpm = require("lp-messaging-sdk");

const connection = lpm.createConnection({
    appId: 'quick_start', // TODO: please change to something unique to your application
    accountId: '12345678',
    userType: lpm.UserType.CONSUMER
});

// log any internal errors (auth errors, etc)
connection.on('error', err => {
    console.error(err);
});

// connect & open conversation
await connection.open();

// optionally set the consumer's name information
await connection.setUserProfile({firstName: 'firstName', lastName: 'lastName', nickName: 'nickName'});

// create conversation
const conversation = await connection.createConversation();

// setup a message notification listener
conversation.on('message', message => {
    console.log(JSON.stringify(message.body));
});

// send a message
await conversation.sendMessage('test');

// close the main dialog
await conversation.close();

// close the connection
await connection.close();

A simple agent conversation listener bot

const lpm = require("lp-messaging-sdk");

// define the auth data
const accountId = '12345678';
const authData = {
    username: 'bot1',
    appKey: '1a804df636f347bgcb4974a1ea3e2a91',
    secret: 'e15d540710838b40',
    accessToken: 'ccf8gf5bb346f3a95245e9b4798695f2',
    accessTokenSecret: '876c7425f81c5160'
};

// create the connection object
const connection = lpm.createConnection({
    appId: 'quick_start', // TODO: please change to something unique to your application
    accountId,
    userType: lpm.UserType.BRAND,
    authData
});

// log any internal errors (auth errors, etc)
connection.on('error', err => {
    console.error(err);
});

// setup the conversation event
// this event will fire whenever the bot is informed of a new conversation
connection.on('conversation', async conversation => {

    // join the conversation as "AGENT" role
    await conversation.join(lpm.ParticipantRole.AGENT);
    
    // listen for messages from the consumer
    conversation.on('message', message => {
        
        // ignore all messages not from the consumer
        if (message.participant.role !== lpm.ParticipantRole.CONSUMER) return;
        
        console.log(message.body);
        
        // send a simple response
        conversation.sendMessage('hello');
    });
    
    // listen for the close event
    conversation.on('close', () => {
        console.log('conversation closed');
    });
    
});

// make the connection
await connection.open();

Commonly Used Features

Application Tracking

In order to help us provide the best support, we require that you choose an appId for your application. appId should only contain characters a-z and/or the special characters: -_.. This should be passed in the createConnection function along with the version of your application if available.

const consumerConnection = lpm.createConnection({
    appId: 'quick_start',
    appVersion: '1.6.2',
    accountId: '123456',
    userType: UserType.CONSUMER
});

Conversations

Create Conversation

When a consumer connection calls createConversation with no arguments, the conversation will be created in the default skill: "-1".

const conversation = await connection.createConversation();
expect(conversation.skill.skillId).toEqual('-1');

To create a conversation in a specific skill, simply pass the skillId as an argument when calling createConversation.

const conversation = await connection.createConversation({skillId: '12345678'});

See Conversation Context and Campaign Info for two other arguments that can be passed to createConversation.

Conversation Functions

Join and Leave

One way to join a conversation is to invoke the join function on that conversation, passing the role that the current user should join the conversation as. Commonly used roles are ASSIGNED_AGENT, AGENT, MANAGER, and CONTROLLER. The other main way to join a conversation as the assigned agent is to accept a ring.

await conversation.join(lpm.ParticipantRole.ASSIGNED_AGENT);

To leave a conversation, use the leave function.

await conversation.leave();

Transfer

To transfer a conversation, use the transfer function. The transfer function will remove the assigned agent from the conversation (if present) and then transfer the conversation to the specified skill or agent.

// transfer to a specific skill
await conversation.transfer({skillId: '1111111'});

// transfer to a specific agent
await conversation.transfer({agentId: '5555555'});

Close

To close a conversation, use the close function.

await conversation.close();

You can also close a conversation by conversationId by using the closeConversation function on the connection object, a conversation object is not required.

const conversationId = '123456789';
await connection.closeConversation(conversationId);

Resume conversation

To resume previously closed conversation you can use the resumeConversation function

const resumedConversation = await conversation.resumeConversation();

Agent Routing Tasks aka "Rings"

Most bots are configured for the role of MANAGER and receive conversations by virtue of being subscribed to all conversations, and thus they will get their conversations through the connection.on('conversation') event.

Agents and agent-type bots, on the other hand, get notified that they should handle a certain conversation through a process called "agent routing". In this process, the bot must indicate it is open to accepting routing tasks otherwise known as "rings" by setting their agent state to "online" and creating a routingTaskSubscription, which will then emit ring events when an agent has been assigned to handle a conversation.

When a ring is received, the agent has the option to either accept or reject the ring. Accepting the ring will add the agent as a participant on the conversation with the role of ASSIGNED_AGENT.

// connect as admin for brand
const connection = lpm.createConnection({appId: 'quick_start', userType: lpm.UserType.BRAND, accountId, authData});
await connection.open();

// agent state must be "ONLINE" in order to receive rings
await connection.setAgentState({agentState: lpm.AgentState.ONLINE});

// subscribe to routing tasks (rings)
const taskRoutingSubscription = await connection.createRoutingTaskSubscription();

// process the rings as they arrive
connection.on('ring', async ring => {
    
    // ignore old rings
    if (ring.ringState !== lpm.RingState.WAITING) return;
    
    // accept the ring
    // full conversation will appear from the connection.on('conversation') event (for now)
    await ring.accept();
    
    // or reject the ring
    // await ring.reject();
});

connection.on('conversation', conversation => {
    console.log('agent has been added to the conversation');
});

Conversation Events

With the Messaging Platform SDK, it is possible to set up hooks for events in a conversation.

Conversation Event: close

To know when a conversation closes, watch the close event. Please note that most conversation actions are not available for closed conversations, such as sending a message or transfer.

conversation.on('close', async () => {
    // TODO: close action
});

Conversation Event: transfer-skill

The transfer-skill event will fire when the conversation is transferred from one skill to another. Usually this also involves the assigned agent being removed.

One potential use case for conversation hooks is to implement holder bots that handles conversations when the contact center is in off hours and there are no available agents:

conversation.on('transfer-skill', async () => {
    
    // if the new skill is in off hours
    if (conversation.skill.isInOffHours()) {
        
        // join the conversation and send a message to inform the consumer
        await conversation.join(lpm.ParticipantRole.AGENT);
        await conversation.sendMessage('we are in off hours, would you like to wait?');
    }
});

Conversation Event: transfer-agent

The transfer-agent event will fire when the conversation is transferred directly from one assigned agent to another.

conversation.on('transfer-agent', async () => {
    
});

Conversation Event: back-to-queue

The back-to-queue event will fire when the assigned agent is removed from the conversation (without adding another) and the skill does not change.

conversation.on('back-to-queue', async () => {
    
});

Conversation Event: consumer-step-up

The consumer-step-up event will fire when the consumer becomes authenticated during a conversation.

conversation.on('consumer-step-up', async () => {
    
});

Conversation Event: participant-added

The participant-added event will fire whenever any participant is added to the conversation, this includes bots and managers.

It is also possible to extend the agent greeter bot to react to new participants on the conversation, a hook for participant-added event can be added:

// listen for new participants on the conversation
conversation.on('participant-added', async addedParticipant => {

    // if a manager joins, send a private message that is hidden from the consumer
    if (addedParticipant.participant.role === lpm.ParticipantRole.MANAGER) {
        await conversation.sendPrivateMessage('a manager has joined the conversation');
    }
});

Conversation Event: participant-removed

The participant-removed event will fire whenever any participant is removed from the conversation.

conversation.on('participant-removed', async (removedParticipant) => {
    
});

For a complete list of events emitted by the conversation object, see Events section of Conversation class

Messages

To send a message to a conversation there are several methods you can use:

// plain text
await conversation.sendMessage('hello');

// rich text
await conversation.sendRichText(richTextObject);

// brand connections can send private messages to a conversation that consumers will not see
await conversation.sendPrivateMessage('this is private');

Markdown in Messages

Messages can include markdown encoding by wrapping the mardown in the #md# tag. One common use is to use this to create a hyperlink via the markdown syntax of [label](url).

await conversation.sendMessage('view our docs #md#[here](https://developers.liveperson.com)#/md#');

Message Events

To receive messages you can watch the conversation's message event. If the user is an assigned agent or a consumer, your application should call the accept and read functions in order to tell the system that the message has been accepted and read (where appropriate).

// listen for messages from the consumer
conversation.on('message', async message => {
    
    // ignore all messages not from the consumer
    if (message.participant.role !== lpm.ParticipantRole.CONSUMER) return;
    
    // indicate that our application has received the message
    await message.accept();
    
    // write the message out to log
    console.log(message.body);
    
    // indicate that the user had read the message
    await message.read();
});

Previous messages

All received messages for a dialog will be stored in the messages array of that dialog. You can iterate through that array to write these messages to the screen or a log.

for (const message of conversation.openDialog.messages) {
    console.log(message.body);
}

Message is sentByCurrentUser

To check if a message is self sent (sent from the same user) you can use the sentByCurrentUser() method on every message.

message.sentByCurrentUser();

Loading all previous messages

By default, messages will only have the messages that have been received since the conversation was joined. For consumer connections, this will be all of the messages, as the messages are automatically retrieved for existing conversations. For brand connections, the messages are not automatically retrieved, as this could result in excessive memory usage for accounts with a large number of open conversations. Instead, you can call getAllPublishEvents on a conversation to ensure that all of its messages have been loaded into the messages array.

connection.on('conversation', async conversation => {
    await conversation.openDialog.getAllPublishEvents();
    // [execute conversation code]
});

However, you can force the SDK to automatically call getAllPublishEvents on all conversations as they are received, before they are emitted via the conversation event, by passing the argument getAllMessages: true when calling createConnection

const connection = lpm.createConnection({
    appId: 'quick_start', // TODO: please change to something unique to your application
    accountId,
    userType: lpm.UserType.BRAND,
    authData,
    getAllMessages: true
});

Message Metadata

To attach metadata to a message, pass it in as the second parameter to sendMessage, sendRichText, or sendPrivateMessage. The structure of metadata objects is strictly validated, please contact the Messaging Platform team for more information.

// TODO: ensure the metadata structure conforms to a valid metadata definition based on type
const metadata = {
    type: 'ExternalId',
    id: '123'
};
await conversation.sendMessage('external action 123 was taken', metadata);

Metadata can also be an array of metadata objects, if you need to attach more than one:

const metadata1 = {type: 'ExternalId',id: '1'};
const metadata2 = {type: 'ExternalId',id: '2'};
await conversation.sendMessage('external action 123 was taken', [metadata1, metadata2]);

Message quick replies

To attach quick replies to a message, pass the object as the third parameter to sendMessage or sendRichText. The structure of quick reply objects is strictly validated, please contact the Messaging Platform team for more information.

// TODO: ensure the quickreplies structure conforms to a valid definition
const quickReplies = {
    "type": "quickReplies",
    "itemsPerRow": 3,
    "replies": [
        // TODO: insert quickreplies objects here
    ]
};
await conversation.sendMessage('here are some quick replies', null, quickReplies);

Accounts that have filesharing enabled can upload and download files using the SDK. The article also describes the limits such as file size, formats, supported channels

To upload files, pass an ArrayBuffer to the Conversation.uploadFile method. An optional caption can also be passed in as the second argument.

If the upload succeeds, the SDK will then publish a message on the conversation with the uploaded file and caption (if any), which makes it viewable by the conversation participants. For image files, the SDK will generate a preview thumbnail that gets displayed in supported channels.

Upload a file from Node.js

To upload a file In Node.js environments, access the file with the File System module to generate a buffer.

const fs = require('fs');
const path = require('path');

// read the file into a buffer
const file = fs.readFileSync(path.resolve(__dirname, 'asset/logo.png'));

// upload the buffer
await conversation.uploadFile(file.buffer);

Download a file from Node.js

Whenever the conversation has a downloadable message with a file, the file can be downloaded.

// set up a hook to download files in the conversation
conversation.on('message', async (msg) => {
    
    // ignore regular messages without files
    if (!msg.isDownloadable) {
        return;
    }
    
    // download the file
    const downloadedFile = await msg.downloadFile();
    
    // write the file out to disk
    const buffer = downloadedFile.data;
    const filename = downloadedFile.filename;
    fs.writeFileSync(path.resolve(__dirname, `asset/${filename}`), data);
});

Upload a file from browser

For browser implementations, the SDK supports client-side scripting with JavaScript. To allow a user to upload a file to a conversation, first create an input tag of type file, an event that pulls the data from that file, and uploads it to the conversation.

<div id="file-upload" style="padding: 4px">
    <input type="file" id="selected-file">
    <button id="upload" value="upload">Upload</button>
</div>

<script type="text/javascript">
    const selectedFile = document.querySelector('#selected-file');

    async function upload(buffer) {
        await conversation.uploadFile(buffer);
    }

    document.querySelector('#upload').addEventListener('click', () => {
        console.log('uploading file');

        const file = selectedFile.files[0];
        
        // create a FileReader instance and read the selected file as arrayBuffer
        let fr = new FileReader();
        fr.onload = function () {
            let data = fr.result;
            upload(data).then(() => {
                writeLine('file uploaded');
            });
        };
        fr.readAsArrayBuffer(file);
    });
</script>

Download a file in browser

To download a file, set up a message event as before, but use the download function below in order to cause the browser to prompt the user to save the file to disk.

    conversation.on('message', async (msg) => {
        // ignore regular messages without files
        if (!msg.isDownloadable) {
            return;
        }
        await download(msg);
    });

    async function download(message) {
        // execute the real download
        const {data} = await message.downloadFile();
        
        // convert arrayBuffer to Blob
        const blob = new Blob([data]);
        
        // obtain the filename 
        const path = message.relativePath.split('/');
        const filename = path[path.length - 1];
        
        // create a temporary element that references the downloaded data
        let link = document.createElement('hiddenDownloadElement');
        link.href = window.URL.createObjectURL(blob);
        link.download = filename;
        
        // downloads the data as a file
        link.click();
        
        // remove the temporary element
        window.URL.revokeObjectURL(blob);
        link.remove();
    }

Advanced Topics

Background Process Errors

There are many active processes running under the hood of the SDK, sometimes these will encounter an error scenario. They will do their best to recover, but it is advised that applications watch and log the error event. To do this, simply add an event watcher to the connection and log the error as you would any other error in the application. If you get any unexpected errors that you can't resolve on your own, please reach out to a LivePerson team member for assistance.

connection.on('error', err => {
    console.error(err);
});

Arbitrary websocket requests

Our goal in making this SDK is to support all Message Platform requests through nicely designed interfaces. However, there may be some requests or edge cases for existing requests that the SDK does not yet support. If there is a type of request that you want to execute for which the SDK does not yet officially support, you can send the request directly using the send function.

The send function is async and will wait for the response back before completing. For example, to send a plain text message, instead of using sendMessage you can use the following code:

const request = {
    type: '.ams.ms.PublishEvent',
    body: {
        dialogId: 'MY_DIALOG_ID',
        event: {
            type: 'ContentEvent',
            contentType: 'text/plain',
            message: 'hello world!'
        }
    }
};

const response = await connection.send(request);

Notification Events

There are three different kinds of messages used in communicating with Messaging Platform: Request, Response, and Notification. For the most part, when using the SDK your application does not need to consider these, but we want to provide the information just in case it is useful.

In general, when you use the SDK to issue a command, it sends a Request to the server, the request is processed and the server returns a Response which then triggers the awaited promise to resolve. So, Response messages are only ever received in response to a Request.

The third type of websocket message is a notification, these are the server's method of communicating with clients asynchronously, without a request originating from the client. They are the main reason that websockets are required, otherwise we could do all communications simply using http.

Notifications are automatically processed by the SDK and may result in one of the events mentioned above. However, some applications might wish to examine notifications directly. In order to do this, watch the notification event on a connection.

connection.on('notification', notification => {
    console.log(`notification received of type ${notification.type}\n${JSON.stringify(notification.body, null, 2)}`);
})

Notification Types

There are three types of Notifications that Messaging Platform can send, each of which has different conditions that must be met in order to receive them. Some of them involve the creation of a subscription telling Messaging Platform which types of notifications the application wants to receive.

Message Event Notification

A message event notification is sent whenever a publishEvent request is successfully processed by the Messaging Platform. There are various types of message events: plain or rich message text from a participant, the status of a participant (typing, away, etc.), a file sharing event, etc.

To receive messages events for a conversation, an agent simply needs to be a participant in the conversation. This is accomplished by joining a conversation or accepting a ring.

Consumer connections, on the other hand, must create a subscription for the conversation before they will receive these notifications. The SDK creates and maintains these subscriptions automatically, there is no need to create them manually.

Conversation State Notification

Conversation state notifications contain information about a conversation's state (whether it is open or closed, or which users are participants, etc.)

To receive conversation state notifications, a conversation subscription is required whose query encompasses that conversation. The SDK creates and maintains these subscriptions automatically, there is usually no need to create them manually, unless you want to see closed conversations on a brand connection, which does not apply to most users.

Routing Notification

A routing task event, aka a Ring, indicating that routing has chosen the current user to handle a conversation.

To receive routing task events, a routing task subscription is required. These must be manually created, for more information see Agent Routing Tasks.

The default subscription

By default, after connecting the SDK will automatically create a single subscription per connection. This subscription is available on the connection object, if you want to log all notifications that subscription receives you can do so with this code:

connection.defaultSubscription.on('notification', notification => {
    console.log(JSON.stringify(notification));
});

Each type of connection has a different default query that is used to create its default subscription:

Brand connections use this query: {stage:["OPEN"]}
Consumer connections use this query: {stage:["OPEN", "CLOSE"]}

You can also provide a different query that will be used to create the default subscription, for example if you want your bot to only monitor conversations with an open main dialog, you would create your connection like this:

const connection = lpm.createConnection({
    appId: 'quick_start',
    accountId,
    userType: lpm.UserType.BRAND,
    authData,
    defaultSubscriptionQuery: {state:["OPEN"], dialogTypes:["MAIN"]}
});

If you don't want the SDK to create the default subscription, you can disable it by passing createDefaultSubscription as false when creating the connection:

const connection = lpm.createConnection({
    appId: 'quick_start',
    accountId,
    userType: lpm.UserType.BRAND,
    authData,
    createDefaultSubscription: false
});

Note that skillId is not supported in the subscription query.

Creating manual subscriptions

In the event that you want to create a conversation subscription manually, use the "createConversationSubscription" function. Please note that conversation objects are shared between subscriptions, in the sense that the SDK will use any notifications from all active subscriptions to update conversation objects.

const query = {stage:["OPEN"], agentIds:['12345.123456']};
const waitForReady = false;
const sub = await connection.createConversationSubscription(query, waitForReady);

Connection Maintenance

Communication with Messaging Platform happens primarily over a websocket, the SDK takes responsibility for maintaining this connection and in the event of a connection loss it will attempt to reconnect. The SDK will do this by default, no additional configuration or intervention is required.

While disconnected, any requests will be queued up and will execute when the connection is re-established. The SDK will also attempt to recreate any subscriptions, including the default subscription.

If the auth token has become invalid during the time in which the connection was down, the SDK will attempt to generate a new one based on the Auth Token Process

Brand Auth Token Process

As part of the .connect() function for brand connections, the SDK will use the provided authData to create a bearer token by making a request to an internal service called "agentVep". This token is used to authenticate with Messaging Platform when making a websocket connection or a rest api request. For this token to remain valid, a refresh request must be made once in every ten minutes back to agentVep, the SDK does this by default.

If a token becomes invalid for any reason, the SDK will automatically attempt to create a new one. In general, any websockets established will not lose connection if their token becomes invalid, so there is no risk of service interruption, but the new token will be required before any new http requests can be made.

If an application creates another token for the same user, the first token will become invalid. So it is therefore important that applications do not create two connections with the same authData, this will cause them to continually generate new tokens and put a strain on LivePerson's services.

If an application needs to use a connection's token to make http requests to other LivePerson services that are not supported directly by the SDK, you can access the bearer token with the following method after the connect() finishes: await connection.getToken()

Continuing an anonymous user session between two connections

It is common for users of a web application to refresh their browser, or to close their browser and return to the site at a later time. In these situations, the expectation is that the user resumes the same conversation. However, from an application stand point, there is no way to preserve objects between page refreshes, much less between separate browser processes.

Instead, the solution is to save the JWT generated by the initial connection and give it to the subsequent connections. They can then use this JWT to connect, rather than generate their own new JWTs. This will cause the Messaging Platform to recognize them as the same consumer, and give them access to the existing conversations for that consumer.

Once the initial connection is open, get the jwt by calling await connection.getToken()
Store that token in local storage or a cookie
Pass the token back in to createConnection as token

Any existing conversations will automatically be loaded up into the SDK and emitted as a conversation event. They will also be available through connection._covnersations which is a Map. To ensure that that conversation is loaded by the time await connection.open() is resolved, you can pass waitForReady: true to createConnection. This will cause open to only resolve once all conversations have been retrieved.

// open the initial connection
const connection1 = Connection.createConnection({
    userType: UserType.CONSUMER,
    appId: 'quick_start',
    accountId: '123456789'
});
await connection1.open();

// get and store the token
const token = await connection1.getToken();

// create a conv so we can resume it in the 2nd connection
const conversation1 = await connection.createConversation();
await conversation1.sendMessage("hello");

// close connection
await connection1.close();

// open a second connection using the same token
const connection2 = Connection.createConnection({
    userType: UserType.CONSUMER,
    appId: 'quick_start',
    accountId: '123456789',
    token,
    waitForReady: true
});
await connection2.open();

// retrieve the conversation and close it
const conversation2 = Array.from(connection2._conversations.values())[0];
await conversation2.close();

// close connection
await connection2.close();

Client Properties

ClientProperties is an object that contains information about the client that a consumer uses to connect to Messaging Platform. This includes not only device and browser information, but also information about the specific messaging features supported by the particular UI client they are connected through.

Example:

const clientProperties = lpm.createClientProperties({
    deviceFamily: lpm.DeviceFamily.DESKTOP,
    deviceManufacturer: 'Apple',
    deviceModel: 'MacBook Pro',
    os: lpm.OS.OSX,
    osName: 'macOS',
    osVersion: '11.6.8',
    ipAddress: '127.0.0.1',
    browser: 'CHROME',
    browserVersion: '47.0',
    timeZone: 'America/Los_Angeles',
    features: [lpm.Features.AUTO_MESSAGES, lpm.Features.PHOTO_SHARING]
});

const consumerConnection = lpm.createConnection({
    appId: 'quick_start',
    accountId: '123456',
    userType: UserType.CONSUMER,
    clientProperties
});

await consumerConnection.open();

Conversation Context and Campaign Info

To create a conversation with a given context and or campaign, use the following syntax. Keep in mind that client properties should be sent during connection creation.

const context = {
    type: lpm.ConversationContextType.SHARK,
    lang: 'en-US',
    visitorId: '',
    sessionId: '',
    interactionContextId: '2'
};

const campaignInfo = {
    campaignId: '111',
    engagementId: '222'
};

const conversation = await connection.createConversation({context, campaignInfo});

Consumer Auth Flow

By default, consumer connections will be made in "anonymous" mode. Some customers have set up Consumer Authentication for their account. To make an authenticated consumer connection, your application must provide the authenticated connector id (usually the connector of type=2) and a jwtClaimsSet.

const connection = lpm.createConnection({
    appId: 'quick_start',
    appVersion: '1.6.2',
    accountId: '123456',
    userType: UserType.CONSUMER,
    authConnectorId: '1234567890',
    jwtClaimsSet
});

How to create a jwtClaimsSet

You can create a jwtClaimsSet by calling createJwtClaimsSet, you can pass in structured data elements (SDEs) in an array. These can be created by using createCustomerInfoSde and createPersonalInfoSde, all of the fields are optional.

The jwtClaimsSet can either be a pre-encrypted base64 encoded string, or it can be a json object.

const customerInfoSde = lpm.createCustomerInfoSde({
    cstatus: '',
    ctype: '',
    balance: '',
    customerId: '12345',
    lastPaymentDate: '',
    registrationDate: '',
    loginStatus: '',
    companyBranch: '',
    socialId: '',
    imei: 'phonenumber',
    userName: 'admin',
    companySize: '',
    accountName: 'company',
    role: 'Administrator'
});

const personalInfoSde = lpm.createPersonalInfoSde({
    firstname: '',
    lastname: '',
    gender: '',
    language: '',
    company: '',
    age: ageObject,
    contacts: arrayOfContacts
});

const jwtClaimsSet = lpm.createJwtClaimsSet({
    sub: '0000000001',
    phoneNumber: "5550005555",
    preferredUsername: "ADMIN1",
    email: "test-example@lp.mokdd",
    sdes: [
        customerInfoSde,
        personalInfoSde
    ]
});

Getting a User Profile

In order to retrieve authenticated consumer data or an agent's profile, call getUserProfile, which is available on any conversation participant.

const consumerProfile = await conversation.consumer.getUserProfile();
const agentProfile = await conversation.assignedAgent.getUserProfile();

Alternatively, you can access all of the participants of a dialog at conversation.openDialog.participants. Note that consumers can only call getUserProfile on their own participant object; they cannot access agent or bot profiles.

Set User Profile

To set a user profile outside of using the consumer auth flow, you can use setUserProfile. Most of these fields are optional, and it is very common to call this function with just firstName, lastName, and nickName alone.

const data = {
    "firstName": "1",
    "lastName": "2",
    "nickName": "3",
    "userId": "",
    "avatarUrl": "",
    "role": "",
    "backgndImgUri": "",
    "description": "",
    "privateData": {
        "mobileNum": "",
        "mail": "",
        "pushNotificationData": {
            "serviceName": "",
            "certName": "",
            "token": ""
        }
    },
    "claims": {
        "lp_sdes": [
            customerInfoSde,
            personalInfoSde
        ]
    }
};

await connection.setUserProfile(data);

Consumer Step Up

Consumer stepup is a process by which an unauthenticated consumer connection is "stepped up" to be an authenticated connection. First, create an unauthenticated consumer connection by providing an unauthenticated connector id and opening the connection:

const connection = lpm.createConnection({
    appId: 'quick_start',
    appVersion: '1.6.2',
    accountId: '123456',
    userType: UserType.CONSUMER,
    unauthConnectorId: '1234567890'
});
await connection.open();

The consumer can create a conversation as usual. When the consumer logs in and you are ready to upgrade the connection to Messaging Platform, call the stepUp function, passing in the authenticated connector id, and the jwtClaimsSet. This will get an authenticated JWT, then disconnect and reconnect using the new JWT. It will then issue a "takeover" command for any existing open conversation, so that the authenticated consumer takes ownership of the conversation, thereby completing the stepUp.

const authConnectorId = '0987654321'
await connection.stepUp(authConnectorId, jwtClaimsSet);

Features Not yet supported

Agent State Subscriptions
Conversation/Dialog level metadata (Message Metadata is available)
AgentRequestConversation for resuming conversations from the Agent side
SendAPI

Faster Better answers through AI

Overview