Bot integration

Bot types

Unblu supports several bot types which may be divided into two groups: dialog bots and conversation-observing bots.

Dialog bots are bots that have a one to one dialog with a visitor during the onboarding, reboarding or offboarding phase of that person.

Conversation-observing bots are bots that can listen to any message in any conversation (or even other webhook events that the Unblu server sends) and chime in when they please.

Bot persons

To participate in a conversation and write messages, a bot always needs a "person" that will represent it. This includes things like the name and the avatar that will be displayed when the bot writes messages.

Like humans, a bot must first join a conversation with their person (giving them an active participation) to enable them to send messages in that conversation. While this is done automatically for dialog bots, it must be done via separate web API calls for the conversation-observing bots.

Bot persons can be created and updated using the Person API. Different bot backends may share the same bot person.

Conversation-observing bots

These bots use generally available webhooks from the Unblu server to detect a situation in which they want to contribute to a conversation.

The integration of this sort of bot uses a rather low-level API that allows a flexible integration of bots into any conversation. Unblu provides web APIs to join a conversation with a bot person and then write different types of chat messages in the name of that bot person.

When adding a bot to a conversation, one can choose whether the bot’s participant should be visible or hidden. A visible participant behaves like a normal human participant. Hidden participants, on the other hand, aren’t displayed in the list of participants (for example in the title bar), and no messages are displayed when they join or leave the conversation.

Dialog bots

Dialog bots allow tapping into the onboarding, reboarding, or offboarding process of a person into or out of a conversation.

Unblu provides a tailored API to participate in this process allowing maximum focus on integrating the underlying bot framework with Unblu and minimum overhead of API calls:

Unblu makes sure only one person is in the dialog with the bot to allow seamless integration with existing bot frameworks.
Dialogs can be
- handed off to the next bot or an agent,
- solved so no further involvement from other bots or agents is required, or
- canceled to stop the boarding process.
Dialog bots can use all Unblu web API services during the dialog to alter conversations and persons.

If you add one or more dialog bots to the onboarding, reboarding, or offboarding process, the messages exchanged during the process will appear as part of a bot thread. To find out more about bot threads, please read the relevant section of our documentation on bot threads and the concierge and the conversation states ONBOARDING, REBOARDING, and OFFBOARDING.

Adding a dialog bot to the onboarding process precludes fast onboarding, because Unblu doesn’t know whether the bot will ask the visitor to answer any questions. This doesn’t mean the onboarding process will be slower than usual. It merely means that Unblu won’t be able to complete the onboarding process without the visitor opening the conversation.

Setting up a dialog bot

The initial step of integrating a dialog bot is to set it up.

If no bot person has been created yet, do that first.
Next, create a dialog bot. This involves defining things such as the webhook endpoint, which persons should be on- and offboarded and so on.

Reboarding can only be enabled or disabled as it only involves the visitor. For more details see the create DialogBot API.

Once this is done, your bot is ready to participate in the onboarding/reboarding/offboarding of the configured persons.

Bots must be enabled for a conversation type to be offered the interaction. This can be changed in the settings for the conversation type. Look for the setting called com.unblu.conversation.bot.externalBotsEnabled.

Receiving and responding to a dialog offer

Once the dialog bot is set up, the Unblu server will send a dialog offer webhook (more specifically, an onboarding, reboarding, or offboarding offer) each time a person matching the configured filter joins or leaves the conversation, respectively. We will only consider the onboarding case here, but the reboarding and offboarding cases follow the same lines.

When we speak of the visitor below, we actually mean the dialog counterpart person. We’ve chosen to refer to them as the visitor since this is the most common case. However, it’s also possible to onboard or offboard agents using a bot. (Reboarding, on the other hand, is only possible for the main visitor of a conversation.)

The onboarding offer webhook serves two purposes:

It allows the bot to decide whether they want to be part of the onboarding, with the full context of the onboarding person and the conversation they’re joining.
It ensures that the bot is available. This keeps visitor waiting time to a minimum if the bot were to malfunction.

When a bot receives a BotOnboardingOfferEvent webhook, it must respond to that offer as fast as possible. If it doesn’t, the Unblu server considers the bot to be not working and automatically excludes it from the further onboarding after a short timeout. Using the Unblu web API, a bot can either accept or decline the onboarding offer.

If the offer is declined, the bot’s participation in this onboarding ends here. No further webhooks will be sent for this onboarding.

If the bot accepts the offer, the web API call returns the dialog token that will be used later on for all webhooks of this dialog. The bot will be placed in the onboarding queue with all other bots that have accepted the offer. When it’s the turn of the bot to complete the onboarding for the visitor, it receives a BotDialogOpenEvent webhook. This is the signal that the dialog between the bot and the visitor is now open and the bot can start sending messages.

All state connected to a dialog should be linked to the dialog token. The dialog token is sent in every webhook related to this dialog and is needed for every dialog-related web API call. If a new context or conversation must be created for the underlying bot framework, this is the time to do it. The new context or conversation should be linked to the dialog token, which may be used to reference it later on.

The dialog remains open, and the bot is the only party interacting with the visitor, until the BotDialogClosedEvent webhook is received. More details about this can be found in closing a dialog

Even though a bot may have accepted a dialog offer there is no guarantee that it will receive the DialogOpen event for this dialog. Reasons for this can be that the conversation is ended or deleted before it’s the bot’s turn, or another bot solves or aborts the dialog. Therefore make sure that your bot implementation doesn’t keep any state during the dialog offer and the dialog open events to avoid memory leaks.

Disable file upload during onboarding and offboarding

By default, the Visitor UIs provide the same functionality during onboarding and offboarding as they do in other phases of a conversation. In particular, if the configuration property com.unblu.conversation.file.allowFileCobrowsing is true, visitors can upload files to a conversation during onboarding and offboarding.

If you wish to prevent this, set the following two configuration properties to false:

This will ensure that visitors can’t upload files to a conversation unless it’s either in the queue or has been answered by an agent.

The active phase of a dialog

During the active phase of a dialog, the bot can use the Unblu web API to send different types of chat messages to the visitor. The bot integration code may also use other web API services, such as the Conversations or Persons services, to influence the routing of the conversation or the visitor’s details. Additionally, the bot receives a BotDialogMessageEvent webhook for every message either the bot or the visitor sends.

Once the other party in the conversation sends a message, Unblu displays a typing indicator to let them know the dialog bot is preparing a response. The typing indicator stops after 4 seconds or when the bot sends a response, depending on which event occurs first. The typing indicator has a 1 second debounce so that it isn’t displayed repeatedly if the other party sends multiple messages in short succession.

By default, Unblu diplays the typing indicator automatically. You can also use the web API endpoints /bots/startDialogBotTypingIndicator and /bots/cancelDialogBotTypingIndicator to start and cancel the typing indicator, respectively. If you do, the conditions when the typing indicator stops remain the same, that is, after 4 seconds or when the dialog bot sends a response.

If an anonymous user logs in during this phase, this triggers a user change. For more information, refer to handling user changes below.

Closing a dialog

When the bot has solved the visitor’s issue, doesn’t know what to do, or has finished its onboarding tasks, it’s time to close the dialog.

There are several ways how this can be accomplished, but the usual way is by making the appropriate web API call. When finishing a dialog via web API, the reason for ending the dialog may be either HAND_OFF, SOLVED or ABORTED.

`HAND_OFF`

HAND_OFF means proceeding to the next step of the boarding process. If more than one bot responded to the boarding offer, and the current bot isn’t the last one in the queue, this is accomplished by handing the process over to the next bot in the queue.

If there is no further bot in the queue, what happens depends on the type of dialog.

For onboarding dialogs, hand-off will either
- activate the onboarding participation and put the conversation in the incoming queue if the conversation is a chat request, or
- activate the person being onboarded and allow them to interact with others for other conversation types or if the person was invited to join an ongoing conversation.
For reboarding dialogs, this will put the conversation back into the incoming queue if there is no further bot.
For offboarding dialogs, this will do one of the following either
- end the conversation if the offboarding was triggered by ending a conversation, or
- end the participation of the offboarding person if the offboarding was triggered by that person leaving.

`SOLVED`

SOLVED means that no further bot or human agent is required. The boarding process is stopped with a success indication. Any further bots that responded to the boarding offer will be ignored.

For onboarding and reboarding dialogs, this also:

Puts the conversation into the UNASSIGNED state if com.unblu.conversation.lifecycle.enableUnassignedState is enabled and the conversation was initiated by a visitor.
Ends the conversation if com.unblu.conversation.lifecycle.enableUnassignedState is disabled.

For offboarding dialogs, it also:

Ends the conversation if the offboarding was triggered by ending a conversation.
Ends the participation of the offboarding person if the offboarding was triggered by the leaving of that person.

`ABORTED`

ABORTED means that no further bots should be called. The boarding process is stopped with a failure indication. Any further bots that responded to the boarding offer will be ignored.

For onboarding dialogs, the participant is directly moved to the offboarding phase and won’t be allowed to enter the conversation.
For reboarding dialogs, the conversation is put into the UNASSIGNED state.
For offboarding dialogs, the participation of the person being offboarded is ended.

This reason can be used when, for example, the visitor doesn’t accept mandatory terms and conditions.

The `BotDialogClosedEvent` webhook

When a dialog is closed, a BotDialogClosedEvent webhook will be sent. This may occur as a result of the finishDialog API call. However, it may also be sent for other reasons: a timeout, the visitor leaves or ends the conversation manually etc.

Make sure your code integrating the bot can always handle this event and is able to clean up everything related to that dialog, even if the event isn’t expected at that point.

Handling user changes

If a visitor logs in during an active bot dialog phase, this may trigger a user change within Unblu. The user change will occur if

the configuration property com.unblu.authentication.allowVisitorLoginDuringSession is true, and
the configuration property com.unblu.conversation.lifecycle.replaceUserOnLogin is set to ALWAYS or IF_ACTIVE_CONVERSATION for the current conversation.

As a result of the user change, the bot’s counterpart in the dialog will change their identity from an anonymous to an authenticated person.

To inform the bot of this change, Unblu sends an additional BotDialogCounterpartChanged webhook event. The event contains both the old and the new person identifying the bot’s counterpart in the dialog. Once this event has been received, any further messages sent by the visitor will reference the new person and the new person’s PersonPresence. Unblu will make sure that any messages sent by the bot will be received and displayed to the person’s new identity.

You must ensure that all bot logic referring to the identity of the counterpart person (like their name, email address, authentication etc.) references the new, authenticated person after a BotDialogCounterpartChanged webhook event.

Managing `read` and `delivered` states

For information on how to handle message states with dialog bots, refer to Message states for external messengers and dialog bots.

Limiting the length of messages in bot dialogs

If your bot answers questions visitors enter as free text, it has to parse the text to determine whether it can answer the question. The longer the text the visitor entered, the harder this gets. Long texts can reduce the number of questions the bot can answer. This, in turn, reduces the benefits using a bot provides your organization.

The configuration property com.unblu.conversation.message.chatTextInputMaxLength lets you limit the length of the messages conversation participants can enter. However, it limits the length of all messages, not just those sent in conversations with bots. Furthermore, it’s set in the CONVERSATION or CONVERSATION_TEMPLATE scope, so you have to set it in the template of any conversation that the bot might join.

To limit the length of messages in a bot dialog, you can use the web API endpoint bots/restrictDialogCounterpart after receiving the bot.dialog.opened webhook event. The endpoint requires you to provide the dialog token of the current dialog and the maximum permissible length of a message. The limit only applies to the dialog you call the endpoint for and is reset once you hand off the dialog to an agent or the next bot.

You can change the maximum permissible length during a dialog. This is useful if, for example, you first want to give your bot a chance to answer simple enquiries. For these questions, you might limit the maximum permissible length to, say, 150 characters. When the bot decides it won’t be able to resolve the issue, it can ask the client for a detailed description before handing the conversation off to an agent. For this, you could increase the maximum length to a much larger value such as 1000 characters.

Unblu displays a hint informing the visitor of how many characters they can still enter. Use the configuration property com.unblu.conversation.messaging.ui.charactersRemainingHintThreshold to specify when Unblu should display the hint.

Using bots to perform requests on behalf of authenticated users

Bots can often deal with simple user inquiries without having to involve an agent in the conversation. This lets your agents focus on more complex issues.

Sometimes, obtaining the answer requires the bot to make a request to another system on behalf of the person asking the question:

A bot can tell a visitor their account balance, provided they can show to your core banking system that the person making the request may access that information. If the visitor is already authenticated by your system, that information can be made available to the bot through Unblu.
While onboarding an agent to a conversation, a bot may ask whether it should open their customer relationship management (CRM) system to display the client’s information. Again, the agent’s authentication information can be made available to the bot through Unblu.

This article describes how to perform requests on behalf of users that were authenticated using ID propagation.

Propagating authentication information

When you use ID propagation to authenticate Unblu users, you must specify which values should be propagated. Which propagated information should be used for authentication is specified in the following configuration properties:

com.unblu.authentication.propagated.public.authInfo for PUBLIC entry paths
com.unblu.authentication.propagated.internal.authInfo for INTERNAL entry paths

Retrieving authentication information

The values propagated during authentication, including the person’s authentication information, are stored in the user’s person presence. A bot must therefore know which person presence of the conversation contains the relevant authentication information, and be able to access the detail of that person presence.

When a webhook event related to a message is triggered, for example conversation.new_message, the message data in the payload includes the field senderPersonPresenceId. The field contains the person presence ID of the person who sent the message that triggered the webhook event.

Once you have the user’s person presence ID, you can call the web API endpoint /personpresences/read. The return value of the API endpoint includes fields for each of the propagated values. With this information, a bot can call a third-party system on the user’s behalf and retrieve the information required to answer the user’s question.