Connecting Twilio

Twilio is still supported for workspaces whose Telecom Provider is set to Twilio.

Use this path for legacy Twilio workspaces, including Rolling Suds orgs that should stay on the Twilio phone stack. If your workspace should use the newer default provider, follow the Esendex setup guide instead.

When Twilio is the active provider, the shared number can:

• send outbound SMS
• receive customer SMS replies
• ring authorized office users inside the Android app for inbound calls
• forward unanswered inbound calls to your saved office line
• start outbound company-line calls from mobile customer records and Messages
• record voicemail when voicemail is enabled
• log missed calls and voicemail into Messages
• power automation steps like Make Call and Voicemail Drop

The dedicated Phone workspace provides the daily dialer, call history, missed-call filters, voicemail transcripts, and secure recording playback. Its Coaching and Intelligence settings add custom weighted scorecards, retry-safe AI review, manager workflow, post-call tasks and drafts, role permissions, recording disclosure, redaction, and retention.

Where To Configure It

Go to Settings in the admin app and open the Phone / Voice card.

1. Set Telecom Provider to Twilio.
2. Enter your Shared Twilio Number.
3. Enter Forward Calls To for the office or mobile line that should ring first.
4. Turn on Voice Enabled if the workspace should receive inbound calls.
5. Save the settings.

If you want voicemail recording and custom audio greetings, keep Voicemail Enabled on and choose either Text to speech or Custom audio file for the greeting type.

When you choose Custom audio file, upload or select the greeting audio before saving. CE Pro blocks the save if custom-audio mode is selected without an audio file.

Switching a workspace from Esendex to Twilio may turn Voice Enabled off until the Twilio number and forwarding destination are ready. This keeps the workspace from receiving calls through an incomplete provider setup.

Required Server Settings

Twilio workspaces still need the Twilio server environment variables in the active app deployment:

• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN
• TWILIO_PHONE_NUMBER

If those values are missing, Twilio SMS, outbound calls, and webhook-driven call handling cannot run even if the workspace settings are saved correctly.

The signed Android softphone also requires these secure deployment values:

• TWILIO_API_KEY_SID
• TWILIO_API_KEY_SECRET
• TWILIO_TWIML_APP_SID
• TWILIO_PUSH_CREDENTIAL_SID

The Android build must contain a google-services.json for the same Firebase project as the Twilio FCM v1 push credential. Keep the API-key secret, Firebase service-account key, and app configuration file out of source control. For EAS, store the Android configuration as a secret file variable named GOOGLE_SERVICES_JSON; EAS mounts it only on the remote builder. When submitting from a workstation, LOCAL_GOOGLE_SERVICES_JSON can point to the same downloaded file for local config resolution. Keep that file ignored and outside source control. The repository-level mobile release archive excludes the web project, local dependencies, generated Android output, test artifacts, and credentials so only reproducible mobile source and the shared pricing/payment package are sent to the EAS builder.

Because the softphone adds native Android and Firebase code, it requires a new signed APK. An Expo over-the-air update cannot add it to an older binary, and Expo Go cannot test it.

Before registering the signed Android app with Twilio, CE Pro now verifies that Firebase Cloud Messaging can return a device token. If the APK was built without a valid google-services.json, the app stays open, marks native in-app calling unavailable, and uses the secure company-line callback flow. This safety check prevents an incomplete preview or production build from crashing after sign-in. Adding the missing Firebase configuration still requires a newly signed APK; an over-the-air update cannot add native Firebase resources.

Callback URLs

Configure the exact callback URLs shown on the Phone / Voice card in Twilio.

• Voice inbound: /api/webhooks/twilio/voice/inbound
• Recording callback: /api/webhooks/twilio/voice/recording
• Transcription callback: /api/webhooks/twilio/voice/transcription
• SMS inbound: /api/webhooks/twilio
• SMS status: /api/webhooks/twilio/status

The settings card shows full URLs for the current environment so you do not have to compose them by hand.

Voice Settings

The Phone / Voice card includes voice-specific controls:

• Voice Enabled turns inbound call routing on for the workspace.
• Forward Calls To controls the office or cell number that should ring first.
• Voicemail Enabled records voicemail when no one answers.
• Greeting Mode supports text-to-speech or uploaded custom greeting audio.
• Call Recording stores call recordings when Twilio returns them.
• Missed Call Alerts raises internal notifications for missed calls and voicemail.

The readiness panel will not mark voice ready until a Twilio number and forwarding destination are present.

Inbound calls first ring up to ten active Android users whose workspace role includes Make calls. The app shows the customer number with Answer and Decline controls and keeps registered devices reachable through an FCM call notification while the app is backgrounded or not running. Android's explicit Force stop action suppresses push delivery until the app is opened again; office forwarding and voicemail remain available during that interval. When more than ten authorized memberships exist, CE Pro prioritizes the devices that registered for mobile voice most recently. Opening the signed Android app with an active session refreshes that presence.

If no app user answers within 18 seconds, CE Pro follows the existing fallback: the saved Forward Calls To number rings for up to 25 seconds. When the office does not answer, is busy, or the destination's carrier voicemail answers, CE Pro returns the original caller to the workspace voicemail greeting and records the message in Messages. A mobile-registration lookup failure also uses this fallback instead of taking the company line down.

Calling Customers From Messages

Open a customer, lead, estimate, or conversation in the signed Android app and select Call. When the app phone is registered, CE Pro places the call directly inside the app:

1. Allow microphone access when Android asks.
2. Select Call in Clean Estimate.
3. The customer receives one call showing the shared Twilio number as caller

ID.

1. Use Mute, Unmute, and End on the full-screen call controls.
2. The completed call is logged against the selected customer record.

When native in-app audio is unavailable, including mobile web and older Android builds, CE Pro uses the secure two-step callback:

1. The configured profile phone rings first. If the user has no profile phone,

CE Pro rings the workspace's Forward Calls To number.

1. Answer that call and stay on the line.
2. Twilio then calls the customer and shows the shared Twilio number as caller

ID.

1. The completed call is logged in the customer's Messages thread.

On the callback path, the customer is not called until the team member answers the first leg. Native in-app calls currently save call activity and duration but do not create a recording or transcript. Provider-recorded callback and forwarded-conference paths continue to follow the workspace recording and privacy settings.

Recording and transcript retention are also controlled in Phone > Intelligence settings. The daily retention process deletes expired recordings from Twilio and clears expired transcript/review content from Clean Estimate.

Testing Checklist

After setup, test:

1. Send a manual SMS from Messages.
2. Reply from a real phone and confirm the inbound reply lands in the thread.
3. In Android 1.1.2 or later, select Call in Clean Estimate and confirm the

approved QA customer rings once from the shared Twilio number.

1. Call the Twilio number from an approved QA phone and answer inside the app.
2. Repeat with the app unanswered and confirm the saved office number rings.
3. Let the fallback call go unanswered and confirm the caller hears the CE Pro voicemail

greeting, can leave a message, and the recording appears in Messages.

1. Run one workflow test for Make Call and one for Voicemail Drop.

Troubleshooting

SMS not sending

• Verify the workspace Telecom Provider is set to Twilio.
• Verify your Twilio credentials are present in the app environment.
• Confirm the SMS add-on is active on the workspace plan.
• Check your Twilio console for account suspension, balance, carrier, or compliance issues.

Customer replies do not appear

• Confirm the Twilio messaging webhook points to /api/webhooks/twilio.
• If the number belongs to a Twilio Messaging Service, open that service's

Integration settings and select Defer to sender's webhook. A service with no inbound URL and this option disabled will accept replies without forwarding them to Clean Estimate Pro.

• Look for the message in Twilio under Messaging > Logs.
• Confirm the customer replied to the exact Twilio number shown in Settings.

Voice calls are not ringing your office

• Verify Voice Enabled is on.
• Verify the incoming voice webhook points to /api/webhooks/twilio/voice/inbound.
• Verify the forwarding number is saved in E.164 format.
• Make sure your Twilio number supports voice, not just messaging.
• For in-app ringing, install Android 1.1.2 or later, allow notifications, and

sign in with an active role that includes Make calls.

• Confirm the Android build's Firebase project matches the FCM v1 push

credential referenced by the mobile access token.

• If the app shows native calling as unavailable, confirm

GOOGLE_SERVICES_JSON was mounted in the same named EAS environment used to build that APK. Rebuild after correcting it; an OTA update is not enough.

• Expo Go and older APKs cannot receive Clean Estimate softphone calls.
• If Twilio's Request Inspector shows an HTTP 403, confirm the app deployment

has the primary auth token for the same Twilio account as the phone number. Current CE Pro deployments validate Twilio's complete, evolving voice payload, including CallToken and the full Call* field set, and accept Twilio's standard HTTPS URL signature variants.

The Messages call button fails

• Confirm Voice Enabled, Shared Twilio Number, and Forward Calls To

are configured.

• On Android, allow microphone access and confirm Call in Clean Estimate

appears. If native registration is unavailable, the sheet intentionally uses the secure callback flow.

• The first outbound leg rings the current user's profile phone. When no profile

phone is saved, it falls back to Forward Calls To.

• Answer the first call from the shared Twilio number; the customer leg starts

only after that call is answered.

Wrong phone number appearing

• Verify the number format in the customer record.
• Verify the workspace Twilio number is saved in E.164 format with the leading + and country code.
• If a customer has multiple phone numbers, make sure the primary number is correct.