...
This article focuses on the required configuration of Twilio to work with ClinSpark.
| Info |
|---|
At this time, ClinSpark is limited to supporting only one Twilio number per instance. |
Twilio leverages web services that are exposed in ClinSpark in order to communicate facilitate scenarios when where phone calls and SMS messages are sent and received. In order for this to happen, a given customer’s Twilio account must have a configured ‘TwiMLApp’. This guide providers a user the configuration settings in Twilio and what must take place in ClinSpark. Configuring Twilio provisioned phone number and configured TwiML App.
Configuring Twilio and ClinSpark is a shared responsibility where both the customer and the ClinSpark IQVIA support team are each required to take specific stepsactions.
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.
...
If a new phone number is required for this use case, use Twilio’s admin UI console user interface to provision it. Note 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://supporthelp.twilio.com/hc/en-us/articles/1260800720410-What-is-A2P-10DLC-
https://supporthelp.twilio.com/hc/en-us/articles/1260801864489-How-do-I-register-to-use-A2P-10DLC-messaging-
The A2P registration process must be done by the Twilio account business owner of the account, 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. These details are appropriately provided by business account owners. There are minimal 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.
| Info |
|---|
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
...
A service desk ticket should be raised to notify IQVIA Support of the account setup, and identify an engineering support team member as an admin user in the customer account. We may add additional internal support users as needed, though this is cost neutral. We will use this access only to configure and manage TwiML App setup and appropriate configuration settings controlled by superadmin users with your ClinSpark instance.
...
IQVIA Support TasksTasks
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 application endpoints such as webhooks. Create a new app or 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.
From the Number menu, click the ‘Tools’, TwiML Apps and then the ‘Add’ icon.
...
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
...
Ensure that the ‘optional’ settings are shown
...
.
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
...
Ensure that the voice and messaging sections are configured with the configured TwiML App
ClinSpark Instance Setup
Ensure that Twilio Support is enabled in ClinSpark. This can only be done by a ClinSpark Support ‘superadmin’ account.
...
Twilio Settings in ClinSpark
Apply Twilio account settings. Note, this can only be done by a ClinSpark Support ‘superadmin’ account.
...
TwiML Application ID from previous step
...
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.
| Info |
|---|
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 setup tasks Twilio account/console exploration may be required after initial configuration of a number and TwiML App. While those are the bare minimum for most instances to get voice and message capabilities functions, some additional exploration may be required against other Twilio features depending on how the number will be used in ClinSpark. Many of these features (such as logging, short codes and message campaigns) are expected to be fully maintained by customers, as certain settings do not require IQVIA support team members to be involved with configuring for ClinSpark messaging.Customer . 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 as much as possible about Twilio 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 nearly all many SMS and Voice scenarios commonly used with ClinSpark integrationscapabilities.
We suggest customers be familiar with the following:
Call, message, and event logs -https://www.twilio.com/docs/sms/troubleshooting/debugging-tools
Messaging short codes - https://www.twilio.com/docs/sms/api/short-code
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 account 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. This may be also be necessary for US customers to properly establish A2P & Compliance requirements against the configured numberSeveral 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.
...
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 the 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.
...
...