Summary
This article focuses on the required configuration of Twilio to work with ClinSpark.
Twilio leverages web services that are exposed in ClinSpark in order to communicate scenarios when phone calls and SMS messages are sent and received. In order for this to happen, a given 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 is a shared responsibility where both the customer and the ClinSpark support team are each required to take specific steps.
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 admin UI to provision it. Note the number provisioned.
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://support.twilio.com/hc/en-us/articles/1260800720410-What-is-A2P-10DLC-
The A2P registration process must be done by the business owner of the account, not the IQVIA team. The process 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 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.
Add IQVIA Support as an admin user
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 Tasks
Create a TwiML App
A TwiML app binds a phone number to application endpoints such as webhooks. Create a new 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.
Note the SID, this is the Application SID to be configured in ClinSpark
Ensure that the ‘optional’ settings are shown
Replace the ‘YOUR_CLINSPARK_DOMAIN’ with the subdomain used to interact with ClinSpark. Ensure the URLs 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
The default country prefix as defined here: List of country calling codes
Post-Setup Tasks
Some additional setup tasks 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 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 SMS and Voice scenarios commonly used with ClinSpark integrations.
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
Configuring a Messaging Service
Messaging Services are Twilio account features that can alter behavior of how messages are handled based on specific use cases. Customers may benefit from exploring these capabilities depending on intended use. This may be also be necessary for US customers to properly establish A2P & Compliance requirements against the configured number. 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
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 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
