This guide explains how to enable LivePerson Functions for messaging.

With Functions for messaging you are able to invoke lambdas from standard messaging events. For example, a new conversation start event could be chosen as the trigger to invoke a pre-created function.

Along with the invocation, the function is sent a payload containing metadata related to the conversation which invoked the function. This payload can then be used in the function for further processing and referencing.

It is required that your account has the Controller Bot permissions enabled; please contact your account team in order to do this.

Best Practices

Functions for messaging listens for messaging events asynchronously. As a consequence this can cause race conditions with other parts of the platform. Therefore, it is considered best practice to use bots instead of Functions for implementing routing logic. Functions is a good option to sync data with third-party systems like CRMs or to save data in the Conversation Context Service in order to use it within Conversation Orchestrator. Routing via Functions makes sense whenever a conversation is in a stagnant state (i.e. not in process of being routed), e.g. a conversation is idle or a message line has been sent in off-hours. Otherwise, the asynchronous nature of its events might interfere with the proper flow of a "dynamic" conversation.

if the authenticated consumer's previous conversation was auto-closed, and the new one opened within 48 hours of that, the new conversation event won't be triggered.

Messaging events for Function Invocation

Conversational Cloud messaging uses a series of "Conversation State Change Events" which are fired when specific actions or events occur within the conversation. You are able to use these events to trigger your functions.

Callback commands

You have the option to send callback commands back to the invoker. You can add multiple commands to the response as the functions itself can return an array or a single object.

With the controller bot as the invoker, as is the case for messaging events, you have the option to execute the following callback commands:

  • Send a message
  • If no message is set in the result of the function (which it returns to the invoker, for example: callback(); ), the default automatic message for the account will be triggered.
  • The default automatic message can be overwritten with { type: "systemMessage", text: "your message" }. To set the message empty just pass [] as text.
  • Transfer Conversation to a different Skill

  • Transfer Conversation to a different Agent (to configure this feature see here)

  • Close the Conversation

Using callback commands is not mandatory. If you only wish to use the events listed above to trigger functions and nothing else, there's no reason for you to pass callback commands back.

If you add more than one command of a certain type (e.g. 2 messages) only the first command of this type will be processed.

Please have a look at this page for further insight into the available events and their related templates. You can also have a look at the related templates per messaging-event within the LivePerson Functions application itself.

Step 1 - Create function

Create a new function using one of the messaging templates.

Currently, only one function per template type can be created. If there are multiple types of functionality needed that stem from the same event invocation, these should be coded into the same lambda.

Step 2 - Edit the Function

Adjust the coding from the template according to your needs by modifying the function. On the right side you can see an example of the payload (in the sidebar, which you might need to open):

As mentioned above, the function can return a series of commands back to the invoker. In the template code you can see the current available commands.

Here's an example of a response sent back to the invoker using a few of those commands:

let result = [
       type: "systemMessage", // Returns a system message into the conversation
       text: "your message"
       type: "transfer", // Transfers the conversation.
       skillId: "123456", // Transfer to different skill.
       agentId: "123456" // Propose an agent.
       type: "closeConversation" // Closes the conversation
callback(null, result);

Step 3 - Deploy the function

Just like any other function, this function must be deployed before it can be used. Please see this document for more information on how to deploy your function. At this point, you can also test your function.

Try to deploy functions with a runtime of less than one second. If the runtime is longer, you may get a bad user experience because of race conditions within the server. For example, if you create a function based on the Participants Change event and an agent joins the conversation, the consumer may see the resulting `systemMessage` after the agent already responded to the consumer themselves.

Payload Details

1. level 2. level 3. level description type example
end closeReason   which role closed conversation STRING AGENT/CONSUMER/SYSTEM
general type   notification type STRING UPSERT
general convId   ID of conversation STRING c840e51e-5f65-4ad4-8d34-5c82b99a2200
general dialogId   ID of dialog STRING c840e51e-5f65-4ad4-8d34-5c82b99a2200
general sessionId   ID of session NUMBER 1528463744580
general startTs   conversation start time as timestamp NUMBER 1528463744663
general effectiveTTR   timestamp when agent should be available NUMBER 1528464044687
general oldConvState   previous state of the dialog STRING CLOSE
general newConvState   current state of the dialog STRING OPEN
general contexttype   type of cotext STRING SharkContext
general campaignInfo id ID of campaign NUMBER 2327699812
general campaignInfo engangementId ID of engangement NUMBER 2327699912
general clientLanguage   language of the client device STRING en-US
general clientFeatures   list of supported client features ARRAY ["AUTO_MESSAGES", "MULTI_DIALOG"]
general inOffHours   shift-status of the contact center BOOLEAN TRUE/FALSE
general visitorId   ID of visitor NUMBER 1528463744580
general originatorId   ID of originator NUMBER 37607275.23
general originatorPid   Pid of originator STRING f39fbc5f-da77-5417-8bc7-7584efdd1a5e
general originatorMetadata id Pid of originator of metadata change STRING f39fbc5f-da77-5417-8bc7-7584efdd1a5e
general originatorMetadata role Role of originator of metadata change STRING CONTROLLER
general serverTimestamp   timestamp of the server NUMBER 1528463781807
general clientIpAdress   IP Address of client STRING
general manualETTR   time to response manually updated by agent STRING 1541152938069
general lastMessageComposer   the role of the last composer STRING CONSUMER
general lastMessageTs   timestamp of last message NUMBER 1541152938069
general lastAgentMsgTs   timestamp of last agent message NUMBER 1541152938069
general backToQueueTs   timestamp when the conversation was returned to queue NUMBER 1541152938069
idle lastConsumerMsgTs   timestamp of last consumer message NUMBER 1541152938069
idle agentNonResponsive time time that should pass after consumer's last message in order the agent to be non-responsive NUMBER 30
idle agentNonResponsive timeUnits time units in which agent non-responsive time should be calculated STRING minutes
idle consumserNonResponsive time time that should pass after agent's last message in order the consumer to be non-responsive NUMBER 30
idle consumserNonResponsive timeUnits time units in which consumer non-responsive time should be calculated STRING minutes
idle convNotTakenTime time time units in which conversation idle time should be calculated STRING minutes
idle convNotTakenTime timeUnits how long should the conversation stay in queue in order to be idle NUMBER 30
mid openedInOffHours   indicator if the conversation was opened in off hours BOOLEAN TRUE/FALSE
participantChange oldParticipants   array of the participants of the previous state ARRAY [{"id": "f9d58c57-c489-45f5-bae4-c5ebd52b3972","role": "ASSIGNED_AGENT"}]
participantChange newParticipants   array of the participants of the current state ARRAY [{"id": "f9d58c57-c489-45f5-bae4-c5ebd52b3972","role": "ASSIGNED_AGENT"}, {"id": "f9d58c57-c489-45f5-bae4-c5ebd52b3972","role": "AGENT"}]
routing oldSkillId   previous skillId of conversation STRING 563268
routing newSkillId   current skillId of conversation STRING 563267
start firstConversation   if this is the frist conversation of the consumer ever BOOLEAN TRUE/ FALSE
ttr oldTtr ttrType type of ttr of the previous state STRING NORMAL
ttr oldTtr value value of ttr of the previous state NUMBER 600
ttr newTtr ttrType type of ttr of the new state STRING URGENT
ttr newTtr value value of ttr of the new state (after change for example to URGENT) NUMBER 300