The Web Tag (or lpTag) provides ‘Hooks’ to allow a website JavaScript callback function to be invoked to 'interfere' with certain events, by modifying their data before the logical execution proceeds.

These 'Web Tag Hooks' also provide transparency into data for engagement attributes (SDEs), embedded chat/messaging windows, visitor/agent messages, cobrowse sessions, and more.

Below you can find a list of hooks available on a web page by the Web Tag, labeled by event name.

Register a hook

Use the lpTag.hooks.push function to register a hook, where the hook's callback function is synchronous JavaScript.

lpTag.hooks = lpTag.hooks || [];

lpTag.hooks.push({
  name: "BEFORE_SEND_VISITOR_LINE",
  callback: function (event) {
    event.data.line.text = "This text has been interfered with by a hook."; // modify event data object as desired
    return event; // return interfered/modified event data
  }
});

Async hooks should be used as following (currently the only hook that support async flow is "BEFORE_WELCOME_MESSAGE" hook, keep in mind that the timeout of the function represent the time it will take the welcome message to be shown to the visitor and try to minimize that as much as possible)

lpTag.hooks.push({
    name: "BEFORE_WELCOME_MESSAGE",
    isAsync: true,
    callback: function (options, successCallback, errorCallback) {
        setTimeout(() => {
            const quickReplyExample = {
                replies: [{
                    click: {
                        actions: [{
                            text: "Async Button 1 Clicked",
                            type: "publishText"
                        }]
                    },
                    title: "Async Button 1",
                    tooltip: "Async Button 1",
                    type: "button"
                }, {
                    click: {
                        actions: [{
                            text: "Async Button 2 Clicked",
                            type: "publishText"
                        }]
                    },
                    title: "Async Button 2",
                    tooltip: "Async Button 2",
                    type: "button"
                }],
                type: "quickReplies"
            };
            const contents = [
                {
                    "source": "agent",
                    "by": "Info",
                    "isWelcomeMessage": true,
                    "text": "This welcome message text has been interfered with by an ASYNC hook.",
                    "type": "line",
                    "quickReplies": quickReplyExample
                },
            ];
            options.data.content = contents;
            successCallback(options);
        }, 3000);
    }
});
Parameter name Type Description
name String The name/type of "hook"-able event Below you can find a list of available hook names/types.
callback Function The callback function for the hook.
Parameter - 'event': an object with the event data for interfering/modifying
Returns - an object containing the interfered/modified data.
- if a non-object parameter is returned, it will be ignored, and the input object will be used.
- should be the original input object (or in the same/similar format).

Multiple hooks for the same event/name can registered, and will be executed by the order they were “pushed”. Ex. If param1 was changed on hook1, hook2 will get param1 after the change.

Valid hook

function hookCallback(event) {
  // modify event.data object in some way (synchronous code)
  // ...
  return event; // return interfered/modified event data
}

Invalid hooks

function hookCallback(param1, param2) { // must be one parameter with the event data for interfering/modifying
  return param1;
}

function hookCallback(event) {
  return 'some string'; // must return an object containing the interfered/modified data
}

function hookCallback(event) {
  setTimeout(() => {
    return event; // must return data with synchronous JavaScript
  }, 3000);
}

Limitations

  • The hook callback function creator is responsible for integrating properly, testing, and not causing bugs / edge cases
  • Hooks will not be executed on an external web messaging window; the window must be embedded in the brand webpage to access the callback functions.
  • In the future when taglet “scope” will be supported, hooks will be supported only if the hook is inside a site taglet.
  • Hook callbacks must be synchronous JavaScript.

Available hooks

Below are the various types of available hooks, labeled by event name (e.g. 'BEFORE_SEND_SDE').

Engagement Attribute (SDE) hooks

'BEFORE_SEND_SDE'

Use case / interference: Add/change/remove engagement attribute (i.e. Standard Data Entity (SDE))
Event timing: before engagement attribute / SDE is persisted on the platform (after SDE is programmatically triggered)
Event data:

{
  "data": {
    "sdes": [{...}, {...}, ..]
  }
}
Parameter name Type Role Data structure
sdes array (object) List of engagement attribute / SDE objects to modify Engagement attribute / SDE object examples

Survey hooks

'AFTER_GET_SURVEY'

Use case / interference: Add/change/remove survey questions or pre-fill answers
Event timing: after the configured survey data is retrieved (before displaying the survey to the visitor)
Event data:

{
  "data": {
    "surveyType": "...",
    "surveyData": {...}
  }
}
Parameter name Type Role Data structure
surveyType string Type of survey submitted (not meant to be modified) 'offlineSurvey' | 'preChatSurvey' | 'postChatSurvey'
surveyData object List of survey questions and pre-filled answers to modify *See below for example data structure
'surveyData' example data structure:
{
  "header": "",
  "id": 1058794,
  "questions": {
    "question": [
      {
        "type": "Text Field",
        "validationType": "alpha_numeric",
        "id": 5567213,
        "logicId": 2,
        "order": 0,
        "mandatory": true,
        "label": "From Name:",
        "lastKnownValue": ""
      }
    ]
  }
}

'AFTER_LOAD_SURVEY'

Use case / interference: Run custom logic based on the displayed survey (changes not persisted)
Event timing: after the survey is displayed
Event data:

{
  "data": {
    "context": {...}, 
    "surveyType": "...",
    "surveyData": {...}
  }
}
Parameter name Type Role Data structure
context object Messaging window application context data (not meant to be modified)
surveyType string Type of survey submitted (not meant to be modified) 'offlineSurvey' | 'preChatSurvey' | 'postChatSurvey'
surveyData object List of survey questions and pre-filled answers (not meant to be modified) *See below for example data structure
'surveyData' example data structure:
{
  "header": "",
  "id": 1058794,
  "questions": {
    "question": [
      {
        "type": "Text Field",
        "validationType": "alpha_numeric",
        "id": 5567213,
        "logicId": 2,
        "order": 0,
        "mandatory": true,
        "label": "From Name:",
        "lastKnownValue": ""
      }
    ]
  }
}

'BEFORE_SUBMIT_SURVEY'

Use case / interference: Add/change/remove survey answers
Event timing: before the survey submission is persisted on the platform (after the survey is submitted by the visitor)
Event data:

{
   "data": {
     "surveyType": "...",
     "questionsInfo": [{...}, {...}, ..],
     "surveyData": {...}
  }
}
Parameter name Type Role Data structure
surveyType string Type of survey submitted (not meant to be modified) 'offlineSurvey' | 'preChatSurvey' | 'postChatSurvey'
questionsInfo array (object) List of survey questions (not meant to be modified) *See below for example data structure
surveyData object List of survey answers to modify *See below for example data structure
'questionsInfo' example data structure:
[{
  "type": "Text Field",
  "validationType": "alpha_numeric",
  "id": 5567213,
  "logicId": 2,
  "order": 0,
  "mandatory": true,
  "label": "From Name:",
  "lastKnownValue": "asf"
}]
'surveyData' example data structure:
{
  "survey": {
    "id": 1058794,
    "question": [
      {
        "id": 5567213,
        "answer": "asf"
      },
      {
        "id": 5567214,
        "answer": "sadf@asf.con"
      }
    ]
  }
}

'AFTER_SUBMIT_SURVEY'

Use case / interference: Run custom logic based on SMS deflection survey (changes not persisted)
Event timing: after the SMS deflection survey submission was (attempted to be) persisted on the platform
Event data:

{
  "data": {
    "context": {...}, 
    "status": "...",
    "surveyType": "PreSmsSurvey",
    "surveyData": {...}
  }
}
Parameter name Type Role Data structure
context object Messaging window application context data (not meant to be modified)
status string Status of SMS deflection form submission (not meant to be modified) 'success' | 'fail'
surveyType string Type of survey submitted (not meant to be modified) Always "PreSmsSurvey"
surveyData object List of survey questions and pre-filled answers (not meant to be modified) *See below for example data structure
'surveyData' example data structure:
{
  "header": "",
  "id": 1058794,
  "questions": {
    "question": [
      {
        "type": "Text Field",
        "validationType": "alpha_numeric",
        "id": 5567213,
        "logicId": 2,
        "order": 0,
        "mandatory": true,
        "label": "From Name:",
        "lastKnownValue": ""
      }
    ]
  }
}

'AFTER_ABANDONED_SURVEY'

Use case / interference: Run custom logic based on a cancelled/abandoned survey (changes not persisted)
Event timing: after a survey was cancelled/abandoned by the visitor
Event data:

{
  "data": {
    "context": {...}, 
    "surveyType": "...",
    "surveyData": {...}
  }
}
Parameter name Type Role Data structure
context object Messaging window application context data (not meant to be modified)
surveyType string Type of survey submitted (not meant to be modified) 'offlineSurvey' | 'preChatSurvey' | 'postChatSurvey'
surveyData object Contains CSAT status (may be null / not meant to be modified) *See below for example data structure
'surveyData' example data structure:
{
  "status": "SKIPPED"
}

Message hooks

'BEFORE_SEND_VISITOR_LINE'

Use case / interference: Add/change/remove an outgoing visitor message (line)
Event timing: before ongoing visitor message is sent to the agent, or displayed (after visitor presses 'send')
Event data:

{
  "data": {
    "line": { ... }
  }
}
Parameter name Type Role Data structure
line object Text the visitor is sending to agent (can be modified) *See below for example data structure
'line' example data structure:
{
  "text": "Can you help me?"
}

'AFTER_GET_LINES'

Use case / interference: Add/change/remove incoming messages (lines) that the visitor recieves
Event timing: after incoming messages have been recieved for the visitor (before incoming messages are displayed to the visitor)
Event data:

{
  "data": {
    "lines": [{...}, {...}, ..],
  }
}
Parameter name Type Role Data structure
lines array (object) List of incoming messages (lines) for the visitor to be modified ('text' value is most common) *See below for example data structure
'lines' example data structure:
[
  {
    "@id": "4",
    "@type": "line",
    "time": "2017-03-02T11:51:02.545+02:00",
    "textType": "html",
    "text": "How may I help you?",
    "by": "tester@liveperson.com",
    "source": "agent",
    "subType": "REGULAR",
    "type": "line",
    "localId": 2
  }
]

'BEFORE_WELCOME_MESSAGE'

Use case / interference: Override the welcome messages
Event timing: Before the welcome message is shown to the visitor
Event data:

{
  "content": [
    {
      "source": "...",
      "by": "...",
      "isWelcomeMessage": ...,
      "text": "...",
      "type": "..."
    }
  ]
}
Parameter name Type Role Data structure
content array (object) List of incoming messages (lines) for the visitor to be modified ('text' value is most common) *See below for example data structure
Before_welcome_message hook example data structure:
{
  "content": [
    {
      "source": "agent",
      "by": "Info",
      "isWelcomeMessage": true,
      "text": "This welcome message was injected in runtime.",
      "type": "line"
    },
    {
      "source": "agent",
      "by": "Info",
      "isWelcomeMessage": true,
      "text": "How may I help you, Mike?",
      "type": "line"
    }
  ]
}

Window state hooks

'ON_WINDOW_CLOSED'

Use case / interference: Run custom logic based on the messaging window closing (changes not persisted)
Event timing: when the messaging window is closed
Event data:

{
  "data": {
    "context": {...}
  }
}
Parameter name Type Role
context object Messaging window application context data (not meant to be modified)

'ON_EXTERNAL_LAUNCH'

Use case / interference: Run custom logic based on the messaging window opening externally (changes not persisted)
Event timing: after the the messaging window was opened externally
Event data:

{
  "data": {
    "type": "...",
    "engConf": {...},
    "externalTarget": {...}
  }
}
Parameter name Type Role Data structure
type string Type of external launch (not meant to be modified) 'popout' | 'tapToText'
engConf object Engagement configuration data (not meant to be modified)
externalTarget object External target data (not meant to be modified)

Rich content hooks

'ON_ADD_TO_CART'

Use case / interference: Run custom logic and modify data from the ‘add to cart’ action of rich content (integrate shopping cart functionality with LivePerson)
Event timing: on the trigger of the ‘add to cart’ action of rich content (visitor clicks/presses to 'add to cart')
Event data:

{
  "data": {
    "type": "addToCart",
    "items": [{...}, {...}, ..],
  }
}
Parameter name Type Role Data structure
type string Type of rich content action (not meant to be modified) Always 'addToCart'
items array (object) List of items being 'added to the cart' to be modified *See below for example data structure
'items' example data structure:
[
  {
    "productId": "5567213",
    "quantity": 3
  }
]