of 3

Documentation

Unblu 7 (latest)

Message states help users to understand what is happening in a conversation. For example, if a user can see at a glance that their message has been sent but not yet delivered to the other participant in the conversation, they will understand why they haven’t received a reply yet.

The badge indicating a message’s state is always in the lower right-hand corner of the message that user themselves sent. How message states work and the badge Unblu displays are aligned with other well-known messengers although there are some minor differences.

The following list provides an overview of all possible message state with their respective badges:

Pending

The message has only been created locally, but it has not yet been sent to the Unblu collaboration server.

A message with the state "pending"

This message state is displayed if there are issues connecting to the Unblu collaboration server.

The pending state is handled differently for dialog bots and external messengers. Please review the relevant section below.
Sent

The message was successfully sent to the Unblu collaboration server but has not been delivered to or read by its intended recipients yet.

A message with the state "sent"

Delivered

The message was delivered to another user who is actively participating in a conversation.

A message with the state "delivered"

Here Unblu behaves somewhat differently from other messengers such as WhatsApp. Since there can be many different channels (e.g. multiple browsers, mail, webhooks etc.) Unblu might have to send the message to, the system can only be sure that the message was delivered if a user received the message while he is viewing the conversation in question. If the user is in the overview (for visitors) or the inbox (for agents), the message will not be marked as delivered — even though they may see part of it as a preview of the conversation.

Read

The message has been read.

A message with the state "read"

A message is considered to have been read if the following two conditions are met:

  1. The other user’s browser tab is currently visible (as determined with the Browser Visibility API).

  2. The individual UI is currently open and displaying the message.

    Please review the section on Configuring delivered and read state below for further details on when a message’s state is changed to read.
Failed terminal

The message could not be sent and it is not possible to resend the message. A more detailed reason for the failure is displayed directly below the message.

A message with the state "failed terminal"

This state may occur in combination with a message sent to an external messenger, for example. In that context, it means that the message could not be sent to the external messenger.

Failed retry

The message could not be sent, but the user can try to send the message again. As with the state failed retry, a more detailed reason for the failure is displayed directly beneath the message.

A message with the state "failed retry"

This state, too, may occur when sending a message to an external messenger. It means that the message could not be sent to the external messenger, but it may have been due only to a temporary connection issue.

Configuring delivered and read states

In many integrations, there are only one-to-one conversations between two participants, a visitor and an agent. In this case it is clear that if, say, an agent sends a message and the state of the message changes to read, the visitor has read the message.

If, on the other hand, there are more than two participants in a conversation, it is not obvious when to change the message’s state. You can therefore using the following two configuration properties to change message state according to your organization’s requirements:

  1. com.unblu.conversation.message.markAgentMessagesAsReadCondition affects messages sent by agents. It takes one of the following possible values:

    • READ_BY_ALL_EXCLUDING_HIDDEN (default): A message must be read by all conversation participants except for hidden agents.

    • READ_BY_CONTEXT_PERSON: A message need only be read by the visitor who is the context person.

    • READ_BY_ANY_VISITOR: A message must be read by at least one visitor.

    • READ_BY_ALL_VISITORS: A message must be read by all visitors.

  2. For messages that were sent by visitors, the corresponding configuration property is com.unblu.conversation.message.markVisitorMessagesAsReadCondition.

    • READ_BY_ALL_EXCLUDING_HIDDEN (default): A message must be read by all conversation participants except for hidden agents.

    • READ_BY_ALL_AGENTS_EXCLUDING_HIDDEN: A message must be read by all agents except for hidden ones.

    • READ_BY_ASSIGNEE: A message need only be read by the agent who is the assigned agent.

    • READ_BY_ANY_AGENT_EXCLUDING_HIDDEN: A message must be read by at least one agent, excluding the hidden agents.

    • READ_BY_ANY_AGENT_INCLUDING_HIDDEN: A message must be read by at least one agent, including the hidden agents.

The two configuration properties affect the transition to both the read and the delivered state in the same manner.

Message states for external messengers and dialog bots

If a conversation is connected via an external messenger, the handling of the pending, sent and delivered states is slightly different. This is because of the need to properly integrate the external messenger into the Unblu environment. Furthermore, if dialog bots are used, it is possible to change the behavior for setting the delivered and read states.

Managing read and delivered states

How external messengers and dialog bots handle message state can be configured individually for each channel and dialog bot, respectively. By default message state is handled by the Unblu collaboration server. In this case, Unblu assumes that a message was delivered and read as soon as it has successfully sent the webhook request to the relevant endpoint.

If an external messenger channel or a dialog bot is configured to handle message state itself, this has an impact on messages sent in either direction, i.e both to and from the Unblu collaboration server.

  • For messages sent to an external messenger or a dialog bot, the collaboration server waits for a Web API call to mark messages either as delivered or as read, or both. Messages remain in the pending state for agents until one of the two endpoints mentioned above is called.

    If the external messenger handles message state, it must also automatically retrieve the webhooks for the messageState. This webhook is triggered if a message sent to Unblu by the external messenger was delivered to and/or read by an agent.

  • For messages sent to a dialog bot, the collaboration server waits for a Web API call to mark messages as either delivered or read, or both. Messages remain in the pending state for visitors until one of the two endpoints mentioned above is called.

    If the external messenger handles message state, it must also automatically retrieve the webhooks for the messageState. This webhook is triggered if a message sent to Unblu by the external messenger was delivered to and/or read by the recipient.

The Web API endpoints are different for external messengers and dialog bots.