home

MinistryPlatform

RealmRealm AccountingMinistryPlatformPDSACSConnectShepherdGrowth MethodHeadMasterRefresh WebsitesTrust CenterGo MethodMissionInsite
RealmRealm AccountingMinistryPlatformPDSACSConnectShepherdGrowth 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 will be 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 Twilio's not-for-profit pricing!

Messaging Options

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

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. And 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. Note that 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.
  • And certain accented characters, non-standard spacing, smart quotes, and reassembly headers are more complex to encode and can further reduce the number of available 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.

  • An account with Twilio must be established before the integration can be configured.
  • 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 cannot be sent. 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 in the Domain timezone after which text messages should not be sent or scheduled. For Message Curfew End Time, enter the time in the Domain timezone before which text messages should not be sent of scheduled.
      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, the youth group is returning from a trip later than expected and parents need to be contacted 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 if the number is current. The texting option won't display in the New Message Tool until at least one Outbound SMS Number is added and set as Active.
    6. Set Default to Yes if this is the primary SMS number. The default number displays pre-selected 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 if you want to limit the use of this number to a certain group. When a user is in the selected User Group, the number will be available to them 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 you'll want to 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 via 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.
      • TwilioSID: The Account SID (not the App SID). You can find this value in your Twilio Dashboard.
      • TwilioTOKEN: The authorization token. You can find this value in your Twilio Dashboard.
      • 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.
      • TwilioSID: The Account SID (not the App SID). You can find this value in your Twilio Dashboard.
      • TwilioTOKEN: The authorization token. You can find this value in your Twilio Dashboard.
      • 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

Add a webhook to allow inbound texts from your Twilio account to display in the Platform.

Note: Already have a Twilio account and want help getting the webhook configured? Reach out to 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 coming back from text messages sent by the Platform, but you cannot 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 MP 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 an inbound text is received, 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 (display as files attached to the Inbound Message record)
    Note: Images can be received with or without text.

Tips and Tricks

Troubleshooting

If you are not receiving texts sent by the New Message tool, double-check each of the setup steps and values to ensure no details were missed. If you're still not receiving texts (and the tool is not giving an error or warning), the issue is most likely with your Twilio account. See these troubleshooting articles from Twilio: Basic and Advanced.

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 for opting out. For more information on the TCPA, these articles may be helpful: TCPA Compliance and Telephone Consumer Protection Act of 1991.

Sending links in your text message will likely get your text message 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 having multiple numbers is that it allows you to spread your text volume over multiple numbers, improving the speed and deliverability of your text messages.

The phone number used with these tools should be different from other numbers used with third party applications (for example, OnlineGiving.Org's text-to-give). If you already have a Twilio account in use by a third party, 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 from my standpoint 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 via the New Message Tool. You can also work with a third party to create a custom web service that could do something more custom, like forward the message onto another number or auto-respond based on various criteria. For more on auto-responses, please see Twilio's 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 texting, 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 will see a default opt-in message on the Sign Up screen. If needed, you can customize this wording by updating the Application Label for the MinistryPlatform Client: 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: May 9, 2024