Bot integration

Bot types

Unblu supports two types of bot: dialog bots and conversation-observing bots.

Dialog bots are bots that have a one-to-one dialog with a user during the onboarding, reboarding, or offboarding phase of that person.
Conversation-observing bots are bots that listen to any message in any conversation (or even other webhooks or outbound web API events that the Unblu server sends) and chime in when they’re required.

Dialog bots

Dialog bots tap in to the onboarding, reboarding, or offboarding process of a person into or out of a conversation.

Unblu provides tailored APIs 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 a 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
- 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 appear as part of a bot thread. For more information about bot threads, refer to the 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 is slower than usual. It merely means that Unblu is unable to complete the onboarding process without the visitor opening the conversation.

Setting up a dialog bot

The first step when integrating a dialog bot is to set it up.

If you haven’t created a bot person yet, do that first.

Next, create a dialog bot. This involves defining things such as the endpoint for outbound requests, which persons should be on- and offboarded, and so on. You must also specify which version of the Unblu web API the dialog bot targets.

Reboarding can only be enabled or disabled as it only involves the visitor. For more details refer to the documentation of the /bots/create endpoint.

Dialog bots must be enabled in the conversation template that Unblu should offer to include them in. To do so, review configuration properties com.unblu.conversation.bot.enableAllExternalBots, com.unblu.conversation.bot.mandatoryExternalBotIds, and com.unblu.conversation.bot.optionalExternalBotIds on the conversation template in question.

With that done, your dialog bot is ready to participate in the onboarding, reboarding, or offboarding of the configured persons.

Receiving and responding to a dialog offer

Once the dialog bot is set up, the Unblu server sends it an outbound request with a dialog offer each time a person matching the configured filter joins, rejoins, or leaves the conversation, respectively. The specific outbound requests are:

An outbound.bot.onboarding_offer with a BotOnboardingOfferRequest in the HTTP request body
An outbound.bot.reboarding_offer with a BotReboardingOfferRequest in the HTTP request body
An outbound.bot.offboarding_offer with a BotOffboardingOfferRequest in the HTTP request body

(This article only discusses the onboarding case, but the reboarding and offboarding cases follow the same lines.)

In the most common cases, the visitor is the dialog counterpart person. 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.

References to the visitor below actually mean the dialog counterpart person.

The onboarding offer 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 outbound.bot.onboarding_offer, its HTTP response to that offer must contain a BotBoardingOfferResponse. If it doesn’t respond to the offer in a timely manner, the Unblu server considers the bot to be not working and automatically excludes it from the further onboarding after a short timeout.

Each event the Collaboration Server sends has a corresponding response associated with it. The boarding offer events all share the same response type.

The table below shows the events and their associated response type:

Table 1. Outbound events and the associated response types
Outbound event	Response type
`BotOnboardingOfferEvent`	`BotBoardingOfferResponse`
`BotReboardingOfferEvent`
`BotOffboardingOfferEvent`
`BotDialogOpenRequest`	`BotDialogOpenResponse`
`BotDialogMessageRequest`	`BotDialogMessageResponse`
`BotDialogMessageStateRequest`	`BotDialogMessageStateResponse`
`BotDialogCounterpartChangedRequest`	`BotDialogCounterpartChangedResponse`
`BotDialogClosedRequest`	`BotDialogClosedResponse`

If the bot declines the dialog offer, the bot’s participation in this onboarding ends there. Unblu doesn’t send any further outbound web API events for this onboarding.

If the bot accepts the offer, the dialog token passed in the body of the outbound.bot.onboarding_offer is used for all subsequent outbound web API events of this dialog. The bot is placed in the onboarding queue with all the other bots that have accepted the offer.

When it’s the turn of the bot to continue the visitor’s onboarding, Unblu sends it an outbound.bot.dialog.opened outbound request. 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 outbound request 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, so as to reference it later on.

The dialog remains open, and the bot is the only party interacting with the visitor, until Unblu sends the outbound.bot.dialog.closed outbound request. For more information about this, refer to the section closing a dialog below.

Even though a bot may have accepted a dialog offer, there’s no guarantee that it will receive the DialogOpen event for this dialog. The reason for this may be that the conversation is ended or deleted before it’s the bot’s turn, or that another bot solves or aborts the dialog. To avoid memory leaks, you should therefore make sure your bot implementation doesn’t keep any state from the dialog offer and dialog open requests.

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, Unblu sends the bot an outbound.bot.dialog.message outbound request 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 calling the /bots/finishDialog web API endpoint. When you finish a dialog with the web API, the reason for ending the dialog may be 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, the process is handed 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 isn’t 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 outbound web API `BotDialogClosedEvent`

When a dialog is closed, Unblu sends an outbound.bot.dialog.closed outbound request. This may occur as the 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, and so on.

The body of your response must be an empty JSON response.

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.

Responses to bot dialog events

Each bot dialog event that Unblu sends as an outbound request has a response schema associated with it. However, only the schema for outbound requests relating to boarding offers, BotBoardingOfferResponse, has a well-defined body.

For all other bot dialog events, you can respond with an empty JSON response.

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 occurs if the following conditions are met:

The configuration property com.unblu.authentication.allowVisitorLoginDuringSession is true
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 changes their identity from an anonymous to an authenticated person.

To inform the bot of this change, Unblu sends an outbound.bot.dialog.counterpart_changed outbound request. The body of the request 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 reference the new person and the new person’s PersonPresence. Unblu makes sure that any messages sent by the bot are received by and displayed to the person’s new identity.

You must ensure that all bot logic referring to the identity of the counterpart person (such as their name, email address, or authentication information) references the new, authenticated person after an outbound.bot.dialog.counterpart_changed outbound request.

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.

Conversation-observing bots

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

The integration of this sort of bot uses a low-level API that allows a flexible integration of bots into any conversation. Unblu provides web API endpoints 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, you 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 system messages appear when they join or leave the conversation.

Bot persons

To participate in a conversation and write messages, a bot always needs a "person" that represents it. This includes things like the name and the avatar that are displayed when the bot sends messages.

Like humans, a bot must first join a conversation with their person. This gives them an active participation and enables them to send messages in that conversation. While this is done automatically for dialog bots, you have join with separate web API calls for conversation-observing bots.

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

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 outbound web API BotDialogOpenEvent. 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 isn’t 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 larger value, for example 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.

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 or an outbound web API 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 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.