Contact usRequest a demo

Bot integration

This article 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.

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

  • Conversation-observing bots use the webhooks and outbound web API events provided by the Unblu web API to detect situations in which they can contribute to a conversation.

Conversation-observing bots and custom dialog bots are integrated using webhooks, outbound web APIs, and the Unblu web API. The integration usually looks something like this:

Bot integration architecture

The Bot Integration component at the heart of the diagram above connects the actual bot framework (RASA or the Microsoft Bot Framework, for example) with the Unblu server. It allows for the integration of existing bots into Unblu:

  • Outbound requests received from the Unblu server are translated into a format that the bot framework understands.

  • Conversely, messages and actions from the bot framework are translated into the correct response types for the Unblu server.

For communication with bots based on Microsoft Copilot agents, Unblu Spark uses the Direct Line 3.0 API, not the Unblu web API.

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 /persons/createOrUpdateBot endpoint. 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 to your organization of using a bot.

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:

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.

See also