Luware Knowledge

Nimbus Portal Nimbus Admin Nimbus Release Notes Luware Cloud Status
Home Nimbus Administration Configuration (Admin) Instant Messaging

Use Case - Setting Up a WhatsApp Integration in Twilio

Using the Twilio cloud communications platform to connect your WhatsApp business account to Nimbus

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.
 
Use Case - Using Web Requests to Block Callers on a Blacklist

In this use case, we will show you how to automatically reject calls of callers o...

Table of Contents