Contact usRequest a demo

Configuring invitations

Agents can invite people to join a conversation in different ways. All invitation types are accessible from the Invite participant control in the Agent Desk. This article describes how to configure the different invitation types.

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.

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:

*Conversation ended* page

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.

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:

    *Join conversation* page in the Visitor Desk

    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.

    Agent Desk login form
    Figure 1. Agent Desk login form

    (In most cases, your agents won’t have the Demo account email field you can see in the screenshot above.)

    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.

    *Join conversation* page for authenticated agents

    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:

    *Join conversation* page after entering details if no agent is present

  • If an agent is present in the conversation, Unblu asks the invitee to wait for an agent to admit them to the conversation:

    *Join conversation* page after entering details if an agent is present

    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:

    *Admission denied* message on the *Join conversation* page

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

*Conversation ended* page

  • 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:

    <strong>Invite</strong> menu with the public link option

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

    Dialog of visitor requesting admission to a scheduled conversation via a public link

    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:

    Unblu doesn’t verify the information visitors provide in this step.

Several configuration properties affect public links for agents:

Preventing exposure of internal URLs

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 an internal URL, this approach exposes that internal URL to visitors.

To prevent 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 20x, Unblu assumes the current user is an agent.

  • If it returns an HTTP status code other than 20x, such as 403, Unblu treats the invitee as a visitor.

Depending on your network and your specific requirements, the checker service may be relatively simple. For example, you might route the client IP to the proxy fronting your Unblu installation, then use that information to distinguish between access attempts from within your organization’s private network and attempts originating on the internet.

If you use NGINX and have access to the client IP—​through $remote_addr, for example—​you can add something like this to your nginx.conf:

# Required for Unblu public link agent determination
geo $remote_addr $geo {
    default        0;

    127.0.0.1      2;
    192.168.0.0/16 1;
    172.16.0.0/12  1;
    10.0.0.0/8     1;

    ::1            2;
    fd00::/8       1;
}

The service to check whether the invitee is an agent can now be reduced to a dummy endpoint in your nginx.conf:

    server {
        listen 8080 default_server;

        # ...

        # For Unblu public link agent determination
        location ~/unblu/check { (1)
            if ($geo != 1) {
                return 404;
            }
            return 204;
        }

        # ...
    }

Be sure to put the checker before other ~/unblu definitions in the nginx.conf.

Finally, set com.unblu.visitor.agentcheck.agentPublicLinkCustomURL to https://<replace-with-your-server>/unblu/check.

Now, when someone accesses the public link, https://<replace-with-your-server>/unblu/check is called. Their IP address is made available in NGINX as $remote_addr. In NGINX, the geo section checks the value of $remote_addr:

  • If the value isn’t one in the range of your organization’s intranet, $geo is set to 0.

  • If the value is in one of the ranges specified, $geo is set to 1.

When NGINX evaluates the location for /unblu/check, the response is determined by the value of $geo:

  • If $geo is 1, NGINX returns a 20x response, granting the user access to the Agent Desk.

  • If $geo is 0, NGINX returns a 40x response, and Unblu loads the Visitor Desk.

This way, the internal URL for the Agent Desk is never exposed.

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:

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:

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

See also