Html Escalation Adapter

Introduction

The purpose of this adapter is to confirm a user's intent to escalate, and call an HTML form to gather the data required to escalate.

Once the user completes the form, the intent executes a js_callback: escalate that triggers the escalateToAgent action on the Chatbot SDK. At this point, the second adapter is subscribed to the escalate action, to retrieve the information and initiate the live chat.

Internal Adapter

This adapter is included in the Chatbot SDK to facilitate the steps to integrate Hyperchat and the escalation.

To use an internal adapter, you must set the adapters array like this:

adapters: [
    SDKcreateHtmlEscalationForm(checkAgents, questions, rejectedEscalation, noAgentsAvailable, true)
]

Note: The SDK at the beginning of the function name is what forces the SDK to use the internal adapter.

If this adapter meets your requirements, you can use it as explained above. Because it is included in the Chatbot SDK, no extra files or downloads are needed.

Escalate conditions

  • The bot shows the escalation form when the user sends a message (The force parameter must be true).
  • The bot asks the user if they want to speak with a human when the user sends a message. This shows as a systemMessage - with the label escalate-chat as the message (The force parameter must be false).
  • User rejects the escalation: rejectedEscalation is displayed (For more information, see below).

    • User accepts the escalation:
      • If there are agents available, an HTML form opens in the customWindow.
      • If there are no agents available, noAgentsAvailable value is displayed (see below for more information).

Configuration parameters

The createHtmlEscalationForm function creates the adapter. These are the entry parameters:

  • External checkAgents function: This must be a function. It comes from the external chat adapter and checks if there are available Agents. If you use the code samples below, make sure to replace checkAgents with the appropriate function name from your chosen product.

  • questionsConfiguration: An array with all the form questions. Each question has to be an object, with the following parameters:

    • label <string>: the key for this question in the object passed in the escalateToAgent action.
    • text <string>: the text to show near to the input element in the form.
    • type [<string>]: input (default) | textarea the type of form element.
    • validate [<function>]: a function to execute when the user changes the input value or when user submits the form. If no function is passed, no validation will be applied for that question. Signature of validate function:
      • validate(newValue: <string>): <boolean>. newValue is the new value user has inserted in the input. The returned value must be set to true if the newValue passed the validation, false otherwise.
  • rejectedEscalation: message that opens as a chatbotMessage when the user rejects the escalation.

  • noAgentsAvailable: message that opens as a chatbotMessage when there are no agents available and the client has tried to speak with a human.

  • forceForm: This must be set to true if you want to show the form when the user writes a message without asking to escalate, false otherwise.

Example
In this example, the bot shows a message that asks to escalate each time the user writes a message. We will be using the internal adapter.

// rejected escalation displays "What else can I do for you?" as a `chatbotMessage`.
var rejectedEscalation = 'What else can I do for you?';

// `noAgentsAvailable` appears as a `chatbotMessage`.
var noAgentsAvailable = 'There are no agents available just now.';

// question configuration
var questions = [
    {
        label: 'FIRST_NAME',
        text: 'What\'s your first name?',
        validationErrorMessage: 'Your first name is not correct',
        validate: function(value) {
            if (value !== '') {
                return true;
            }
            return false;
        }
    },
    {
        label: 'LAST_NAME',
        text: 'What\'s your last name?',
        validationErrorMessage: 'Your last name is not correct',
        validate: function(value) {
            if (value !== '') {
                return true;
            }
            return false;
        }
    },
    {
        label: 'EMAIL',
        text: 'What\s your email?',
        validationErrorMessage: 'Your email is not correct',
        validate: function(value) {
            return /^\s*[\w\-\+_]+(\.[\w\-\+_]+)*\@[\w\-\+_]+\.[\w\-\+_]+(\.[\w\-\+_]+)*\s*$/.test(value);
        }
    },
    {
        label: 'CONTACT_REASON',
        text: 'Can you briefly explain your problem?',
        type: 'textarea'
    }
];

// IMPORTANT: You must subscribe the chat adapter **first**. This way, when the chat is enabled, it interrupts the `sendMessage`, and the HTML escalation form does not open when user writes to the agent.

var authorization = {
  domainKey:"<your_domain_key>",
  inbentaKey:"<your_API_key>"
}
InbentaChatbotSDK.buildWithDomainCredentials(authorization, {
adapters: [
  ExternalChatAdapter(),
  SDKcreateHtmlEscalationForm(checkAgents, questions, rejectedEscalation, noAgentsAvailable, false)
]
});

This is the systemMessage that offers the escalation. To modify the displayed message, edit the labels in the configuration:

Escalation

The following message appears when the user rejects the escalation.

rejectedEscalation

The side window of the Chatbot is shown with the form we passed in the configuration:

initialForm

If the user changes a question which has defined a validate function and the new value is not valid, it will show the validationErrorMessage:

invalidAnswer

If at least one question has a validate function defined, and the answer for this question is not valid, then the system shows the validationErrorMessage when the user tries to submit the form:

invalidAnswer

In this example, the object passed in the escalateToAgent action is:

{
  CONTACT_REASON: 'hello',
  EMAIL: 'my@name.com',
  FIRST_NAME: 'my name',
  LAST_NAME: 'last name'
}

External Adapter code example

Inbenta recommends that you use the internal adapter. If you need custom features, the code samples below function the same way as the internal adapter, and can give you some insight on how to create your own escalation adapter.

In the case shown, the questions are directly created inside the adapter in the customFormHTML variable.

Caution: Inbenta does not support or maintain this code. For full support and guaranteed functionality, use the internal adapter.

Main page code (where the build is executed)

var authorization = {
  domainKey:"<your_domain_key>",
  inbentaKey:"<your_API_key>"
}
var noAgentsAvailable = {
    message:'There are no agents available just now. Try in a few minutes. Thanks!'
}
InbentaChatbotSDK.buildWithDomainCredentials(authorization, {
  closeButton:{
    visible:true
  },
adapters: [
  externalChatAdapter(),
  createCustomHTMLForm(externalChatAdapter.checkEscalationConditions, noAgentsAvailable)
]
});

Custom Escalation HTML Adapter code

Adapter code and public Github repository

This adapter can be found in the Inbenta Github adapters repository.

Click here to see the adapter code