Use Case - Setting Up a SMS/RCS Integration in Twilio

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

In this Use Case, we're going to set up and SMS/RCS-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/RCS 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/RCS 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.
 

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/RCS enabled phone number

✅ Now we need to acquire an SMS/RCS-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/RCS capable and purchase it as needed. → Also see related note below.
  4. Go to Phone Numbers > Manage > Active Numbers.

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/RCS messages using Twilio’s API.

Integrate with Nimbus

Known Limitations

🔎INSTANT MESSAGING DESIGN NOTES

💡The following notes are “by design”. They describe behavior of message protocols which cannot be circumvented or fully mitigated by Nimbus.


☝Data visibility: 

  • Visible Customer Inputs: 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”.
  • Attachments sent by either customer or user are subject to the Instant Messaging integration vendor (e.g. WhatsApp, Twilio) and their respective data handling and retention policies. If you are uncertain about handling certain media types via Instant Messages, consider restricting the Allowed File Types within your Data Privacy Service Settings.

☝Delay consideration for Power Automate (e.g. preferred user scenarios): 

  • Note that – while Instant Messaging tasks can be routed with minimal delay – the measured roundtrip time of e.g. setting a preferred user via Power Automate Flow Action in many cases lies above 1 second. 
    → When you want to leverage “Preferred User Routing” in your Distribution Policies we recommend to add a delay in your workflow (e.g. via “Message” or “Delay” Conversation Handling Activity) before handing the task over to your “Queue”.

☝Maximum message length is 1600 characters.1

  • Twilio enforces a maximum message length of 1600 characters. Additional Parameters in your (automated) messages count towards this limit.
  • In the UI (e.g.  My Sessions, Nimbus will detect the integration channel (e.g. SMS, RCS, WhatsApp) and display limits and warning messages accordingly.
  • In Workflows, e.g. a “Message” Conversation Handling Activity Nimbus cannot anticipate the incoming integration channel proactively. If the length would be exceeded (e.g. a resolved Parameter leading to a long message), the activity will be skipped.

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

  • Please note that when you send a long message (via workflow or Nimbus UI), the customer generally receives multiple SMS at the same time. This 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).

💡Recommendation:  If you intend to handle multiple IM channels via the same workflow and service, keep messages (including resolved Parameters) short in order to not exceed the most restrictive limits. 

1Also refer to Twilio' documentation on maximum message length. 
2Also 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.
    • 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.

      Show list of 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. 
    • Message editing & deletion, reactions and replies are not supported and will not be supported (Twilio API limitation)
 
 

SMS / RCS specific limitations

SMS/RCS specific limitations

  • Provider Connectors > Twilio - Currently the integration works with “United States” region only.
 
 
 

Table of Contents