Message states
Message states help users understand what’s happening in a conversation. For example, if a user can see that their message is sent but not yet delivered to the other participant in the conversation, they understand why they have no reply yet.
The badge indicating a message’s state is always in the lower right-hand corner of the message that the 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 states with their respective badges:
- Pending
-
The message has been created locally, but it hasn’t been sent to the Unblu Collaboration Server yet.
This message state is displayed if there are issues connecting to the Unblu Collaboration Server. See the section on optimistic client changes below for details on how network issues are mitigated.
The pendingstate is handled differently for dialog bots and external messengers. See the relevant section below. - Sent
-
The message was successfully sent to the Unblu Collaboration Server but hasn’t been delivered to or read by its intended recipients yet.
- Delivered
-
The message was delivered to another user who is actively participating in a conversation.
Here Unblu behaves somewhat differently from other messengers such as WhatsApp. Since there may be many different channels Unblu has to send the message to (such as multiple browsers, mail, and webhooks), the system can only be sure that the message was delivered if a user received the message while they’re viewing the conversation in question. If the user is in the overview (for visitors) or the inbox (for agents), the message isn’t marked as delivered even though the user may see part of it as a preview of the conversation.
- Read
-
The message has been read.
A message is considered to have been read if the following two conditions are met:
-
The other user’s browser tab is currently visible (as determined with the Browser Visibility API).
-
The visitor UI is currently open and displaying the message.
For more information on when a message’s state changes to read, refer to the section on Configuringdeliveredandreadstates below.
-
- Failed terminal
-
The message couldn’t be sent and it isn’t possible to resend the message. A more detailed reason for the failure is displayed directly below the message.
This state may occur in combination with a message sent to an external messenger, for example. In that context, it means that the message couldn’t be sent to the external messenger.
- Failed retry
-
The message couldn’t 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.
This state, too, may occur when sending a message to an external messenger. It means that the message couldn’t 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’s clear that when, for example, an agent sends a message and the state of the message changes to read, the visitor has read the message.
On the other hand, if there are more than two participants in a conversation, it’s not obvious when to change the message’s state. You can therefore use the following two configuration properties to change message state according to your organization’s requirements:
-
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.
-
-
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.
Configuring the visibility of message states
In some scenarios, you may want to allow agents to see whether visitors received and read their messages but not allow visitors to see if the agents received and read their messages. In other cases, you may want to hide message states entirely.
You can configure which participant types, if any, are allowed to see message states using the com.unblu.conversation.message.allowSeeMessageStatus configuration property. By default, the assigned agent, context person, secondary agents, and secondary visitors can view message states.
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’s 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, that is, 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
deliveredor asread, or both. Messages remain in thependingstate 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
deliveredorread, or both. Messages remain in thependingstate 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 Unblu web API endpoints are different for external messengers and dialog bots. |
Optimistic client change mechanism for text and reply messages
Unblu provides an optimistic client change mechanism to mitigate any network issues that may arise during conversations.
When there is a network issue and a visitor or an agent sends a message, the message appears in the UI in pending state while the client tries to send the message to the Collaboration Server. The client waits for the connection to be reestablished and then tries to send the message to the server for 20 seconds or until it succeeds. If the message still can’t be sent, its state changes to failed retry and a Retry button is displayed so the visitor or agent can decide to try sending the message again or not.
When the connection is restored and the message sent, the server informs the client that the message has been received and the message state is updated from pending to sent.
Messages and their states are persisted in client-side session storage. When you restore the connection to a conversation by, for example, refreshing the browser page and returning to the conversation, the session storage restores the correct message statuses and ensures the server and client sides remain consistent. The optimistic client change mechanism doesn’t persist messages, however, if a user closes the browser tab and returns to the same conversation in a different tab.
Note that only text and reply message types use the optimistic client change mechanism. If a visitor or agent encounters a network issue when sending a file message type, for example, a red banner appears indicating that the file upload failed and the visitor or agent must try to send it again manually.