> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thefaithapp.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Twilio Setup
> Connect a church-owned Twilio account for SMS, approved WhatsApp delivery, inbound keywords, and the homebound phone companion.
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.
Twilio's browser-based Virtual Phone is for messaging tests, not Voice calls.
The homebound phone companion rings real telephone numbers. Twilio Video is
a separate product and is not used by this workflow.
## 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.
Trial accounts are useful for a first connection check, but they restrict the
destinations that can be called or messaged. A verified destination can
still be unavailable when it is outside the trial account's permitted
country. Upgrade the account before treating trial results as production
readiness.
## 1. Prepare the Twilio Account
1. Sign in to the [Twilio Console](https://console.twilio.com/).
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.
The webhook must be the public HTTPS URL shown by TheFaithApp. `localhost`, a
private IP address, a temporary development tunnel, or the web-dashboard URL
will not work in production.
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.
A `busy` or `no-answer` result can still prove that Twilio accepted the
outbound call and that the status callback worked. It does not prove the
conference audio experience; answer at least two real phones for that check.
## Troubleshooting
| Symptom | What to Check |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Test Connection fails** | Re-copy the production Account SID and Auth Token from the same Twilio project. Rotate the token if it may have been exposed, then update TheFaithApp. |
| **Trial account says the destination is unverified** | Verify the test destination in Twilio. If it is outside the trial's permitted country, upgrade the account before retrying. |
| **Voice call is blocked** | Confirm the From Number has Voice capability and check **Voice > Settings > Geo permissions** for the destination country and number range. |
| **SMS sends but replies never appear** | Confirm **A message comes in** uses the exact TheFaithApp webhook URL with `HTTP POST`. If the number belongs to a Messaging Service, confirm whether the service defers to the sender webhook or overrides it. |
| **Twilio reports `403` for the webhook** | Confirm the webhook URL has not been rewritten by a proxy and that TheFaithApp still has the matching Auth Token. The public scheme and hostname must reach the API exactly as configured. |
| **Twilio reports `404`, `502`, or a timeout** | Open the webhook URL's hostname from outside the server, check TLS and DNS, and confirm the API is reachable. Do not use a local or temporary URL in production. |
| **Call stays at queued in TheFaithApp** | Check the Twilio Call Log Request Inspector for the status callback response. A failed callback prevents the dashboard from learning the final call state. |
| **WhatsApp delivery fails** | Confirm the sender is approved for WhatsApp, the recipient joined the sandbox when testing, and any required production template is approved. |
| **Scheduled SMS or phone sessions do not start** | Confirm the Laravel scheduler and queue workers are running. Scheduled SMS and phone-companion launch checks run every minute. |
## 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](https://www.twilio.com/docs/numbers-and-senders/choose-sender-type)
* [Incoming messaging webhooks](https://www.twilio.com/docs/usage/webhooks/messaging-webhooks)
* [Voice dialing geographic permissions](https://www.twilio.com/docs/sip-trunking/voice-dialing-geographic-permissions)
* [Twilio trial limitations](https://www.twilio.com/docs/usage/trials)
* [Rotating a Twilio Auth Token](https://www.twilio.com/docs/iam/api/authtoken)
* [Twilio Virtual Phone messaging guide](https://www.twilio.com/docs/messaging/guides/guide-to-using-the-twilio-virtual-phone)