Runbook: Resbit family number — calls not connecting or not logging

Purpose and scope

Restore inbound call handling on a family's Resbit number. Covers three failure shapes: callers hear rejection or dead air, calls connect but never appear in the call log, and escalation keywords fail to produce an SMS. Out of scope: Twilio account suspension and carrier-side outages — see Escalation.

Triggers

Run this runbook when any of the following is reported or observed. A caregiver says calls to the family number fail or go nowhere. The Number view's call log shows no new rows after known inbound calls. A voicemail containing an escalation keyword produced no text message. Cloudflare or Twilio dashboards alert on error rates for the worker.

Pre-checks

1. Confirm the worker is alive:

curl https://<worker-url>/health

Expected: ok resbit-telephony. Any other result means the worker deployment itself is down — go straight to Resolution step R4.

2. Confirm the number's status is active in Twilio Console → Phone Numbers → Active Numbers.

Diagnostic steps

1. Tail the worker while placing a test call from a known phone:

npx wrangler tail resbit-telephony

If no request appears when the call is placed → the webhook is not pointed at the worker — go to R1. If a request appears with status 403 → signature validation is failing — go to R2. If 200 but no log row → continue.

2. Check the number is registered to the family. In the Supabase SQL editor:

select n.e164, f.name, f.founder_phone, f.escalation_keywords
from resbit_numbers n join resbit_families f on f.id = n.family_id;

If the called number is absent → R3. If founder_phone is null, calls go straight to voicemail by design — not a fault, but confirm the caregiver expects that.

3. For missing voicemail rows specifically: transcription callbacks arrive after the recording completes, not at hang-up. Wait two minutes, then re-check resbit_calls:

select at, caller, triage, summary from resbit_calls order by at_ts desc limit 10;

4. For a missing escalation SMS: confirm the transcript actually contains a configured keyword (matching is case-insensitive substring against escalation_keywords), and that founder_phone is set — both conditions are required before any SMS is attempted. On a Twilio trial account, SMS delivers only to verified numbers.

Resolution

R1 — Repoint the webhook. Twilio Console → the number → Voice Configuration → "A call comes in": Webhook, https://<worker-url>/voice, HTTP POST → Save. Verify with a test call while tailing.

R2 — Fix the signed-URL mismatch. Signature validation reconstructs the URL from PUBLIC_URL; it must match the URL Twilio calls exactly, with no trailing slash. Correct PUBLIC_URL in wrangler.jsonc, then:

npx wrangler deploy

Danger: Never "fix" a 403 by disabling signature validation. The worker's no-token-means-reject behavior is intentional; an unsigned webhook endpoint would accept forged call records from anyone.

R3 — Register the number.

insert into resbit_numbers (family_id, e164)
select id, '+1XXXXXXXXXX' from resbit_families where name = '<family name>';

R4 — Redeploy the worker. From the telephony project directory:

npx wrangler deploy

Secrets (TWILIO_AUTH_TOKEN, SUPABASE_SERVICE_KEY) persist across deploys; re-enter them with npx wrangler secret put <NAME> only if they were never set on this worker.

Rollback

1. Stop — if a change made things worse, note the exact change and time.
2. Restore — webhook: repoint to the previously working URL. Worker: redeploy the last known-good commit of the telephony project.
3. Verify — run the Verification section below.
4. Document — record cause and fix in the incident note; update this runbook if the diagnosis path missed it.

Verification

Place three calls from a verified phone. First: answer at the forwarded phone — expect the whisper announcement, then a ✓ Forwarded & answered row. Second: let it ring out and leave a benign voicemail — expect a transcribed ◆ Voicemail — review row within about two minutes. Third: leave a voicemail containing the word "discharge" — expect a ▲ Escalated row and an escalation SMS to the caregiver's phone. All three rows must appear exactly once; duplicates indicate the idempotent upsert is broken and warrant a code-level look.

Escalation

Communication templates

Initial

The family number is currently not handling calls correctly. While it's being fixed, providers can reach you directly at . Voicemails from the outage window may be missing from the log.

Resolved

The family number is handling calls normally again as of . The gap was ; call records between and may be incomplete.

References

Worker source: resbit-workers/telephony/src/index.js, src/core.js. Provisioning steps: RESBIT_TELEPHONY_RUNBOOK.md. Webhook API details: Resbit Telephony Worker — Webhook API Reference.