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 Chat SDK. At this point, the second adapter is subscribed to the escalate action, to retrieve the information and initiate the chat with an agent.

Internal Adapter

This adapter is included in the Chat SDK to facilitate the steps to integrate Agent Chat and the escalation.

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

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

If this adapter meets your requirements, you can use it as explained above. Because it is included in the Chat 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.

• labels: labels object to be used in the HTML escalation form. If this parameter or a specific label is not specified, it will use the default value.

  • submit <string>: text to be shown in the submit button (default: Submit).

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'
    }
];

var labels = {
    submit: 'Submit'
};

// IMPORTANT: You must subscribe to the chat adapter **first**. This way, when the chat is enabled, it interrupts the `sendMessage`, and the HTML escalation form does not open when the 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, labels)
]
});

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

The following message appears when the user rejects the escalation.

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

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

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:

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.

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.