Luware Knowledge

Nimbus Portal Nimbus Admin Nimbus Release Notes Luware Cloud Status
Home Nimbus Use Cases Administration Use Cases

Use Case - Setting Up Instant Messaging

Learn how to configure and enable instant messaging communication channels.

In this Use Case, we're going to tackle the following topics:

  • Cover technical and licensing preconditions for enabling the Instant Messaging (IM) modality.
  • Explain all Administration and Integration steps to enable the Instant Messaging (IM) modality on your tenant.
  • Recommend follow-up steps after the IM modality has been enabled.

INC Instant Messaging Preconditions

PRECONDITIONS

✅ Instant Messaging (IM) is a user modality (channel of communication) 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.

✅IM Integration paths

INC Instant Messaging Integration Channels

There are currently two integration paths to route Instant Messages to Nimbus users: via Luware Interact or via WhatsApp.

Path Path Description Related Pages
via Interact
  1. The customer reaches out to either services or users directly via contact widgets on a website.
  2. The widgets are HTML code containing a service or user-unique code. They  that are embedded by a website admi
  3. The Interact SDK provides the multimodal chat functionality behind the website widget. The SDK can also be used to implement customer-specific UIs or functionality.
  4. The Nimbus Interact configuration determines individual service and user settings, allowed modalities.
  5. Depending on the path, incoming customer chats are now distributed by the service or directly routed through to users. The interaction is handled directly in MS Teams.

✅Getting started:

🔎Additional sources:
Instant Messaging Integration path, showcasing how the customer interacts with Nimbus services and users
via WhatsApp
  1. The customer reaches out via their WhatsApp client. The Service is represented via WhatsApp Business account.
  2. The Twilio Integration validates authenticity of the WhatsApp Business account and phone number, then provides a messaging Service API to use by Nimbus. 
  3. The Nimbus Provider Connector authenticates with the Twilio Service API.
  4. Service Owners embed the configuration in their service settings, distributing incoming chats via workflows. The chat interaction is handled in the Nimbus UI.

✅Getting started:

🔎Additional sources:

✅User access

  • Tenant Admin rights are needed to handle Tenant and service settings and apply related licenses.
  • Additional roles and permissions may be involved as per integration scenario → See specific use cases below.

✅Nimbus service and user licensing

Instant Messaging can be enabled and licensed per user or service. Note that 

For Applicable Licenses When to apply Configuration areas
Service Contact Center
license
  • When you want to allow Instant Messaging workflows for your services.
  • Also applies when you want to use WhatsApp as your service touchpoint.

Interact Service

(optional)
  • When you want to use your website as service touchpoint.
  • Optional addon to a Contact Center service.
User Instant Messaging modality license
  • When you want to distribute Instant Messaging tasks via service workflows.
  • Also applies when you want to use WhatsApp as your touchpoint.
  • General User Settings (License)
  • Users need to be part of the service with the Instant Messaging modality enabled.

Interact User

(optional)
  • When you want to use your website as user touchpoint.
  • Optional addon, works outside of Contact Center and Instant Messaging workflows.

💡Show some licensing examples

  • Your Service A shall be reachable via WhatsApp - you need:
    • The Contact Center service license → Enables the "WhatsApp" channel and according workflow options in the Modalities Service Settings in order to distribute the Instant Messaging tasks.
    • At least one user as member of this service, with the Instant Messaging modality enabled to receive the tasks.
  • Your Service B shall be reachable via Website - you need: 
    • The Contact Center license on the service → Enables the “Interact” channel and according workflow options in the Modalities Service Settings in order to distribute the Instant Messaging tasks.
    • The Interact service addon → Enables the “Interact” tab for configuration of the integration and restrictions.
    • At least one user as member of this service, with the Instant Messaging modality enabled to receive the tasks.
      💡As long as the user should not be directly reachable, no extra user Interact license is required. → see next point.
  • Your User Y shall be directly reachable via Website (and is not necessarily part of Service B)
    • The Interact User license → Enables the “Interact” tab for configuration of integration and restrictions.
    • Use this method if you want the user to be directly exposed on a website instead of going via service workflows.
 
 
 

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.
 
 

Integration Use Cases

The following scenarios and steps are directly taken from our Use Cases. Depending on your chosen integration scenario, follow the steps inside.

Interact Setup

Setting up Interact

🔎Source: Use Case - Setting Up Interact.

Use Case - Setting Up Interact

On this page, we're going through an example setup for your own Interact web presence, covering the following steps:

PRECONDITIONS

✅Before you start

  • This Use Case is a follow-up to Use Case - Setting Up Instant Messaging. Refer to it for general and licensing preconditions on your tenant.
  • For this Use Case to work, the Instant Messaging modality must be enabled on your tenant. If this hasn't been done already, please get in contact with your Luware Customer Success specialist to discuss terms and License Management details.

✅User Permissions

  • Tenant Admin rights are required to create and update tenant, user, and service settings.
  • Delegated Tenant Admin permissions are required to grant Nimbus App Permissions once via grant link. 
    🔎This link can be found under Modalities Tenant > Modalities Tab > Instant Messaging > “Grant Permissions”.

✅Additional users

  • You need a dedicated O365-user (teams license assigned) on behalf of which Teams meetings will be created. This user needs to have a proper Access Policy assigned.
  • You also require Web developer privileges on your homepage to embed Interact widget codes wherever you want to allow customers to interact with your Nimbus services or users.

✅ Data access

  • By default all Instant Messaging data is routed through Nimbus ACS (Azure Communication Service) instance
  • OPTIONALLY you can bring your own dedicated ACS instance. → The setup steps for this are explained below.
 

🔎GOOD TO KNOW: Before you start

Supported Modalities

Audio/Video Instant Messaging Luware Interact can be licensed and configured to handle multiple incoming modalities: 

Modality
Nimbus Distribution
 Customer touchpoint scenario

Either handed directly by a user

OR 
distributed according to the service's Audio/Video Workflow.

 Customers use an Interact widget on your website where they can configure their headset, webcam, and screen sharing options.
Either handed directly by a user
OR 
distributed according to the service's Instant Messaging Workflow.		 Customers use an Interact widget on your website where they can provide a name, an email address, and an initial message, and start chatting.

Individual User / Service configuration

💡You can configure either modality independently per service and user. If not marked further, steps are generally applicable regardless of modality.

🔎Depending on your scenario, refer to Nimbus Features (respectively for users / services) and do not hesitate to contact your Customer Success partner to define the best approach to your setup and License Management.

☝Note: Unless stated otherwise, all setup steps below cover both service / user touchpoint scenarios. Any specific instructions are divided into “for users / services” tabs respectively.

 

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.
 
 

Enable Interact on your Tenant

  1. Navigate to Nimbus Admin > Tenant Administration.
  2. In the Extensions tab, go to section Interact.
  3. Enable Interact for your Tenant.
  4. Specify the following Interact settings:
    1. ACS Connection string (from the ACS instance which was created)
    2. O365 User ID (newly created Azure EntraID User with a proper Teams License) → ✅ See Preconditions.
    3. Widget Key (autogenerated)
    4. Session Recovery Timeout in Seconds
    5. Authorization. → 🔍Follow Use Case - Enabling Additional Authorization for Interact when you want to implement token-based authentication.
  5. Save the changes.

Optional: Bring your own ACS instance

💡Note: 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. In the Modalities tab, go to section Interact.
  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.
     
     

Provisioning via Microsoft PowerShell - After the tenant configuration is completed, your need to run the Nimbus provisioning script in order to get the changes applied.

 

Instant Messaging user account setup

💡Note: Nimbus / Interact uses guest accounts to track the status of your other Nimbus user's availability in MS Teams. Luware will provide these 

 
  1. Go to Modalities Tenant Settings.
  2. In the Modalities tab, go to section Interact. Ensure Interact is enabled.
  3. Depending on the option “Use your own accounts” follow the steps below:

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

 

 

Configuring a Domain Template

Domain templates define where Interact widgets are allowed to be used on the web, so that no external websites can "redirect" traffic to your services. Templates can be applied to either users or services independently. To define templates, perform the following steps:

  1. Navigate to Nimbus Admin > Configuration > Interact Domain Templates (CORS).
  2. Click Create new.
  3. Enter a name and select the relevant Organization Unit.
  4. Specify Domain name(s) on which you want to allow Interact usage (whitelist).
  5. Click Create.

Restricting Access (CORS)

The previously created domain template needs to be applied to either users or services.

☝Please Note: CORS templates with the same or a higher Organization Units level as your user/service may be available for selection. Ensure you do not select the wrong template (e.g. provided by a higher OU level administrators) or your embedded widgets may not work.

For users

  1. Navigate to Nimbus Admin > users and select the user.
  2. Enable Interact license for the user and click Save. 
    ⮑ The Interact tab appears.
  3. Go to the Interact tab and activate Interact.
  4. In section Restriction, enable Restrict Access. 
     💡You can skip this and the next step if you don't want to apply domain templates to the user.
  5. Select the previously created CORS-Domain-Template in the Domain Template dropdown list.
  6. Click Save.
 
 

For services

✅Your Service has either an Enterprise or a Contact Center license applied.

  1. Navigate to Nimbus Admin > Services.
  2. Select the service you want to enable Interact for.
  3. In General Service Settings, assign an Interact license for the service.
  4. Click Save & Apply. 
    ⮑ The Interact tab appears.
  5. Go to the Interact tab and activate Interact.
  6. In section Restriction, enable Restrict Access. 
     💡You can skip this and the next step if you don't want to apply domain templates to the service.
  7. Select the previously created CORS-Domain-Template in the Domain Template dropdown list.
  8. Click Save & Apply.
 
 

Creating Service and Direct System Messages

💡This step is optional and only necessary if you want to add Service System Messages to your service or Direct System Messages for users.

System Messages are message templates for messages displayed to the customer and user before, during, and after the session, e.g. a welcome message for the customer, or an informative message for the user on the Adaptive Card.

For users

  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:

 
 
 
 

For services

  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:

 
 
 
 

Interact to Service/user Settings

☝This step is required if you want to distribute instant messages to either users and/or services. You can freely combine both options.

 

For users

Configure your user for IM

  1. Go to Admin > Users
  2. Select the user.
  3. In the “General” Tab, ensure “Interact” is enabled. 
    ⮑ This will show the “Interact” tab for the user.
  4. In the Interact Tab:
    1. Ensure that “Interact” is enabled.
    2. Set “Instant Messaging" is enabled.
    3. OPTIONAL, In the “Direct System Messages” dropdown, select a direct system message created previously in the chapter above. 
      💡⮑ This message configuration is shown to all users and customers during to a chat session when engaging directly with each other.
    4. OPTIONAL: Apply CORS Templates 

Teams App Setup Policy

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

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

  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 App Setup Policy to your IM users

✅Teams Administrator: 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 your users for direct Instant Messaging

 Service Owner / Admin - Please Note

✅When using Interact widgets for a direct-to-user communication, note that … 

  • … 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, as MS Teams will otherwise block the communication. For these reasons …
  • … you need Instruct users to register with the IM chat bot1. This is done via Nimbus Portal > User Preferences or a consent link. Detail instructions are below.

1💡Good to know: Chat interactions received and distributed via service (e.g. shown in My Sessions, Attendant Console, or Assistant UI) do not require the IM Signaling Bot registration, as Nimbus handles the distribution with admin-delegated permissions.

 
  1. As an administrator: 
    1. 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.
  2. As the (future) Nimbus user:
    1. Either open the link sent by the administrator or head to User Preferences (Portal) and register with the bot yourself as described below:
    2. Click the link next to the “Not Registered” warning icon.
      ⮑ This will open MS Teams with the Bot as target and a predefined message. 
    3. 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 let the Admin know you are ready to receive Instant Message tasks.
       
 
 

For services

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.

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 (Modalities 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. OPTIONAL: In the “Service System Messages” dropdown, select a service system message created previously in the chapter above. 
    💡⮑ This message configuration is shown to all users / customers during to a chat session when engaging with the service.
  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 service-distributed Instant Messaging

💡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.
    💡The IM modality is enabled on the user's General Settings tab.
     
 
 

Testing your Integration snippets

✅Tenant Admin / Website Admin: 

The final step for setting up Interact is to copy and test snippets for your services and users to your customer-facing homepage. The procedure for both services and users If you do not have the expertise, ask your web administrator to embed the widget snippets for you.

 
  1. In the Interact tab (either in Interact User Settings for users or Interact User Settings for services), go section Integration 
  2. Click Preview.
    ⮑ A mockup website with the Interact functionality opens. This is how it will look like for the customer.
  3. If you are satisfied with the preview, copy the HTML code snippet and insert it into your website. 
    💡Keep in mind: 
    1. Users and services have individual IDs and widget keys. Make sure not to mix these details when pasting them on your website.
    2. When you applied Interact Domain Templates (CORS) earlier in this Use Case, remember that the restrictions can be applied to both users or services.
  4. ⮑ All users (behind a service or standalone) should now be able to chat with outside customers. Test the chat interaction via your website. 
    🔍 Refer to Call Handling and Instant Message Handling to see how the interaction looks like on the Nimbus Portal UI.

Troubleshooting

🤔 Preview or embed code not working? Check if:

✅Prerequisites check: 

✅Configuration check:

  • Interact is enabled on Tenant Level within the Tenant Administration.
  • Interact is enabled for the service or user respectively.
  • All relevant configuration items and service / user settings have been saved at least once so they are effective,.

✅Access and permission check:

 

Known Limitations

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
 
 
 

WhatsApp Setup

Setting up WhatsApp

🔎Source: Use Case - Setting Up a WhatsApp Integration in Twilio.

Use Case - Setting Up a WhatsApp Integration in Twilio

INC Preview Feature

This feature is in PREVIEW and may not yet be available to all customers. Functionality, scope and design may change considerably.

In this Use Case, we're going to verify your WhatsApp business account with Facebook and integrate everything into Twilio. The goal is to establish a Twilio messaging service with an API endpoint which Nimbus can integrate into.

PRECONDITIONS

✅Before you start

  • This Use Case is a follow-up to Use Case - Setting Up Instant Messaging. Refer to it for general and licensing preconditions on your tenant.
  • For this Use Case to work, the Instant Messaging modality must be enabled on your tenant. If this hasn't been done already, please get in contact with your Luware Customer Success specialist to discuss terms and License Management details.

✅User Permissions

  • You require Tenant Administrator permissions to make all adjustments in Nimbus. 
  • You also require rights to do the necessary administration in your Twilio instance. 

✅Infrastructure Requirements

For the Instant Messaging integration of WhatsApp into Nimbus you require: 

  • A verified Meta Business account for verification with WhatsApp and Twilio. 🧠 You require the “Facebook Business Manager ID” 
  • A WhatsApp Business account for connecting with the Twilio API. 
  • An exclusive phone number which needs to be associated with the WhatsApp account. 
    • This number must be able to receive SMS/Voice and must not be used for any other purpose other than one (singular) WhatsApp account.
    • Landline or mobile numbers are allowed, but VOIP numbers may be restricted.
    • You’ll will need temporary access to the number to receive a verification call or SMS, e.g. on a mobile phone.
 

INC Icon Legend Accordion

Show Icon Legend 💡 = A hint to signal learnings, improvements or useful informati...

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.
 
 

 ✅ Your WhatsApp Business phone number in Twilio must be linked with your Facebook Business account.

  1. In the Twilio Console https://console.twilio.com/ go to Conversations Messaging > Senders > WhatsApp Senders.
  2. Click Create new sender.
  3. Select a new or a existing phone number:
    1. Twilio Phone Number.
    2. My Own Phone number (☝must fulfill → Prerequisites listed on top of this page).
  4. Link with Meta/WhatsApp Business account
    1. Log in with Facebook and link the accounts. Use your🧠 Facebook Business Manager ID (learn how).
    2. Select the phone number you want to register (must be able to receive voice/SMS for verification).
    3. Trigger the verification.
  5. Verify ownership of the number:
    1. Choose between SMS or voice call for receiving a verification code.
    2. Enter the code in the Twilio console to prove ownership.
Linking your WhatsApp Business Account with Twilio

WhatsApp Business Profile Setup

✅The business profile will be visible to your customers in WhatsApp.

  1. Set up your business profile:
    1. Business display name 
    2. Business description
    3. Logo/image
    4. Website and contact info
  2. Submit your choice.
    ⮑ Twilio will submit your request to WhatsApp/Facebook for manual review.
    ☝From our experience, the business approval process can take a few hours or days, depending on your region.
Business Profile Setup

Create New Conversation Service

  1. Go to https://console.twilio.com/.
  2. Go to Conversations > Manage Service > Create new Service.
  3. Within “Base Configuration”:
    1. Add a friendly name (only needed for later identification).
    2. 🧠 Retrieve the Service SID for later in Nimbus.
  4. Within “Webhooks”:
    1. Fill in the Post-Event URL as follows: 
      https://portal.<ClusterIdentifier>.luware.cloud/api/acs/chat-handler/tenants/<YourTenantID>/twilio-callbacks
       💡You can find out your ClusterIdentifier by logging into Nimbus User Portal and observing your browser URL.
       💡The Tenant ID you can see after logging into Nimbus Admin Portal and heading to the General Tenant Settings.
    2. Further down on Webhooks:
      1. Leave Post-webhooks all checked.
      2. Leave Pre-webhooks unchecked.

Twilio API Key 

  1. Go to Account Management > Keys & Credentials.
  2. Create a new API key: 
    1. (any friendly name)
    2. Region: United States - Default
    3. Key Type : Standard
  3. 🧠 Retrieve the API Key SID & Secret for later in Nimbus.

Test Your Setup

✅ Once approved, the phone number will appear as a “Verified” WhatsApp sender in Twilio Console.

  • You can now send and receive WhatsApp messages using Twilio’s API.
  • All production messaging must use **pre-approved templates** for outbound communication outside the 24-hour customer window.

Integrate with Nimbus

✅ Now you establish a connection with the Twilio Messaging Service and a Nimbus Service.

Nimbus Provider Connector

  1. Head to Nimbus Administration > Configuration > Provider Connectors.
  2. Create a New Connector. Place it in a Organization Unit that ensures no crossover-usage between services.
  3. Enter the API Key SID from Twilio. 
  4. Enter the API Key Secret from Twilio.
  5. Select the Region from Twilio
    💡Should be the same as set in Twilio - the regional selection is limited by what Twilio offers. For the time being this should be set to “United States”.
  6. Save the Connector.

Nimbus Messaging Entry

✅This step is necessary for the service initially receiving messages. You can skip it on other Nimbus Services which are not supposed to be contacted directly, but can accept transfers from your source IM service.

  1. Head to Nimbus Administration > Configuration > Messaging Entries.
  2. Create a New Messaging Entry. Place it in a Organization Unit that ensures no crossover-usage between services.
  3. Select the previously created Provider Connector.
  4. Enter the Service SID from Twilio. 
  5. Save the Messaging Entry.

Nimbus Tenant Settings

✅ You need to have Tenant Administrator rights to make changes in the Tenant Settings.

  1. Go to Modalities Tenant Settings.
  2. In the Instant Messaging section, enable Twilio and WhatsApp.
  3. Save your settings.

Nimbus Service Settings

  1. Within your Nimbus service, go to the Modalities Service Settings.
  2. Ensure that Instant Messaging is enabled as modality.
  3. Further down in section Instant Messaging, enable WhatsApp.
  4. Select a valid Instant Messaging workflow.
  5. Select your previously created Messaging Entry .
    💡Note: The Messaging Entry is a unique value per service, meaning that once assigned it won't be available for selection for other services.
  6. Save your settings.

Test Your Chat Integration

  1. Via WhatsApp, send a chat message to your service.
  2. Within Nimbus Portal, check in the service queue if the incoming chat is being distributed as a task.

Known Limitations

INC Instant Messaging Limitations

BY DESIGN

💡Customer data visibility: During an ongoing Instant Messaging session, any messages that customer enters into the chat will be visible to the Nimbus user, including information entered during Workflow Activities such as “Collect Information”.

 

KNOWN INSTANT MESSAGING LIMITATIONS

💡The following limitations are currently known to the Nimbus development team. We are actively working on improvements.

General limitations

  • Supervision is currently not supported for Instant Messaging sessions.
  • Instant Messaging modality support for Workflow Activities is currently limited. Workflows with incompatible activities cannot be selected in the service settings.

    Show list of supported WF activities

    INC Instant Messaging supported WF activities

    Currently the following Workflow activities are supported for Instant Messaging workflows:

    ▼Workflow Activity | Chat Integration path via ►

    Interact1

    WhatsApp1

    Conversation Handling

    Accept

    ✅

    ✅

    Announcement

    ❌

    ❌

    Collect Information

    ✅

    ✅

    Delay

    ✅

    ✅

    Disconnect

    ✅

    ✅

    Disconnect as Handled

    ❌

    ❌

    Forward

    ❌

    ❌

    Input Customer

    ✅

    ✅

    Input Customer (Advanced)

    ❌

    ❌

    Mark as Handled

    ❌

    ❌

    Message

    ✅

    ✅

    Play Music

    ❌

    ❌

    Reply

    ❌

    ❌

    Save to Parameter

    ✅

    ✅

    Standby Duty

    ❌

    ❌

    Transfer 

    ✅ (to service only)

    ✅ (to service only)

    Virtual User

    ❌

    ❌

    Voice Message

    ❌

    ❌

    Web Request

    ✅

    ❌

    Check

    Availability-based Routing

    ✅

    ✅

    Check Opening Hours

    ✅

    ✅

    Check Parameter

    ✅

    ✅

    Get Available Users

    ✅

    ✅

    Get Queue Position

    ✅

    ✅

    Wait for Parameter

    ❌

    ❌

    Queue

    Cancel Task

    ✅

    ✅

    Check Task

    ✅

    ✅

    Distribution Priority

    ✅

    ✅

    Queue

    ❌

    ❌

    Queue Task

    ✅

    ✅

    1 If a workflow is edited in post using unsupported activities, the Nimbus Reporting session will terminate with a “failed” outcome.

     
     
  • Reporting: IM Sessions are currently not differentiated by the Integration method used (either WhatsApp or Interact). 
    → A workaround is to use dedicated IM services for either integration method.

Interact specific limitations

  • Directly contacting a user via Interact will block a user depending on the incoming modality. The user stays “available” during an Instant Messaging session because a chat is non-blocking, but Audio/Video will result in the user being “not available” because they are in a blocking call.
  • Nimbus Reporting Model - There isn't a service nor user session reported when a user is directly contacted.

WhatsApp specific limitations

  • Provider Connectors > Twilio - Currently the integration works with “United States” region only.
  • Chat functionality is currently limited to the essential only. 
    • HTML text formatting, inline images and attachments are not supported yet.
    • Message editing & deletion, reactions and replies are not supported and will not be supported (Twilio API limitation)
  • Unsupported workflow activities: If a workflow is edited in post using unsupported Workflow Activities, the Nimbus Reporting session will terminate with a “failed” reporting outcome.
 
 
 

Prepare your users for Instant Messages

Once the technical integration is done, you can do the following: 

☝Integration channel consideration when using Distribution Policies: In addition to the modality Nimbus also considers the previously used service integration channel (e.g. via WhatsApp or Interact) for preferred- and last user routing Distribution Policies. For example:

  1. Whatsapp session 1 → Multiple users available, user A is selected by policy.
  2. Interact session 2 → Multiple users available, user B is selected by policy.
  3. Whatsapp session 3 → Last user routing policy applies → User A is selected as preferred.
 

Known Limitations

INC Instant Messaging Limitations

BY DESIGN

💡Customer data visibility: During an ongoing Instant Messaging session, any messages that customer enters into the chat will be visible to the Nimbus user, including information entered during Workflow Activities such as “Collect Information”.

 

KNOWN INSTANT MESSAGING LIMITATIONS

💡The following limitations are currently known to the Nimbus development team. We are actively working on improvements.

General limitations

  • Supervision is currently not supported for Instant Messaging sessions.
  • Instant Messaging modality support for Workflow Activities is currently limited. Workflows with incompatible activities cannot be selected in the service settings.

    Show list of supported WF activities

    INC Instant Messaging supported WF activities

    Currently the following Workflow activities are supported for Instant Messaging workflows:

    ▼Workflow Activity | Chat Integration path via ►

    Interact1

    WhatsApp1

    Conversation Handling

    Accept

    ✅

    ✅

    Announcement

    ❌

    ❌

    Collect Information

    ✅

    ✅

    Delay

    ✅

    ✅

    Disconnect

    ✅

    ✅

    Disconnect as Handled

    ❌

    ❌

    Forward

    ❌

    ❌

    Input Customer

    ✅

    ✅

    Input Customer (Advanced)

    ❌

    ❌

    Mark as Handled

    ❌

    ❌

    Message

    ✅

    ✅

    Play Music

    ❌

    ❌

    Reply

    ❌

    ❌

    Save to Parameter

    ✅

    ✅

    Standby Duty

    ❌

    ❌

    Transfer 

    ✅ (to service only)

    ✅ (to service only)

    Virtual User

    ❌

    ❌

    Voice Message

    ❌

    ❌

    Web Request

    ✅

    ❌

    Check

    Availability-based Routing

    ✅

    ✅

    Check Opening Hours

    ✅

    ✅

    Check Parameter

    ✅

    ✅

    Get Available Users

    ✅

    ✅

    Get Queue Position

    ✅

    ✅

    Wait for Parameter

    ❌

    ❌

    Queue

    Cancel Task

    ✅

    ✅

    Check Task

    ✅

    ✅

    Distribution Priority

    ✅

    ✅

    Queue

    ❌

    ❌

    Queue Task

    ✅

    ✅

    1 If a workflow is edited in post using unsupported activities, the Nimbus Reporting session will terminate with a “failed” outcome.

     
     
  • Reporting: IM Sessions are currently not differentiated by the Integration method used (either WhatsApp or Interact). 
    → A workaround is to use dedicated IM services for either integration method.

Interact specific limitations

  • Directly contacting a user via Interact will block a user depending on the incoming modality. The user stays “available” during an Instant Messaging session because a chat is non-blocking, but Audio/Video will result in the user being “not available” because they are in a blocking call.
  • Nimbus Reporting Model - There isn't a service nor user session reported when a user is directly contacted.

WhatsApp specific limitations

  • Provider Connectors > Twilio - Currently the integration works with “United States” region only.
  • Chat functionality is currently limited to the essential only. 
    • HTML text formatting, inline images and attachments are not supported yet.
    • Message editing & deletion, reactions and replies are not supported and will not be supported (Twilio API limitation)
  • Unsupported workflow activities: If a workflow is edited in post using unsupported Workflow Activities, the Nimbus Reporting session will terminate with a “failed” reporting outcome.
 
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

A NOTE TO ADMINISTRATORS TENANT ADMIN: Note that this Knowledge Base page will on...

Table of Contents