Summary

This article focuses on the configuration of Twilio to work with ClinSpark.

Twilio leverages web services that are exposed in ClinSpark to facilitate scenarios where phone calls and SMS messages are sent and received. In order for this to happen, a customer’s Twilio account must have a provisioned phone number and configured TwiML App.

Configuring Twilio and ClinSpark is a shared responsibility where both the customer and the IQVIA support team are each required to take specific actions.

Twilio Account Setup

Twilio configurations require that a customer has created a Twilio account and has logged in to the management dashboard. This task must be done prior to any setup done in ClinSpark.

Customers are expected to maintain full ownership and responsibilities over their Twilio accounts while ClinSpark integrations are in place.

Customer Responsibilities

Reserve a Number

If a new phone number is required for this use case, use Twilio’s console user interface to provision it. Be sure to note the number provisioned, as it will be used throughout this guide.

These articles from Twilio can assist customers in the number setup process.

https://www.twilio.com/docs/phone-numbers

https://help.twilio.com/articles/223135247-How-to-Search-for-and-Buy-a-Twilio-Phone-Number-from-Console

A2P 10DLC Registration

For US numbers, A2P (Application To Person) 10DLC (10 Digit Long Code) registration will be required if using SMS messaging services. Without this, SMS messages sent via that number may not be delivered by mobile carriers. Carriers in the US consider all Twilio traffic to be A2P.

US customers are encouraged to become familiar with the A2P registration requirements and read through the full Twilio documentation on the topic.

https://help.twilio.com/articles/1260800720410-What-is-A2P-10DLC

https://help.twilio.com/articles/1260801864489-How-do-I-register-to-use-A2P-10DLC-messaging

https://support.twilio.com/hc/en-us/articles/4407882914971-Comparison-between-Starter-Low-Volume-Standard-and-Standard-registration-for-A2P-10DLC

The A2P registration process must be done by the Twilio account business owner, not the IQVIA team.

The process typically requires a 'profile' of the business to be created and then selection of a 'brand' based on the volume of daily messages sent per number. There may be fees associated with the process as well (depending on message volumes).  Customers are to be responsible for proving these details and are expected to reach out to Twilio directly if there are questions about the process.

ClinSpark Environment Setup

IQVIA Support Tasks

Twilio messaging services and supported features can only be used in ClinSpark with the enabling of an advanced system setting. This setting must be enabled by a ClinSpark superadmin user. IQVIA support teams may need to be engaged to complete this task in each ClinSpark environment that Twilio functionality is needed.

Open

Customer Tasks

Once Twilio features have been enabled in a given ClinSpark environment, and Twilio account with provisioned number has been completed, customers can complete the remaining setup without IQVIA support team involvement.

Note Account SID and Auth Token Values

Customers should be familiar with how to access their Twilio Account SID and Auth Tokens. These are necessary to complete the configuration steps within ClinSpark, defined later on. Details about these can be reviewed in Twilio support documentation, or, from directly within the admin console.

REST API: Credentials | Twilio

Create a TwiML App

A TwiML app binds a phone number to a given ClinSpark instance using web services. More details about TwiML apps and Twilio REST API applications can be reviewed here:

REST API: Applications | Twilio

From within the Twilio Console, create a new TwiML app, or, re-purpose another if that’s no longer used.

Open

Provide a ‘friendly name’ for the app. We recommend including the Instance URL or a known Instance name so it can be easily recognized.

Once saved, access the new app to modify the Voice and Messaging configurations.

Twilio will generate a unique TwiML App SID. Note this value, as it will be used in later steps to be configured in ClinSpark.

Apply and save Request and Status Fallback URLs, using the following as a guide:

• Voice Request URL: https://environment.clinspark.com/voice

• Voice Status Callback URL: https://environment.clinspark.com/voiceCallback

• Messaging Request URL:https://environment.clinspark.com/smsIn

• Messaging Status Callback URL: https://environment.clinspark.com/smsCallback

Leave all Request Methods as the default, HTTP POST.

Do not define any Fallback URLs.

Configure Number to Use TwiML App for Voice and Messaging

Once the TwiML app is setup, you’ll now need to configure it for use with a specific number.

Access ‘Active Numbers’ in the Twilio console for this. For a given number, navigate to the configuration area. Be sure to define both Voice and Messaging Configurations with the TwiML app intended for that number.

Save the configuration for the number, and then complete remaining steps in ClinSpark.

Twilio Settings in ClinSpark

An administrative user with access to the Administration > General Settings are of ClinSpark can modify Twilio account settings.

Role Actions | Administration General Settings

Using the values that were defined previously, complete the setup in ClinSpark for SMS/Voice configurations.

• Authorization Token and Account SID values can be obtained from Twilio main console.

• Application SID is provided via the TwiML app configuration, noted from previous steps.

• The Twilio Messaging and Voice number defined should match the configured TwiML app.

Post-Setup Tasks

Some additional Twilio account/console exploration may be required after initial configuration. Additional phone/messaging features may need to be maintained by customers long-term depending on the use case. Settings outside of the active number and TwiML App configured in ClinSpark are outside the scope of support we offer.

Customers are encouraged to explore their Twilio account console and learn about capabilities on their own prior to reaching out to the IQVIA support team on questions. Many existing Twilio features in the console are useful for general troubleshooting and support purposes. Twilio has extensive documentation covering many SMS and Voice capabilities.

We suggest customers be familiar with the following:

• Call, message, and event logs -Debugging Tools | Twilio

• Regional regulatory requirements - Twilio Regulatory Guidelines for Countries | Twilio

• Geo-permissions (for multi-site international customers) - What Are Geographic Permissions and Why do They Exist?

• How to lookup error messages and error codes - https://www.twilio.com/docs/api/errors

Messaging Services

Messaging Services are Twilio features that can alter behavior of how SMS messages are handled based on specific use cases. For US customers, using a messaging service may be necessary to properly establish A2P compliance against a configured number.

Customers may benefit from exploring these service capabilities depending on intended use. Several features have practical value long term as they can influence the way messages are exchanged between sites, volunteers, and study participants. This includes using short codes, link shortening, and opt-out keyword behavior. Details about these features are available on the Twilio support site and directly within the account console.

https://support.twilio.com/hc/en-us/sections/360005227194-Messaging-Services

https://www.twilio.com/docs/messaging/services

Assigning a Message Service to an Active Number

When managing active phone numbers, customers can optionally determine if a messaging service is to be used for that number. By default, active phone numbers are not assigned to a messaging service, and messages route through the account as expected following default behaviors.

When not in use, inbound messages will go through whatever message handler is configured on the individual phone numbers, and route messages accordingly.

Inbound Message Handling

If an active number is setup to use a Messaging Service, the inbound message handling behavior may change from what is expected and not properly handle replies. This means that messages can be sent to recipients without issue, but any replies back from those recipients are not properly routed through the Twilio account and back into ClinSpark.

If customers are finding that inbound messages are not being received back into ClinSpark, we recommend to check to see if active numbers in use are configured with a Messaging Service. If so, that Messaging Service Integration settings can be changed to ensure that inbound messages defer to sender’s webhooks. Customers can access and modify these settings in this area of the Twilio account:

Messaging > Services > Select a Service > Integration

Adding IQVIA Support to Twilio Account

Customers can optionally decide to add IQVIA support team members to their account as an additional user type as Developer, Support, or both. A service desk ticket should be raised to notify IQVIA of this and identify a support team member to be added into the customer account.

Adding IQVIA support may allow access to the account to help review and manage TwiML App setup and other logs to troubleshoot configurations.

See also

1. Manage Correspondence