Configuring invitations

Inviting agents and teams

To invite teams or other agents to a conversation, agents can use the Agent Desk as described in the Invite participant control section of the Agent Desk guide. Agents can also join a conversation using a public link as described below.

Which types of participant may invite agents and teams to join a conversation is controlled by the configuration properties com.unblu.conversation.invitation.allowInviteAgent and com.unblu.conversation.invitation.allowInviteTeam, respectively.

If an agent forwards a conversation to another agent, the agent the conversation is forwarded to is set as the recipient of the conversation. If you set com.unblu.conversation.invitation.setRecipientForForwardingTargets to false, the agent forwarding the conversation remains the recipient of the conversation. This is useful if the conversation should return to the previous queue or named area when the agent that the conversation was forwarded to declines the invitation, or if they resolve the issue and leave the conversation.

The Unblu web API has endpoints to invite agents and teams to conversations. For more information, refer to the Unblu web API reference.

Inviting visitors

The configuration property com.unblu.conversation.invitation.allowInviteVisitor specifies which types of participant may invite visitors to join a conversation.

To invite visitors to a conversation, agents can:

Generate a PIN for the visitor to enter in the floating or Embedded Visitor UI, or in a mobile app using the Unblu mobile SDK. The visitor joins the conversation once they’ve entered the PIN.

The configuration property com.unblu.conversation.invitation.allowInviteVisitorPin specifies who can create PIN invitations.
Generate a private link that they can share with the visitor. The visitor joins the conversation once they click the link. The link only works once.

The configuration property com.unblu.conversation.invitation.allowInviteVisitorPrivateLink specifies who can invite visitors with a private link.
Send the visitor an email containing a private link to the conversation. The link works the same way as for private link invitations.

The configuration property com.unblu.conversation.invitation.allowInviteVisitorEmail specifies who can send visitors an email invitation.
Send visitors the public link to the conversation. Public links are discussed in more detail below.

The Unblu web API has endpoints to invite visitors to conversations. For more information, refer to the Unblu web API reference.

Redeeming a personal invitation

The process for redeeming an invitation to a conversation depends on the type of invitation and whether the invitee is an agent or a visitor.

This section discusses redeeming personal invitations. Redeeming public links is discussed in the section Public links below.

Redeeming an invitation for an agent or team

Personal invitations for agents appear in their queue. Invitations addressed to a team appear in the queue of the team’s members.

Agent Desk queue with a pending invitation

To redeem an invitation, agents click the Answer button on the conversation.

By default, agents invited personally to join a conversation may decline the invitation. You can disable this by setting com.unblu.queue.ui.enableDeclineAgentInvitationsAndForwardings to false.

Invitations sent to a team can’t be declined.

Redeeming a personal invitation for a visitor

How visitors redeem a personal invitation depends on whether the invitation was a PIN invitation or a private link.

Redeeming a PIN invitation

To redeem a PIN invitation, visitors must access a page of your website that’s instrumented with Unblu. There, they open the embedded or Floating Visitor UI and click Enter PIN. The visitor UI then displays a screen where they can enter the PIN they’ve been provided:

*Enter PIN* page in the Floating Visitor UI

To enable the Enter PIN option in the visitor UI, set com.unblu.visitor.ui.engagement.showPinEngagementOption to true.

PIN invitations can only be redeemed once.

Redeeming a private link invitation

Visitors redeem private link and email invitations by clicking the private link. Once they do so, the Visitor Desk opens and displays the conversation.

Private link invitations, including private links sent as email invitations, can only be redeemed once.

If the conversation has already ended when the invitee tries to join, they’re redirected to the Conversation ended page:

Public links

Invitations, whether PIN, private link, or email invitations, are only redeemable once. If something goes wrong while someone is trying to join a conversation, the agent has to create a new invitation for them. Furthermore, if agents want to invite several people to a meeting, they must create a separate invitation for each participant, which can be time-consuming.

Public links address both of these issues. They’re redeemable multiple times, so users can make multiple attempts to access the conversation with the same link. The same public link can be used by multiple invitees, and invitees can be agents or visitors. This lets agents invite multiple participants to a conversation with a single email addressed to them all, for example.

Redeeming a public link invitation

Public links first direct the person who opened them to the Visitor Desk. Agents using a public link invitation must therefore be able to access the PUBLIC entry path.

If the person isn’t an authenticated agent, the Visitor Desk opens on the standard Join conversation page:

Visitors click on the Join button to join, as if they had received a private link. If the Agent Desk is accessible, the page has an additional Join as an agent button beneath the Join button, which redirects agents to the Agent Desk and displays the Agent Desk login screen.

If you prefer, you can configure Unblu to execute the redirect automatically.
If Unblu determines that the person who clicked the public link is an agent, they’re redirected to the Agent Desk and displayed the modal dialog below.

If necessary, the invitee is asked to log in to the Agent Desk first.

Before an invitee can join a conversation using a public link, their request must be approved by an agent.

If no agent has the conversation open in the Agent Desk when the invitee asks to be admitted, Unblu asks the invitee to wait for an agent to join:
If an agent is present in the conversation, Unblu asks the invitee to wait for an agent to admit them to the conversation:

Any agent who’s already joined the conversation can grant or deny access on a person-by-person basis.
Once an agent admits the invitee to the conversation, Unblu treats them no differently than if they’d used a personal invitation.

If an agent denies a visitor or agent access to a conversation, the Join conversation page shows the invitee who requested admission the Admission denied message:
If the conversation has already ended when the invitee tries to join, they’re redirected to the Conversation ended page:

Configuring public links

To let agents create public links for conversations, set the configuration property com.unblu.conversation.invitation.allowPublicLinkAccess in the CONVERSATION_TEMPLATE scope to true. For scheduled conversations, this is the case by default. For other agent-initiated engagement types, it’s set to false.

If you enable public links on an engagement type, Unblu adds a section to the bottom of the Invite menu:

Configuring public links for visitors

Since anyone can use a public link to join a conversation, Unblu lets agents perform a basic check of who’s requesting admission via a public link. This option is controlled by the configuration property com.unblu.conversation.invitation.requireAgentApprovalBeforeJoin. When it’s set to true, Unblu displays a modal dialog like the one below in the Agent Desk. The dialog appears for all agents who have the conversation open.

Any agent who’s already joined the conversation can grant or deny access to the conversation on a person-by-person basis. If you don’t want your agents to vet participation requests via public links, set the configuration property to false.
Access via public links is anonymous. You can require anonymous visitors to provide their name or email address (or both) when they request admission to a conversation via a public link:
- Setting com.unblu.visitordesk.admission.request.requireUsernameWhenAnonymous to true (the default value) forces anonymous visitors enter their name.
- Setting com.unblu.visitordesk.admission.request.requireEmailWhenAnonymous to true requires anonymous visitors to enter their email address before proceeding with the admission process. The default value is false.
Unblu doesn’t verify the information visitors provide in this step.

Configuring public links for agents

Several configuration properties affect public links for agents:

Unblu checks for the presence of a cookie to determine whether the invitee’s an agent. You can specify the name and expiration with the configuration properties com.unblu.identifier.agentCookieName and com.unblu.identifier.agentCookieMaxAge, respectively.
By default, agent detection involves the invitee’s browser attempting to connect to the Agent Desk URL and checking if there’s an agent cookie set. If the Agent Desk is only accessible on a URL that’s only accessible within your organization, this approach exposes that internal URL to visitors.

To avoid this, set com.unblu.visitor.agentcheck.agentPublicLinkDetectionMode to CUSTOM and provide a custom URL for Unblu to call in the configuration property com.unblu.visitor.agentcheck.agentPublicLinkCustomURL. The custom URL must provide access to a service that checks whether the invitee is an agent and returns an HTTP response.
- If the service returns the HTTP status code 200, Unblu assumes the current user is an agent.
- If it returns an HTTP status code other than 200, such as 403, Unblu treats the invitee as a visitor.
If you don’t want agents attempting to join a conversation to be vetted before they join, set com.unblu.conversation.invitation.requireAgentApprovalBeforeJoinAsAgent to false.
You can customize the appearance of the page with the configuration properties in the Agent admission UI group.
To define what’s displayed on the agent Request admission view, edit the configuration properties in the group Agent "request admission" component configuration.
The Join conversation page is also customizable. For more information, see below.

CORS policy for agent redirects

In a cross-origin setup, your CORS policy must be set up in such a way that the agent cookie can be checked. The Access-Control-Allow-Origin header must therefore allow the visitor domain access to the agent domain.

Configuring invitation pages

The Unblu UI has three pages related to invitations:

The Join conversation page.
The Waiting room page.
The Conversation ended page.

Join conversation page

The Join conversation page, pictured above, appears when an unauthenticated agent or a visitor opens a public link invitation.

There are a number of configuration and text properties to customize the Join conversation page:

To remove the information about the assigned agent, the scheduled start date and time, or the topic of the conversation from the Join conversation page, set the appropriate configuration property to false:
- com.unblu.visitordesk.admission.request.showAssignee for the assigned agent
- com.unblu.visitordesk.admission.request.showDate for the scheduled start date and time
- com.unblu.visitordesk.admission.request.showTopic for the conversation topic
The configuration properties for styling the page are in the group Visitor admission request component.
You can add custom text to the Join conversation page with the text property com.unblu.visitordesk.admission.request.customInformation. Use Markdown to format the text.
If you’re using STANDARD agent detection, define when to display the Join as an agent option to unauthenticated invitees with the configuration property com.unblu.visitor.agentcheck.joinAsAgentButtonDisplayMode. The possible values are:
- ALWAYS: Always display the option.
- NEVER: Never display the option.
- WHEN_AGENT_URL_REACHABLE: Only display the option if the URL of the Agent Desk is reachable.
  
  The URL is reachable if it responds to a call with a status code of some kind, including an error. It isn’t reachable if, for example, DNS resolution fails or the CORS request is blocked.
- WHEN_AGENT_COOKIE_SET: Only display the option if a cookie with the name defined in com.unblu.identifier.agentCookieName is set.
To change the label of the button, adapt the text property com.unblu.visitordesk.admission.request.joinAsAgentBtn.
Instead of displaying the Join as an agent button, you can opt to redirect users to the Agent Desk automatically. If you’re using STANDARD agent detection, the configuration property com.unblu.visitor.agentcheck.agentPublicLinkRedirectMode lets you specify when this should occur. The possible values are:
- NEVER: Never perform an automatic redirect. In this case, the Join conversation page is also displayed to authenticated agents.
- WHEN_AGENT_URL_REACHABLE: Only perform a redirect if the URL of the Agent Desk is reachable.
- WHEN_AGENT_COOKIE_SET: Only perform a redirect if a cookie with the name defined in com.unblu.identifier.agentCookieName is set.
  
  If you’re using CUSTOM agent detection, use the configuration property com.unblu.visitor.agentcheck.agentPublicLinkCustomBehavior instead. The possible values are:
- WHEN_AGENT_CUSTOM_URL_SUCCESSFUL_REDIRECT: Perform a redirect if the custom agent URL endpoint returns the HTTP status code 200.
- WHEN_AGENT_CUSTOM_URL_SUCCESSFUL_SHOW_BUTTON: Show the Join an agent button. In this case, the Join conversation page is also displayed to authenticated agents.
Use the configuration property com.unblu.visitor.agentcheck.agentPublicLinkRedirectTarget to specify the target of the automatic redirect.

Waiting room page

The Waiting room is only used for scheduled conversations. For information on configuring the page, refer to Configuring scheduled conversations.

Conversation ended page

If a conversation ends before an invitee attempts to join, they’re redirected to the Conversation ended page:

You can specify which information about the conversation you want to show to agents and visitors on this page with the configuration properties in the groups Agent "conversation ended" component group and ConversationEndedComponent, respectively.