Contact usRequest a demo

Dialog bots

Dialog bots have a one-to-one dialog with a user during the onboarding, reboarding, or offboarding phase of that person. Unblu supports two types of dialog bot:

Custom dialog bots

This section assumes your bot is targeting version 4 of the Unblu web API. If you’re using version 3, refer to the documentation of Unblu 7. Unblu 8 supports version 3 of the Unblu web API for reasons of backward compatibility only.

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 custom 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 the 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:

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

Version 4 of the Unblu web API still provides the old webhooks bot.onboarding_offer, bot.reboarding_offer, and bot.offboarding_offer to facilitate migrating from version 3 to version 4. In new implementations, use the outbound.bot.\* requests listed above.

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 context person of a conversation.

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

The onboarding offer serves two purposes:

  1. 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.

  2. 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 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 request events and the associated response types
Outbound event Response type

BotOnboardingOfferRequest

BotBoardingOfferResponse

BotReboardingOfferRequest

BotOffboardingOfferRequest

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 displays 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.

Bot Dialog 3 - Active

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:

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 BotDialogClosedRequest

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.
Bot Dialog 4 - Close

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:

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.

Microsoft Copilot agent dialog bots

Microsoft Copilot agent dialog bots use the Direct Line API 3.0 to communicate directly with Unblu Spark. You configure them in Microsoft Copilot Studio.

For information on setting up an agent for use with Unblu Spark in Microsoft Copilot Studio, refer to Creating Microsoft Copilot Studio agents for Unblu Spark.

See also