Twilio Setup

TheFaithApp uses a Twilio account owned by the church. The church controls its phone number, credentials, geographic permissions, compliance registrations, usage, and billing. This connection can support:

• SMS campaigns and staff replies.
• The signed SMS inbox, including STOP, START, HELP, join keywords, and text-to-give keywords.
• WhatsApp delivery when the configured sender is approved for WhatsApp in Twilio.
• Outbound, audio-only homebound phone-companion conferences.

​

What You Need

Before opening TheFaithApp, prepare:

• A Twilio account with two-factor authentication enabled.
• The production Account SID and Auth Token from the Twilio Console.
• A Twilio number with the capabilities you intend to use:
  • SMS for campaigns, replies, keywords, and the inbox.
  • Voice for the homebound phone companion.
• A funded, upgraded account for normal production use.
• Any registration or approval required by Twilio and the destination country.
• A small group of consented test recipients whose phone numbers are in E.164 format, such as +256... or +1....

Choose the number by capability, not only by country or price. Some Twilio numbers support both Voice and SMS, while others support only one. Review the capability badges before buying or assigning a number.

​

1. Prepare the Twilio Account

1. Sign in to the Twilio Console.
2. Enable two-factor authentication for account owners and administrators.
3. Open Phone Numbers > Manage > Buy a number or Active numbers.
4. Choose a number with SMS capability. Also require Voice capability when the church will use the homebound phone companion.
5. Complete any country-specific regulatory or sender registration shown by Twilio.
6. Review pricing for the countries the church will message or call.
7. Set usage alerts and limit geographic access to the countries the church actually serves.

For outbound international calling, open Voice > Settings > Geo permissions and enable the required low-risk destination ranges. Only enable high-risk ranges when the church has a specific, reviewed need.

​

2. Connect Twilio in TheFaithApp

1. In the admin dashboard, open Marketing > Integrations.
2. In the Twilio card, select Configure.
3. Enter the Twilio Account SID.
4. Enter the Twilio Auth Token.
5. Enter the sending number in E.164 format, including the leading + and country code.
6. Turn on Active.
7. Turn on Set as Default Provider when Twilio should handle the church’s SMS campaigns and replies.
8. Select Save.
9. Select Test Connection.

The connection test verifies the credentials against the Twilio account. It does not send a message, place a call, prove that the number has SMS or Voice capability, or confirm that a destination country is permitted. Complete the live checks later in this guide. TheFaithApp encrypts the saved Account SID and Auth Token and masks them when the configuration is reopened.

​

3. Add the Incoming Messaging Webhook

The webhook is required for the SMS inbox, staff replies to inbound threads, opt-out and opt-in handling, join keywords, and text-to-give keywords.

1. Save and activate Twilio in TheFaithApp.
2. Copy the Webhook URL shown in the Twilio configuration drawer.
3. In Twilio, open Phone Numbers > Manage > Active numbers.
4. Select the same number entered in TheFaithApp.
5. Find Messaging Configuration.
6. Under A message comes in, choose Webhook.
7. Paste the copied URL.
8. Select HTTP POST.
9. Save the Twilio number.

The URL is church-specific. Do not reuse one church’s webhook URL for another church or replace it with a dashboard page URL. TheFaithApp validates Twilio’s signature before accepting an inbound message. Repeated delivery of the same Twilio message does not create a duplicate inbox message or repeat a keyword action.

​

4. Prepare SMS and WhatsApp Delivery

​

SMS

• Confirm the configured number can send SMS to every destination country the church intends to use.
• Complete any required sender registration before sending campaigns.
• Collect and retain the recipient’s consent before adding them to SMS outreach.
• Keep Reply STOP to opt out in campaign messages. TheFaithApp adds it when a campaign does not already contain an opt-out instruction.

​

WhatsApp

WhatsApp works only when the configured number is also an approved Twilio WhatsApp sender. Approval and template rules are managed in Twilio, not in TheFaithApp. For a temporary Twilio WhatsApp Sandbox test, each test recipient must first join the sandbox using Twilio’s join instructions. Do not treat a sandbox pass as production approval. Before launch, move to the church’s approved WhatsApp sender and complete Meta and Twilio onboarding. If the configured number is not enabled for WhatsApp, leave WhatsApp delivery off and use SMS.

​

5. Prepare the Homebound Phone Companion

The phone companion places outbound calls. You do not need to create a TwiML App, configure an incoming Voice webhook, or paste a separate Voice callback URL into Twilio. TheFaithApp supplies non-recorded conference instructions and a signed status callback for each participant call. Before the first session:

1. Confirm the configured Twilio number has Voice capability.
2. Upgrade the Twilio account if it is still on trial.
3. Open Voice > Settings > Geo permissions and enable only the destination countries the church needs.
4. Confirm Voice and conference pricing for those countries.
5. Record each participant’s consent in a Homebound phone companion care request.
6. Store each participant’s real telephone number in E.164 format.
7. Confirm the TheFaithApp server scheduler runs every minute.

In TheFaithApp, authorized staff open Church Management > Pastoral Care > Care Programs, select between two and ten consented requests, and schedule the shared line. Launch now is available for an intentional live test. The page refreshes active calls automatically. Normal final participant statuses include completed, busy, no-answer, failed, and canceled. One failed participant does not stop the remaining calls. Recording is always disabled for this workflow.

​

6. Complete a Safe Live Test

Use test recipients who know a message or call is coming. Do not use a full member list for the first test.

​

Messaging test

1. Select Test Connection in the Twilio drawer.
2. Send one SMS campaign to a consented test recipient.
3. Confirm it appears in Monitor > Logs > Messaging in Twilio.
4. Reply HELP from the test phone and confirm an inbound thread appears in TheFaithApp.
5. Test a disposable join keyword.
6. Test STOP, confirm sending is blocked, then reply START to restore the test recipient’s consent.
7. Schedule a second small campaign and confirm the server launches it at the selected time.

​

Voice test

1. Create at least two consented homebound phone-companion test requests.
2. Schedule a session and select Launch now.
3. Answer the test phones and confirm they hear the introduction and join the same audio conference.
4. Confirm the session moves through calling or live state and then completes.
5. In Twilio, open Monitor > Logs > Calls and inspect the participant calls and Request Inspector.
6. Confirm the status callback received a successful 2xx response.

​

Troubleshooting

​

Server Readiness

This section is for the team operating TheFaithApp. Churches using the hosted service do not need to change server settings themselves.

• Set APP_URL to the public HTTPS API origin, such as https://api.thefaithapp.com.
• Never leave APP_URL set to localhost or a development tunnel in a staged or production deployment.
• Preserve the original HTTPS scheme and hostname through the reverse proxy so Twilio signature validation uses the same URL Twilio called.
• Run Laravel’s scheduler every minute and keep the queue workers healthy.
• Keep TLS, DNS, and the callback route publicly reachable from Twilio.
• Review Twilio Messaging and Call Logs after deployment and confirm callbacks return 2xx responses.

​

Security and Billing

• Treat the Auth Token like a password. Do not send it by email, paste it into support tickets, commit it to Git, or include it in screenshots.
• Enable two-factor authentication and usage alerts in Twilio.
• Rotate the Auth Token immediately if it is exposed, then update and retest the connection in TheFaithApp.
• Enable only the geographic destinations the church needs.
• Review messaging, Voice, conference, number rental, and WhatsApp charges in Twilio before launch.
• If the church stops using Twilio, turn the provider off in TheFaithApp before releasing or canceling the Twilio number.

​

Twilio References

• Twilio phone numbers and sender types
• Incoming messaging webhooks
• Voice dialing geographic permissions
• Twilio trial limitations
• Rotating a Twilio Auth Token
• Twilio Virtual Phone messaging guide