Summary
This article focuses on the configuration of Twilio to work with ClinSpark.
At this time, ClinSpark is limited to supporting only one Twilio number per instance.
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
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
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.
The registration process may take several days to complete successfully. Twilio may not allow traffic through a number configured with a Message Service associated with an unverified A2P Campaign. Customers should be aware of this limitation when registering numbers for existing ClinSpark integrations, as service interruptions may take place until verification and registration is confirmed via Twilio.
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.
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.
https://www.twilio.com/docs/iam/credentials/api#authentication
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:
https://www.twilio.com/docs/usage/api/applications
From within the Twilio Console, create a new TwiML app, or, re-purpose another if that’s no longer used.
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/voiceVoice Status Callback URL:
https://environment.clinspark.com/voiceCallbackMessaging Request URL:
https://environment.clinspark.com/smsInMessaging Status Callback URL:
https://environment.clinspark.com/smsCallback
Leave all Request Methods as the default, HTTP POST.
Do not define any Fallback URLs.
Be sure to replace ‘environment’ from the above examples with the subdomain used to interact with the ClinSpark environment being configured. Ensure the URL patterns are otherwise the same.
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.
For initial setup a Messaging Service is not required for number messaging configurations. However, configuration and use of Messaging Services may be necessary depending on how the number is being used. Services are covered in a later part of this article.
Twilio Settings in ClinSpark
An administrative user with access to the Administration > General Settings are of ClinSpark can modify Twilio account 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.
Be sure to include the country prefix for the phone number. This can be observed by accessing the number in the Twilio console, or, verifying against the default country prefix here: List of country calling codes
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 -https://www.twilio.com/docs/sms/troubleshooting/debugging-tools
Regional regulatory requirements - https://www.twilio.com/en-us/guidelines/regulatory
Geo-permissions (for multi-site international customers) - https://support.twilio.com/hc/en-us/articles/223180168-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.
