Luware Knowledge

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

Use Case - Setting Up a SMS Integration in Twilio

Using the Twilio cloud communications platform to pass through SMS to Nimbus using your business account

In this Use Case, we're going to set up a SMS-capable phone number and related messaging service in Twilio. The goal is to establish a Twilio API endpoint into which your Nimbus service 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 for SMS services into Nimbus you require: 

  • An exclusive phone number which needs to be associated with the service account. This number must be able to receive SMS and must not be used for any other purpose other than one (singular) account.
  • Please note that cost and support of Twilio-related services are not part of your Nimbus subscription.
 

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.
 
 

Configure the Twilio Service

 ✅ In Twilio you need to create a service and link it to a phone number. Both elements are then combined 

Creating a Conversation Service

  1. Go to https://console.twilio.com/.
  2. Go to Conversations > Manage Service > Services > Create new Service.
  3. Within “Base Configuration”:
    1. Add a friendly name, used for later identification within Twilio.
    2. 🧠 Retrieve the Service SID for later in Nimbus.
  4. Within “Webhooks”:
    ☝Ensure the webhook address matches with your cluster
    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 all unchecked.

Creating a SMS enabled Phone number

✅ Now we need to acquire an SMS-capable phone number to be used for your messaging service.

  1. Go to https://console.twilio.com/.
  2. Go to Phone Numbers > Buy a number. 
  3. Ensure that your new number is SMS capable and purchase it as needed. → Also see related note below.
  4. Go to Phone Numbers > Manage > Active Number

3rd party service compliance and regulation

Providing chat services: compliance and regulations

  • Note that providing services via chat (in either integration scenario) underlies country-specific regulations your service needs to follow. This can involve details on the use of shortened-URLs (scam regulations), automated message generation (spam regulations), possibility for customers to opt-out of communications, privacy, data-security and retention. Breaking these regulations may result in your numbers being blacklisted or cancelled by Twilio or the mobile carriers without further notice.
  • WhatsApp and SMS data residency is determined by Twilio, which currently hosts data centers primarily in the US.

Note that Luware does not provide any assistance in being compliant with local laws and regulations.

Related Source: https://www.twilio.com/en-us/changelog/data-residency-for-sms--eu--is-now-in-private-beta 

 
  1. Go to https://console.twilio.com/.
  2. Go to Conversations > Addresses > Configure addresses 
    1. Enable "Autocreate a conversation”
    2. Under “Select a conversation service”, select your previously created service.

Create API Key & Secret

  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” sender in Twilio Console.

  • You can now send and receive SMS messages using Twilio’s API.

Integrate with Nimbus

Nimbus Twilio Integration Steps

In the following we explain how you establish a connection with the Twilio Service API and a Nimbus Service. 

✅ Precondition: 

  • You have already set up a Twilio account, a corresponding conversation service and API.
  • 🧠From Twilio you have Service SID, API Key SID and API Key Secret ready at hand.
 

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.
    1. 🧠Enter the API Key SID from Twilio. 
    2. 🧠Enter the API Key Secret from Twilio.
    3. 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”.
  3. 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 avoids crossover-usage between services.
  3. Select the Provider Connector created from previously above.
  4. Enter the Service SID from Twilio.
  5. Save the Messaging Entry.

💡Consideration for multi-modal services: Even if you intent to handle multiple integration channels by the same service, we recommend to split the Service SID on Twilio's side to have a clear distinction. You can have multiple Messaging Entries in Nimbus and assign them individually via the service settings. This allows you to specifically disable one part of the service without affecting the other.

 

Nimbus Tenant Settings

✅ If not already done before, you now enable the related integration channels.

  1. Go to Modalities Tenant Settings and locate the Instant Messaging section.
    1. Enable Twilio and …
    2. … your related integration channel (e.g. WhatsApp or SMS) as configured in Twilio.
  2. Save your settings.
    ⮑ This action enables the corresponding service settings 

Nimbus Service Settings

✅ Now it's time to apply your configuration in your service.

  1. On your Nimbus service, go to Modalities Service Settings.
  2. Ensure that Instant Messaging modality is enabled for your service.
  3. Within the “Instant Messaging” section, enable your integration channel (WhatsApp / SMS) 
    ⮑ Additional configuration options become available.
    1. Select an Instant Messaging workflow.
    2. Select your Messaging Entry previously created above.
      💡The Messaging Entry is a unique value per service, meaning that once assigned it won't be available for selection for other services.
  4. Save your settings.

Test Your Chat Integration

  1. Depending on your chosen Twilio integration and capabilities, send a chat message to your service's associated phone number.
  2. Within Nimbus Portal, log in as a Service user / owner for your IM-enabled service. 
  3. Inspect the service queue (e.g. in My Sessions) if the incoming chat is shown as new task.
  4. Accept the task and reply in the My Sessions chat window. 🔎 Further details can be found under Instant Message Handling.

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

☝SMS length is impacted by character encoding1. Please keep the length in mind:

  • Please note that when you send a long message, that the customer generally will receive multiple SMS at the same time, which could be considered as spam - on top of generating additional cost for the involved actors.
  • The Nimbus UI will show the amount of SMS generated by a chat response. The amount of remaining characters and SMS will be adjusted when you change the encoding (e.g. by using emoticons).

1Also refer to Twilio's documentation on SMS character limits and instruct your users accordingly before sending out long message chains.

 

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 ►

    Interact

    WhatsApp

    SMS

    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)

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

    ✅

    ✅

    ✅

    💡General Note: 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.

SMS specific limitations

  • Provider Connectors > Twilio - Currently the integration works with “United States” region only.
 
Use Case - Token-Based 2FA to verify a phone number via SMS

Two-factor authentication (2FA) enhances security by requiring users to provide t...

Use Case - Looking Up Phone Numbers via Search.ch API

Local.ch and search.ch are services of the Swisscom Directories (https://www.loca...

Use Case - Creating a ServiceNow Ticket Based on User Input

🔍Related Page:  This use case is a more complex extension to Use Case - Creating ...

Table of Contents