Luware Knowledge

Nimbus Portal Nimbus Admin Release Notes Service Status
Home Nimbus Use Cases Administration Use Cases

Use Case - Setting Up Instant Messaging

Learn how to configure and enable chat as a communication channel.

In this use case, we're going to tackle the following topics:

 

INC Instant Messaging Preconditions

PRECONDITIONS

✅ Instant Messaging (IM) is a user modality feature to be enabled for your tenant. This is done during initial setup with your Luware Customer Success representative and in tandem with License Management for your users and services. You can also read Use Case - Setting Up Instant Messaging for a walkthrough.

☝ Please Note: 

  • Tenant Admin rights are needed to handle Tenant and Service settings and apply the licenses accordingly.
  • Delegated Tenant Admin permissions are required once via grant link. This link can be found under Modalities Tenant Settings  > Instant Messaging > “Grant Permissions”. Refer to Nimbus App Permissions for more details on these permissions.

Licensing and Settings

Note that either Users or Services need a license for Interact to handle incoming messages. Refer to Use Case - Setting up Interact to learn more on how to embed Interact on your website.

  • If a Service has an Interact license assigned, users also need an Instant Messaging modality license to handle IM interactions with outside customers. This is all done within Service Administration and User Administration, respectively. → See Service and User Requirements below.
  • If a User has the Interact license, the service requirement can be skipped. → See User requirements below.

Service Requirements

These requirements apply when you want to distribute instant messages via service queue. 

The service Configuration is done in General Service Settings and Interact Service Settings.

 
 

User Requirements

These requirements apply for all users you want to distribute instant messages to. There are two methods for this, either distribution via service queue via service or user directly.

Distribution via Service Direct to User

✅ Service Requirements from above apply.  

 

 

The receiving user(s): 

  • Need to be part of the service so they are considered by its queue OR be defined as preferred user in a service Distribution Policy.
  • Needs an “Instant Messaging” modality license assigned in General User Settings.

Without a service being involved, users receive instant messages via Interact.

 

The receiving user(s):

End-User Permissions

💡Optional - only when using Adaptive Cards: Each receiving user of the Instant Messaging modality needs to register with the IM chat bot once in order to receive Adaptive Cards messages for incoming IM tasks / chat session invitations. This is done via Nimbus Portal > User Preferences.

After registration, the IM Signaling Bot will invite users via Adaptive Cards on incoming chat messages.

Good to know: Chat interactions received via My Sessions, Attendant Console, or Assistant do not require the IM Signaling Bot registration, as the Nimbus UI will handle the distribution.

 
 
 

INC Icon Legend Accordion

Show Icon Legend

💡 = A hint to signal learnings, improvements or useful information in context. 🔍 = Info points out essential notes or related page in context.
☝ = Notifies you about fallacies and tricky parts that help avoid problems. 🤔 = Asks and answers common questions and troubleshooting points.
❌ = Warns you of actions with irreversible / data-destructive consequence. ✅ = Intructs you to perform a certain (prerequired) action to complete a related step.
 
 

Enabling Instant Messaging on Your Tenant

  1. Go to Modalities Tenant Settings.
  2. In the section Instant Messaging, toggle on “Instant messaging enabled” to get further options.
  3. There are two possibilities how Instant messaging can be used. 

Either Case A (Use the Luware accounts) or Case B (Bring your own Instant Messaging account). 

✅ In either case, you need to “Grant Permissions” to the Nimbus App to send Instant Messages.

Case A:  Luware guest accounts on your tenant

 

Case B: Bring your own Instant Messaging account

 
 

This solution uses 2 guest accounts provided by Luware. You will be performing these tasks in tandem with Customer Success.

 
  1. Invite the external guest account users for IM on your tenant.   

    Learn how to invite external accounts to your tenant

    INC Invite Azure Guest Accounts

    1.  As Tenant Admin, log into your Azure Portal.
    2. Go to Users > New Users and select “Invite external User”.
       
    3. Invite both guest users 1&2 on your tenant. Add each of the previously copied email addresses (e.g. svr_nimbus_guest@onmicrosoft.com) and click Invite.
      ⮑ A standard Azure invite mail will be sent out to Luware.

      ☝ Note that MFA (Multi Factor Authentication) needs to be disabled for these users. Otherwise, this feature will not work as the guest users cannot sign in to your tenant.
    4. Let your Customer Success Specialist know that the guest users have been invited.
    5. Please wait while steps are done in the background:
      1. Luware cloud operations team must accept the guest invitations. Please allow for some time for this to happen.
      2. Once successful, the "Account is not added as guest" message should disappear on your side in the Nimbus admin UI.
      3. If this is not the case, please get in contact with the Luware support.
     
     
  2. As Tenant Admin: Inform your Customer Success partner about the pending user user invite.  
    💡 This invitation needs to be accepted by us before usage is possible on your side.
  3. After receiving the confirmation from Customer Success and having permissions granted on your behalf, you can use the Test UPN field to send messages to any user on your tenant (e.g. a future chat message recipient acting as service user).
 

✅ For this solution, you need to have at least one dedicated service account ready, fulfilling the following requirements:

  • A valid Teams license, with no MFA enabled and no password policy.
  • Ideally a second account with the same settings should be used as fallback.
 
  1. Navigate to Nimbus Admin > Tenant Administration.
  2. Go to the Modalities tab.
  3. Locate the "Instant Messaging" section.
  4. Enable the “Use your own account” toggle.
  5. Fill in the UPN and the password.
  6. Save your changes.
  7. When accounts are configured and the permissions granted, you can use the Test UPN field to send messages to any user on your tenant (e.g. a future chat message recipient acting as service user).
Tenant Administration: Use of own accounts for Instant Messaging

 

 

Bring your own ACS instance

💡 Note: This step is optional. Out of box, Nimbus will provide you with an Azure Communication Services endpoint. However, you can make use of your own dedicated ACS (Azure Communication Services) instance from Azure.

 
  1. Navigate to Nimbus Admin > Tenant Administration
  2. Go to the Modalities tab.
  3. Locate the "Instant Messaging" section. 
  4. Enable "Use your own ACS Instance" and provide the ACS connection string and resource ID.  

    Learn how to get this ACS connection string

    INC ACS Instance Setup

    INC ACS Instance Setup

    The following steps describe how an ACS instance can be setup. Which is required for Nimbus Assistant and/or Interact.

    INC Interact Azure Billing

    AZURE BILLING

    The usage of Interact will cause additional monthly ACS (Azure Communication Services) costs depending on modality (IM/AV) used. These cost are determined by Microsoft. Also see: https://learn.microsoft.com/en-us/azure/communication-services/concepts/pricing

    • Before enabling additional modality features for your services, get in touch with your Luware Customer Success specialist to discuss terms, usage scenarios, and necessary setup procedures.
    • Please note that Nimbus and Interact support does not cover pricing discussions or make recommendations based on the Microsoft Azure infrastructure.
     

    Create new Azure Communication Service

    To create a new Azure Communication Service perform the steps:

    1. Head to Azure Portal and login with tenant admin rights.
    2. Search for "Azure Communication Service" component and click "Create".   
       
      ☝ Make sure not to use any underline/underscores within the name.
    3. Switch to the Keys tab and copy the connection string  

     

     

     
     
  5.  Additionally, you need to setup an ACS Event subscription.

    Learn how to set up an ACS Event Subscription

    INC Setting Up an ACS Event Subscription

    1.  Go to your created ACS instance and select Events.
    2.  Create an event subscription with the Event Grid Schema.
    3.  Choose a suitable System Topic Name (no impact).
    4.  Select the following filters:
      1.  Chat Message Received
      2.  Chat Message Edited
      3.  Chat Message Deleted
      4.  Participant Added To Chat Thread
      5.  Participant Removed From Chat Thread
    5.  The endpoint type needs to be Web Hook.
      1.  The URL needs to contain as base URL your Cluster and as suffix /api/acs-driver/v1/events
    6.  Go to the Overview tab, select the JSON View, and copy the immutableResourceId into the Nimbus Admin.
     
     

Configuring Instant Messaging

As stated in the preconditions, there are two ways to distribute Instant messages:

IM via Services

☝This step is only necessary if you want to distribute Instant Messaging tasks through your Services queues. If not required - or you want to circumvent the service queues - you can the follow “IM to Users” instructions instead.

 

Configure Your Instant Messaging Workflow

  1. Navigate to Nimbus Admin > Configuration.
  2. Select Workflows > Workflows.
  3. Click Create New.
  4. As Workflow Type, select Instant Messaging   
  5. Name your workflow and pick an Organization Unit that is equal or higher to your IM-handling service. 
  6. Design your workflow in the editor.💡 Refer to Workflow Activities for a full list.
    1. Start with "Accept Conversation" and a "Message" activity to welcome your customer.
    2. Follow up with a "Queue Task" activity to assign the IM task to the queue of your service.
    3. Once the queue limit is reached, don't forget to use "Cancel Task", and "Disconnect" the user as you would in a call.   
      💡 A friendly "Sorry" message goes a long way for your customers.

Define Service System Messages

💡This step is optional and only necessary if you want to add System Messages specific to your service. These messages are sent to user and customers during certain IM session events (Session accept, end, terminated).

 
  1. Go to Nimbus Admin > Configuration.
  2. Select Instant Messaging > Service System Messages.
  3. Click Create New.
  4. Fill out the tabs as follows:

INC Service System Messages

General

  1. Give your Service System Message a name and select the Organization Unit.
  2. Optionally, add a description.
  3. In the User dropdown, select how you want to display the task handling agent's name that is in the chat with the customer.
  4. In the Service dropdown, select which service name you want to display for the customer.

    In the example below, our service is called Documentation Team:
 
 

Messages to User

In the tab Messages to User, you can define messages that are displayed to the agent when an instant message is coming in, handled, or terminated, using both custom parameters and System Fields and Parameters:

 
 

Messages to Customer

In the tab Messages to Customer, you can define messages that are displayed to the customer when getting connected to an agent or ended by the agent:

 
 

Configure your Service for IM

💡 Now, it's time to apply your new workflow.

  1. Navigate to Nimbus Admin > Service Settings.
  2. Select your service. Ensure that it has a Contact Center license assigned.
  3. Go to the tab Modalities (Modality Service Settings).
  4. Enable Instant Messaging.   
    ⮑ A new section “Instant Messaging” appears. If you don't see it, scroll down to the end of the page.
  5. In the “Instant Messaging Workflow” dropdown, select your newly created Instant Messaging workflow from the previous step. 
  6. In the “Service System Messages” dropdown, select a service system message created previously. This step is optional.  
     
  7. Head over to the tab Interact (Interact Service Settings) and enable Interact by switching on the toggle.
  8. Enable "Instant Messaging" and other modalities you want to allow in the service.
  9. Finally, copy the service snippet (in the section “Integration”) and paste it into your website once you are ready to go live. 
Clicking Preview opens the Interact integration preview for your service.

Prepare Your Users for IM

Finally, you need to ensure that users are part of the service and can handle incoming instant message tasks.

  1. Go to Admin > User Administration.
  2. In General User Settings, enable Instant Messaging for each user you want to allow to handle IM tasks.   
  3. Navigate to Nimbus Admin > Service Settings.
  4. Select your service and go to the tab Users.
  5. Ensure that at least one user with an assigned “Instant Messaging” modality license is added to the service in order to receive the IM tasks.   
     
Ensure that the IM-receiving user is a member / agent of your service
 
 

IM to Users

☝This step is only necessary if you want to directly handle Instant Messages through your Users instead of a service queue. If this is not the case, you can follow “IM via Services” instead.

 

Configure your User for IM

  1. Go to Admin > Users.
  2. Select the user.
  3. In Interact User Settings, enable “Instant Messaging”.
  4. Optionally, select the previously created Direct System Message in the appropriate field.  
    💡Also explained in the next step.

Define Direct System Messages

💡This step is optional and only necessary if you want to add System Messages specific to your users. These messages are sent to user and customers during certain IM session events (Session accept, end, terminated).

 
  1. Go to Nimbus Admin > Configuration.
  2. Select Instant Messaging > Direct System Messages.
  3. Click Create New.
  4. Fill out the tabs as follows:

INC Direct System Messages

General

  1. Give your Direct System Message a name and select the Organization Unit.
  2. Optionally, add a description.
  3. In the User dropdown, select how you want to display the user's name for customer. You can can either display the user's current display name or define a custom name.
 
 

Messages to User

In the tab Messages to User, you can define messages that are displayed to the user when an instant message is coming in, handled, or terminated, using Direct Conversation Parameters:

 
 

Messages to Customer

In the tab Messages to Customer, you can define messages that are displayed to the customer when getting connected to the user or ended by the user:

 
 

Teams App Setup Policy

🤔 Why is this necessary? As no service can distribute the IM task in this scenario, Nimbus instead uses a chatbot to post Adaptive Cards directly to users, effectively allowing them to accept/decline/terminate incoming Instant Messaging sessions. However, this chatbot requires consent on each user's behalf.

 

✅ Teams Administrator: Within Microsoft Teams Admin Center, you need to enable Upload custom apps for Nimbus. Otherwise, sending messages via the Nimbus bot might not work. You can create a separate Nimbus App Setup Policy for this or configure your global policy accordingly. 

For this example, we created a separate App Setup Policy for Nimbus.

 
  1. In Microsoft Teams admin center, go to Teams apps > Setup policies and select the Nimbus App Setup Policy.
  2. Enable Upload custom apps.
  3. Optionally, enable User pinning.   
  4. Save the configuration.

Assign the Nimbus Setup Policy to your IM users

Now, the Nimbus App Setup Policy needs to be assigned to all Nimbus IM users.

  1. In Microsoft Teams admin center, go to Users > Manage Users and select the user you want to assign the policy to.
  2. Click Edit.   
      
    ⮑ A popup will appear on the right-and side.
  3. In the Select App setup policy dropdown, select the Nimbus App Setup Policy.   
  4. Click Apply.

Instruct users to prepare for IM

 Service Owner / Admin - Please Note

✅ When using Interact widgets for a direct-to-user communication:

  • Adaptive Cards are now a requirement. Every newly added user (or Contact Center Agent) that handles instant messages must grant this permission to the Nimbus bot once.
  • Instruct your agents to register with the IM chat bot. This is done via their individual Nimbus User Preferences (Portal) or a consent link. Detail instructions are below.

✅When you are not using the direct-to-user method and distribute IM via your service queues, you can instruct your users to use the Nimbus UI (Attendant Console, My Sessions or Assistant) to handle any incoming Instant Messaging task. Details on this are described in Instant Message Handling.

 
  1. Administrator: Within the User Administration > Interact tab, check if the user has registered with the bot. On any new user this will most likely be the case. 
  2. You can send the registration link to the user directly or ask your user to perform the steps below.  
  3. As the receiving user, either open the link sent by the administrator or head to User Preferences (Portal).  
  4. Clicking the link will open Teams with the Bot as target and a predefined message. In order to get registered, you need to send a message to the bot.  
     
    ⮑ After registration, the bot is ready to invite via Adaptive Cards whenever a customer chat request is coming in via Interact.  
    ⮑ You can now engage in Instant Message tasks.  
     

Follow-Up Check:

✅ Interact Setup:  If you haven't used Interact for any other modalities before, it is a good time now to read Use Case - Setting Up Interact. By doing so, you learn how to embed your respective user and service widgets within your web presence.

 

Known Limitations

INC Instant Messaging Limitations

KNOWN INSTANT MESSAGING LIMITATIONS

  • Engaging in Instant Messaging with Nimbus Services currently requires Interact and its SDK.
  • Supervision is currently not supported for Instant Messaging interactions.
 

INC Known Interact Limitations

KNOWN INTERACT LIMITATIONS

  • Interact has certain JavaScript calling limitations in regards to operating systems and browsers. Refer to the official MSFT documentation.
  • Audio/Video Calls initiated from Interact have the following workflow limitations:
Workflow Activity Limitations
Transfer

Can only target services. Not supported targets are:

  • external
  • user
  • parameter
Queue "Pickup" distribution type is not supported.
Voice Message Not supported.
Customer Input Sending DTMF over Interact (Client/SDK) is not supported
 
Use Case - Setting Up Assistant

PRECONDITIONS You require tenant administrator rights to create and update tenant...

User Preferences (Admin)

User preferences allows you to access settings that refer to your user account on...

Administration Overview

BEFORE YOU START Access to the Admin Panel is granted via the following links: Ni...

Operations

FOR ADMINISTRATORS TENANT ADMIN  Note that this Knowledge Base page will only cov...

Table of Contents