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);
    }
});

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": [{...}, {...}, ..]
  }
}

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": {...}
  }
}

'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": {...}
  }
}

'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": {...}
  }
}

'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": {...}
  }
}

'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": {...}
  }
}

'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": { ... }
  }
}

'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": [{...}, {...}, ..],
  }
}

'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": "..."
    }
  ]
}

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": {...}
  }
}

'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": {...}
  }
}

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": [{...}, {...}, ..],
  }
}

'items' example data structure:

[
  {
    "productId": "5567213",
    "quantity": 3
  }
]