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.

Messaging events for Function Invocation

LiveEngage messaging uses a series of "Conversation State Change Events" which get fired when specific actions or events occur within the conversation. You are able to use theses events to trigger functions within Functions.

The following "Conversation State Change Events" can be used to trigger functions:

New Conversation

This event is fired when a consumer initiates a new conversation.

TTR (Time to Respond) changed

This event is fired by the consumer or by the agent. This event is fired by the consumer when they mark the conversation as urgent or unmark it as such. This event is fired by the agent when they change the TTR.

Participants Change

This event is fired if an agent or a consumer joins or leaves the conversation.

Conversation Idle

This event is fired if a consumer or agent did not respond within the configured idle time for the account.

Conversation Routing

This event is fired if the conversation is routed to a different skill

Messaging Line in Off-Hours

This event is fired if a conversation was opened during office-hours, but a new consumer line in the conversation is written during off-hours (essentially when a consumer sends an off-hour message).

Conversation End

This event is fired when a conversation is closed.

Note: If no message is set in the result of the function (which it returns to the invoker), the default automatic message for the account will be triggered.

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

  • Transfer Conversation to a different Skill

  • 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-by-Step implementation guide

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 to a new skill
       skillId: "123456"
   },
   {
       type: "closeConversation" // Closes the conversation
   }
]
callback(null, result);

Step 4 - 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 172.26.138.38
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