home

MinistryPlatform

RealmRealm AccountingMinistryPlatformeGivingPDSACSConnectShepherdGrowth MethodHeadMasterRefresh WebsitesTrust CenterGo MethodMissionInsite
RealmRealm AccountingMinistryPlatformeGivingPDSACSConnectShepherdGrowth MethodHeadMasterRefresh WebsitesTrust CenterGo MethodMissionInsite

What would you like to know more about?

Show Contents

Show Page Sections

thumbnailMinistryPlatform

Integrations

Twilio

With Twilio, you can send and receive messages at scale using Messaging APIs. This makes it the perfect integration to send SMS messages from MinistryPlatform directly to your congregation! You can also view inbound text replies. With a one-time configuration, you'll be good to go.

Note: Diocesan SPoCs: You only need one account, and each of your parishes can have their own SMS Outbound Number.

Cost

There is no charge from ACS Technologies for configuring the integration.

Fees from Twilio are assessed as per each church's individual contract agreement. See Twilio's SMS Pricing page. Pricing is based on your usage, with discounts for committed usage as you scale. Be sure to ask about not-for-profit pricing!

Messaging Options

We usually recommend churches use toll-free numbers in Twilio, which send messages faster and are reliably received by cell phone carriers. However, you should choose the messaging option that best fits your needs. See this Twilio article to learn the differences between messaging options.

Planning to send text messages to contacts in countries outside of the United States? Make sure your Twilio account is configured to allow texting to those regions. And make sure you've enter the full phone number (with "+" and the country code) on the Contact record.

Texting Segments

Segments can determine what your texts look like and how much you pay to send them.

Every text message is limited to a certain number of characters. That limit is called a segment. If your message is longer than the limit, it creates a new segment. Sending a really wordy text? Your long text will still send, just with more segments. You pay by the segment.

How many characters do you get per text? That depends on the following:

  • Traditionally, 160 characters.
  • If you use emojis, 70 characters.
  • Certain accented characters, non-standard spacing, smart quotes, and reassembly headers are more complex to encode and can further reduce the number of characters available per segment.

For more information, see this Twilio article.

See Also

Integration Setup

A SPoC can complete this one-time initial setup with Twilio to enable text messages from MinistryPlatform.

  • You must have an account with Twilio to configure this integration.
  • Make sure you've completed Milestones 1 through 4 of the Twilio Onboarding process.
  1. Set up or update your Twilio account for SMS.
    • Be sure to ask about not-for-profit pricing available in Twilio.
    • Diocesan SPoCs: You only need one Twilio account, and each of your parishes can have their own SMS Outbound Number.
  2. Update your Domain record in the Platform.
    1. Go to System Setup > Domains/Accounts, and open your Domain record.
    2. Click Edit Record, and scroll down to the SMS Configuration section.
    3. For SMS Server Username, enter your Twilio Account SID. You can find this on your Twilio dashboard under Account Info or on your account under API Keys & Tokens.
    4. For SMS Server Password, enter your Twilio Twilio Auth Token. You can find this on your Twilio dashboard under Account Info or on your account under API Keys & Tokens.
    5. For SMS Server Callback Secret, generate a new GUID and paste it in this field.
      Tip: We recommend using a GUID Generator to generate a random value.
    6. You may be in a situation where you don't want MinistryPlatform to send any texts for account verification, password recovery, one-time code logins, and multi-factor authentication. To disable texting for account management (without affecting texts sent from the New Message Tool and other areas of the Platform), set Disable SMS for Account Management to Yes. Otherwise, keep it set to No.
    7. You can set a curfew timeframe during which text messages do not send. If you've ever scheduled a group text to go out at 4 AM instead of 4 PM, you know why this can be useful! For Message Curfew Start Time, enter the time after which you don't want text messages to send in the Domain timezone. For Message Curfew End Time, enter the time before which you don't want text messages to send in the Domain timezone.
      Note: If a user tries to send or schedule a message during the curfew, they'll receive a warning. They can still send the message if needed. For example, if youth group is returning from a trip later than expected and you need to contact parents outside of the standard messaging hours. Make sure you clear your cache in the About section so these settings can take effect.
  3. Add Outbound SMS Numbers to the Platform. You must create one record for each active phone number on your Twilio account.
    1. Go to Communications > Outbound SMS Numbers.
    2. Click New Outbound SMS Number.
    3. For Number Title, enter a friendly name to describe this phone number.
    4. For SMS Number, enter the phone number or short code used to send the SMS message.
    5. Set Active to Yes for current numbers. The texting option won't display in the New Message Tool until you add at least one Outbound SMS Number and set it as Active.
    6. Set Default to Yes if this is the primary SMS number. The default number displays preselected in the New Message Tool as the From SMS Number value, and it's the number that all automated texts come from.
    7. Select a User Group to limit the use of this number to a certain group. When there is a user in the selected User Group, they can use the number in the New Message Tool.
      A church may want to specify a number for the Children's Ministry and ensure that only users in that User Group can send a text from that number. A diocese may want to specify a number for each parish to use and set up all of the users in each parish in different User Groups.
      Important: If all of your SMS numbers are associated with a User Group, users must be in one of those User Groups to send text messages. If they are not in a User Group that can access text messaging, they will not see the option to send a text in the New Message Tool.
  4. Update the Mass Text Quota for the appropriate Security Roles and User Groups.
    1. Go to Administration > Security Roles.
    2. Add a new role or open an existing one.
    3. For Mass Text Quota, enter the maximum number of text messages a user with this role can send at one time.
    Note: If a user's Mass Text Quota field is zero or left blank, they won't see the Text option in the New Message Tool. At installation, this field is set to zero for all Security Roles, so be sure to set it if users should see the option for texting.
  5. If you use Classroom Manager and want to send text messages through the Notify Front Desk button, you'll need to complete a few more steps.
    1. Go to Administration > Configuration Settings.
    2. Update the following CORETOOLS Configuration Settings based on your Twilio account. Make sure you have no trailing spaces in the values.
      • CORETOOLS, TwilioSID: The Account SID (not the App SID). You can find this value in your Twilio Dashboard.
      • CORETOOLS, TwilioTOKEN: The authorization token. You can find this value in your Twilio Dashboard.
      • CORETOOLS, TwilioSMSNUMBER: Your SMS numbers (input numbers only. This is the "From" SMS Number).
    3. Update the following COMMON Configuration Settings based on your Twilio account. Make sure you have no trailing spaces in the values.
      • COMMON, TwilioSID: The Account SID (not the App SID). You can find this value in your Twilio Dashboard.
      • COMMON, TwilioToken: The authorization token. You can find this value in your Twilio Dashboard.
      • COMMON, TwilioSMSNumber: Your SMS numbers (input numbers only. This is the "From" SMS Number).

Once you enable your Twilio integration, you can send text messages from the Platform using the New Message Tool!

Add a Webhook for Inbound Messages

Using a webhook, you can display inbound texts from your Twilio account in the Platform.

  • You must have a configured Twilio account. Fees apply for inbound messages.
Note: Already have a Twilio account and want help configuring the webhook? Contact Support, and our Integration Specialist can help you!

From your Twilio account, you can configure a messaging webhook for each active phone number. This optional feature is only for informational purposes. You can see replies from text messages the Platform sent, but you can't respond to their reply. It is not a two-way texting feature.

  1. Log in to your Twilio account.
  2. Under Phone Numbers, click the Manage Numbers tab.
  3. Under Active Numbers, select the number.
  4. In the Messaging section, set the following:
    1. Set Configure With to Webhooks....
    2. For A Message Comes In, select Webhook.
    3. Enter the webhook formula, which is your MinistryPlatform Base URL + /ministryplatformapi/callback/twilio/ + your SMS Server Callback Secret GUID (from your Domain record).
      https://{your platform domain}/ministryplatformapi/callback/twilio/a1b234cd-e567-8f90-1gh2-34ijklmn5o67
    4. In the last drop-down list, select HTTP POST.

    Twilio interface showing the Messaging section with the Webhook selected

When you receive an inbound text, it creates a record under Communications > Inbound Messages. The record includes:
  • Time received
  • Message To number
  • Message From number
  • Message Text, up to 1,600 characters – the Twilio limit
  • Emojis are accepted (but do affect cost)
  • Images and GIFs (these display as files attached to the Inbound Message record)
    Note: You can receive images with or without text.

Tips and Tricks

Troubleshooting

If you aren't receiving texts sent by the New Message tool, double-check each of the setup steps and values to ensure you didn't miss any details. If you're still don't receive texts (and the tool doesn't give an error or warning), the issue is most likely with your Twilio account. See this article from Twilio: Troubleshooting Undelivered Messages.

Carriers may automatically block messages that are not in compliance with the Telephone Consumer Protection Act (TCPA) guidelines. Be aware of your content, especially if it contains a clickable link. Avoid wording like "Click this link" and bit.ly links. Ensure your message has a footer with instructions to opt out. For more information on the TCPA, these articles may be helpful: TCPA Compliance and Telephone Consumer Protection Act of 1991.

Text messages with links are more likely to be filtered and blocked.

Do I need more than one Twilio number?

The New Message Tool supports the use of multiple Twilio numbers, so add as many numbers as your church or diocese needs! A benefit of multiple numbers is that you can spread your text volume over multiple numbers, which improves the speed and deliverability of your text messages.

You should use different phone numbers for these tools versus other third-party applications (for example, the OnlineGiving.Org text-to-give). If you already have a third party using your Twilio account, you may need to purchase additional numbers to use with these tools. Contact your third-party vendor for specific requirements.

Is there something I can do that would help process large quantities of text messages faster?

Twilio throttles things, so getting a Short Code can help to speed up processing time. Short codes have an 8- to 12-week provisioning time.

You can also get a toll-free number that's verified through Twilio to speed things up by up to three times faster. For more information from Twilio regarding processing time, see their Sending and Receiving Limitations on Calls and SMS Messages article. Toll-free numbers are available in five to seven days.

Long codes are turned off by Sprint if they see 200+ of the same message in one day.

Can I set up an auto-response to send when people reply to texts?

You can work with Twilio to update the auto-response sent to people who respond to texts sent through the New Message Tool. You can also work with a third party to create a custom web service for something more custom, like forward the message onto another number or auto-respond based on various criteria. For more on auto-responses, see the Twilio article, Set up an SMS Auto-Responder with TwilioStudio. Reach out to Twilio Support for assistance!

Can I customize the message about opting in to texting that displays on the Sign Up screen?

If you use Twilio for text, you may work with them to register your A2P (Application-to-Person) campaigns. Learn more with this article from Twilio, What is A2P 10DLC?.

To help with compliance, people who sign up for a MinistryPlatform user account see a default opt-in message on the Sign Up screen. If needed, you can update the Application Label for the MinistryPlatform Client to customize this wording: oauth.smsDataWarning.

Image displaying the Twilio Sign Up screen. The opt-in/opt-out messaging displays at the bottom.

Is there non-for-profit pricing?

Yes! Twilio offers special non-for-profit pricing; you just have to ask for it!

Integration
MinistryPlatform
portal

Last updated: July 16, 2024