Connecting Twilio

Current V2 and legacy V1: The Current V2 setup below configures the live inbound-call and voicemail foundation with deployment-managed provider credentials. Later sections preserve the legacy V1 self-service credentials, Phone/softphone, add-on, and outbound-call workflows as required parity and label them explicitly.

Twilio supports the current V2 inbound-call foundation and legacy V1 workspaces whose Telecom Provider is set to Twilio.

Use Current V2 setup for V2 inbound calls. Use the later legacy sections for V1 Twilio workspaces, including Rolling Suds orgs that should stay on the V1 Twilio phone stack. If a legacy V1 workspace should use the newer default messaging provider, follow the Esendex setup guide instead.

Current V2 capabilities

With the current V2 foundation, the configured company number can:

• send outbound SMS and receive customer SMS replies when it is also saved as

the workspace's separate SMS sender number

• forward unanswered inbound calls to your saved office line
• record voicemail when voicemail is enabled
• log scoped connected-call and missed-call activity, plus voicemail, for

conversation processing and staff alerts

• optionally record connected company-line calls after a spoken notice reaches

both participants

• optionally transcribe and score retained connected calls with evidence-based

coaching, next steps, and an editable follow-up draft in web Phone

• publish a versioned Call scorecard with weighted criteria and score

thresholds for future AI reviews

The mobile Calls/Missed calls filters, private playback, Call back, and call-bound Text back proposal is preserved separately and is not shipped while mobile interaction remains frozen pending explicit approval. Forwarded calls preserve a valid customer caller ID on the receiving phone; anonymous or withheld callers use the configured company number as a safe fallback. Twilio Client or SIP identities are not treated as customer phone numbers, even when the identity text contains digits; those calls stay in a scoped unmatched thread until staff can safely identify the caller.

Broader V1 capabilities preserved for parity

The following capabilities belong to the legacy V1 Phone stack and remain required V2 follow-up; this guide does not present them as current V2 controls:

• ring authorized office users inside the Android app
• start outbound company-line calls from mobile customer records and Messages
• power automation steps such as Make Call and Voicemail Drop

The current dedicated Phone workspace provides a daily summary, company-line readiness, filters, search, scoped call history, conversation links, retained voicemail/call playback, permission-gated callback-first calling from a saved call, retry-safe AI review, and the first V1-style coaching presentation. It also provides versioned custom weighted call scorecards. It does not yet provide the V1 free-form dialer, broader live call workflow, manager calibration, post-call alerts, live scripts, or automatic post-call tasks.

Current V2 setup

For current V2 company calls, recording, and voicemail, open Settings > Company calls, recording, and voicemail. Do not use the legacy Phone / Voice card for this procedure.

1. Turn on Enable inbound voice.
2. Enter the workspace Company voice number as full international E.164,

including the leading + and country code. If the same number is already saved as the workspace SMS sender, the voice field can stay blank and V2 uses that saved SMS number. Save a newly edited SMS number with its own Save action before relying on it here; an unsaved SMS draft is never treated as the active company voice number. A nonblank company or forwarding field must match E.164 even while inbound voice is off, because those fields are still saved; the form shows the field error and keeps Save unavailable instead of sending a mutation the server would reject.

1. Optionally enter Forward calls to in the same format.
2. Enable voicemail and review its 10–500 character greeting when calls should

be answered without forwarding or after forwarding does not answer. An enabled setup needs at least forwarding or voicemail; voicemail-only V2 setups are valid.

1. Choose the 1–365 day recording retention period and confirm the workspace's

notice, consent, and recording-law responsibility. Save remains unavailable until retention is a whole number inside that range while voicemail or company voice is on. The voicemail greeting must contain 10–500 characters. Turning voicemail off leaves the last valid greeting unchanged; retention remains active while company voice is on because every connected company call is recorded.

1. Review the 10–500 character connected-call notice. Every connected inbound

and outbound company call is recorded and AI-reviewed automatically; the configured notice plays to both participants before the bridge begins. Redact common sensitive details in new transcripts is a separate option that defaults off. It affects new transcripts only, and AI follow-up copy remains an editable draft that is never sent automatically.

1. Under Call scorecard, keep the built-in rubric or prepare a custom rubric

with 1–10 criteria. Enter a Scorecard name, Label, 1–100 whole-number Weight, and What good sounds like guidance for each criterion. All weights must total exactly 100. Set whole-number Passing score and Low-score threshold values from 0–100; the low-score threshold cannot be greater than the passing score. Select Save and activate new version to publish a new immutable version for future reviews.

1. Save, then copy the complete signed Twilio incoming-call webhook displayed

on this page into the A call comes in HTTP POST field for every active voice-capable company or brand number in this workspace. All of those numbers use the same organization-bound URL.

The scorecard version binds the exact criteria, weights, Passing score, and Low-score threshold used for a call review. A later settings edit publishes a different version and cannot rewrite a completed review. Automatic retries of one queued review revision keep its existing binding. Choosing Retry review after a failure creates a new review revision and binds the scorecard active at that time. Publishing does not automatically re-review old calls. If no custom scorecard is active, new reviews continue to use Rapport, Discovery, Clarity, Objection handling, Next steps, and Professionalism as the built-in six-category rubric. The Phone workspace labels unversioned built-in and older retained results Legacy scorecard · Passing 75 and does not assign them a new custom version.

In Phone, scores at or above Passing score are green. Scores from Low- score threshold up to—but not including—Passing score are amber, and scores below Low-score threshold are red. The scorecard editor currently shows only the active rubric; version browsing, restoring an earlier version, and switching back to the built-in rubric after custom activation remain future work.

This scorecard release is web-only. It does not change visible native mobile layout, navigation, controls, labels, or interactions. Manager calibration, automatic post-call alerts and tasks, and live call scripts remain separate parity work.

If the deployment has not configured its signed comms webhook secret, the rest of Settings still loads and the voice card shows that the signed webhook URL is unavailable. A deployment administrator must configure that secret before the Twilio number can use the V2 callback.

Once Twilio delivers a signed inbound CallSid, V2 saves only the minimum route result needed for replay: the unavailable reason, forwarding caller ID and destination, or voicemail greeting. It does not keep unrelated settings or a rejected caller's number in that durable result. Provider retries for the CallSid replay the same forwarding or voicemail response even if a teammate changes the company number, forwarding number, voicemail switch, or greeting after the first delivery. The changed settings apply to the next new call, not to an in-progress provider retry.

Only teammates whose manage_phones permission is enabled can change this configuration or publish a Call scorecard version. Teammates who can read Phone activity can see only the call reviews already authorized for their organization and locations; Phone access does not grant scorecard editing. See Permissions for the permission defaults and grant path.

Legacy V1 Phone and softphone setup

For the V1 Phone workspace, go to Settings and open Phone / Voice:

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 legacy 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 legacy workspace from Esendex to Twilio may turn Voice Enabled off until the Twilio number and forwarding destination are ready. This is a V1 Phone/softphone readiness rule, not the V2 voicemail-only rule above.

Required Server Settings

For a single-account deployment, Twilio workspaces still need these server environment variables in the active app deployment:

• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN
• TWILIO_PHONE_NUMBER

Connected-call AI review also requires the existing server-only OPENAI_API_KEY. The optional OPENAI_CALL_TRANSCRIPTION_MODEL and OPENAI_CALL_REVIEW_MODEL values can pin approved models; V2 otherwise uses gpt-4o-transcribe-diarize for speaker-labeled transcription and the existing admin model fallback for structured review. If the OpenAI key is absent, Settings refuses to enable company voice while this required AI-review key is missing. Calls already in progress retain their durable recording and review workflow if voice settings change after connection. An existing workspace also fails closed before a new inbound or outbound connection when the key is missing: inbound callers hear that recording and review are temporarily unavailable, and staff cannot start an outbound company-line call until the provider is restored.

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

Production multi-organization deployments that use one Twilio subaccount per workspace configure TWILIO_ORG_CREDENTIALS_JSON instead. This server-only JSON object is keyed by the internal organization UUID. An unchanged workspace can keep the original value with its accountSid and authToken. When rotating a workspace to another subaccount, use a current credential plus a historical array of the prior credentials. Keep each historical credential available until every call created under that account has finished and all of its recordings have passed retention and been purged from Twilio; then remove it. The global account SID and token remain a single-account fallback only. Never paste an auth token into Clean Estimate Settings, a brand record, a callback URL, or source control.

{
  "organization-uuid": {
    "current": {
      "accountSid": "AC_current_account_sid",
      "authToken": "current-server-secret"
    },
    "historical": [
      {
        "accountSid": "AC_prior_account_sid",
        "authToken": "prior-server-secret"
      }
    ]
  }
}

Clean Estimate checks new signed callbacks against the organization's current AccountSid and saves that non-secret account SID with the call. Status, recording, and transcription callbacks tied to an existing call, plus retention cleanup, resolve the same organization and the call's stored account. Outbound callback attempts save that account before the provider dial, so the exact internal attempt and reported provider call can keep using a retained credential if rotation happens while the call is underway. They select a matching current or retained historical credential before Clean Estimate enriches the call or fetches, lists, or deletes provider media. A missing or mismatched credential fails closed instead of trying another workspace's Twilio account. Historical credentials authorize only callbacks whose call identity and account match an existing saved call; they do not authorize a new inbound call after rotation.

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

Current Clean Estimate V2 inbound calls

Open Settings > Company calls, recording, and voicemail and copy the complete Twilio incoming-call webhook (HTTP POST) shown for that organization. Configure it as the A call comes in webhook, using HTTP POST, on every active voice-capable Twilio number for that organization—including each active brand number. Repeat this on each number even though the organization-bound URL is the same. The URL uses /api/webhooks/twilio-voice and includes an organization-bound ?o=... token; copy it exactly and do not remove, replace, or share that query value. A bare route without the displayed token is rejected.

V2 supplies its signed status, recording, and transcription callbacks inside the TwiML response, so do not compose or separately configure those URLs in Twilio. Every callback also requires Twilio's request signature.

V1 Phone workspace callbacks

The following paths belong to the established V1 Phone/softphone workflow. They are not substitutes for the displayed signed V2 inbound-call URL:

• 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 relevant settings card shows full URLs for its environment so you do not have to compose them by hand.

Legacy V1 voice settings

The legacy V1 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.

That V1 Phone/softphone readiness panel does not mark voice ready until a Twilio number and forwarding destination are present. The current V2 Settings > Company calls, recording, and voicemail foundation uses a different safe boundary: it requires a company Twilio number plus at least one destination—an E.164 forwarding number or enabled voicemail. A voicemail-only V2 workspace is therefore ready without an office forwarding number.

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 (Legacy V1)

Legacy V1 procedure: Current V2 does not yet provide in-app outbound company calling, device callback action, or the two-step Twilio callback flow. The preserved V2 mobile Calls proposal remains pending approval.

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

For the current V2 inbound foundation:

1. Call the configured Twilio number from an approved QA phone.
2. With forwarding configured, answer the office leg and confirm the provider

callback completes without a duplicate call/message or alert.

1. With voicemail enabled, leave a voicemail and confirm the signed recording

and transcription callbacks enrich the same scoped call. Verify retention redaction and provider cleanup with a non-production fixture; do not expose the Twilio recording URL. A voicemail-only setup should be tested without a placeholder forwarding number.

For the separate V1 Phone/softphone workflow, 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

Legacy V1 SMS only: SMS not sending

The provider selector, workspace Twilio credential controls, and SMS plan add-on below belong to V1. Current V2 messaging is deployment-managed; use Sending Messages for its supported sender, consent, and delivery troubleshooting contract.

• 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.

Legacy V1 SMS only: Customer replies do not appear

This webhook procedure documents the V1 Twilio SMS stack. Current V2 does not expose the V1 Telecom Provider or workspace credential controls.

• 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

Current V2 forwarding and voicemail

• For current V2, verify Enable inbound voice is on under **Settings >

Company calls, recording, and voicemail**.

• For current V2, verify the incoming voice webhook is the exact signed URL

displayed under Settings > Company calls, recording, and voicemail, including its ?o=... token, and that Twilio uses HTTP POST.

• Verify the forwarding number is saved in E.164 format.
• Make sure your Twilio number supports voice, not just messaging.
• If Twilio's Request Inspector shows an HTTP 403, confirm the app deployment

has the auth token for the same workspace subaccount as the phone number and that the callback reports that subaccount's AccountSid. Current V2 validates Twilio's complete, evolving voice payload, including CallToken and the full Call* field set, and accepts Twilio's standard HTTPS URL signature variants.

Current V2 does not ring or answer inside the Android app. Stop after the checks above when troubleshooting the current forwarding/voicemail foundation.

Legacy V1 Phone/softphone only: Android in-app ringing

• Verify Voice Enabled is on in the legacy Phone / Voice card and its

webhook uses /api/webhooks/twilio/voice/inbound.

• 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.

Legacy V1 only: The Messages call button fails

The current V2 foundation has no live Android answer controls or company-line outbound call button. Use this procedure only for the legacy V1 softphone.

• 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.