kirklandsig/AIReceptionist v0.2.0

v0.2.0 — call artifacts, intakes, DTMF, calendar, GA Realtime

on GitHub

AIReceptionist 0.2.0 is the first tagged release since 0.1.0 (March 2026). It collects six months of work that has been running in production on a real law-firm phone line the whole time. If you deployed 0.1.0, treat this as a major upgrade: the configuration schema grew substantially, one metadata field changed shape, and the way you authenticate to OpenAI changed because OpenAI retired the Realtime Beta API.

Full detail for every item below is in documentation/CHANGELOG.md.

Highlights

Call artifacts and notifications

• Call recording (LiveKit Egress) to local disk or any S3-compatible bucket, with a spoken consent preamble.
• Call transcripts in JSON and Markdown with per-call metadata (caller, outcomes, duration, tools used, languages detected).
• Multi-channel message delivery: file, email (SMTP or Resend) and webhook channels can run simultaneously per business.
• One consolidated call-end email per call with an AI-generated summary, the transcript attached as .txt, any message taken, booking details, intake answers and info-packet sends. Booking and message triggers are configurable.
• Retention sweeper and a failures CLI for delivery records that could not be sent.

New caller-facing capabilities

• Google Calendar integration: check_availability and book_appointment tools, relative-date resolution ("next Tuesday"), optional invite to the caller.
• Structured phone intakes: a per-business intakes block defines the questions; the agent asks them, records answers, emails partials after each answer, and finalizes. agent.mode: intake_only turns a line into intake-only.
• Keypad (DTMF) entry for digit-only intake questions such as callback numbers and SSNs, so digits are captured exactly instead of transcribed.
• DTMF auto-attendant: map keypad digits to transfer targets or actions.
• Consent-gated information packets by email, with two-step confirmation of the destination address.
• end_call tool and voice.idle safety nets: silence timeout, maximum duration, and an unproductive-turn ceiling, all configurable.
• Multi-language auto-detection with a per-business allowed-language list.

Reliability and operations

• Realtime error safety net: on a recoverable model error (typically a token rate limit) the agent speaks a short filler and retries instead of going silent.
• voice.reasoning_effort and voice.max_response_output_tokens to control latency and protect per-minute token budgets.
• Signaling warmup at worker start and a generation watchdog, eliminating the "first call rings out" cold-start problem and stale-worker takeovers.
• CallerID capture fixes for Asterisk/BYOC trunks, configurable SIP transfer URI, late SIP attribute handling.
• Linux systemd deployment guide, telephony setup guide, RingCentral/Twilio guide, and a rewritten configuration reference.
• GitHub Actions CI on Python 3.11 and 3.12.

Upgrade notes (read before deploying over 0.1.0)

1. OpenAI authentication. OpenAI shut down the Realtime Beta API on 2026-06-03. ChatGPT/Codex OAuth tokens (voice.auth.type: oauth_codex) no longer work: the call connects and the caller hears silence. Use voice.auth.type: api_key with a standard sk- key in OPENAI_API_KEY. Loading a YAML that still uses oauth_codex now logs a warning.
2. Default model is now gpt-realtime-2.1 (thanks to @fady-mz, #21). gpt-realtime-2, gpt-realtime and gpt-realtime-2.1-mini remain valid choices; gpt-realtime-mini is deprecated by OpenAI. See the model table in the configuration reference.
3. Token rate limits. Realtime counts audio as tokens and re-sends the system prompt every turn. On a low OpenAI usage tier, multi-turn calls exhaust the per-minute budget and the agent goes silent mid-call. Raise the tier; set max_response_output_tokens and reasoning_effort: low as mitigations. Details in troubleshooting.
4. Breaking metadata change: CallMetadata.outcome: str | None became CallMetadata.outcomes: set[str]. Anything consuming transcript metadata JSON must read the new field.
5. Config schema. messages.delivery: "file" is still accepted and auto-converted, but new deployments should use messages.channels. Unknown keys and invalid timezones are now rejected at load.
6. Dependencies. Minimum livekit-agents and livekit-plugins-openai is 1.8.2. New production dependencies for email, S3, Google Calendar. Python 3.11 or 3.12 recommended for production.
7. Removed module. receptionist/messages.py moved to receptionist/messaging/. Import paths change if you extended it.

Verification

669 tests pass (2 skipped by design). The tagged commit is deployed on the maintainer's production worker with livekit-agents 1.8.2 and gpt-realtime-2.1, validated with live PSTN calls.

Thanks

@trinicomcom for the Asterisk-side bug reports and feature requests that drove the CallerID, transfer URI, end_call, idle safety-net and DTMF work (#6, #9, #10, #11, #16). @fady-mz for the Realtime 2.1 model update (#21).