axiom: ALWAYS verify enabled_features contains 'telephony' after any assistant update — API PATCH success does NOT mean telephony is enabled. The master toggle is portal-only for first enablement.

category: telephony

source: Post-mortem session 82, confirmed 2026-02-26

severity: critical


axiom: Use Qwen/Qwen3-235B-A22B as default model for all SubAIVA voice agents — zero API key cost, lowest latency, 32K context is sufficient for receptionist use cases. Only switch to Gemini Flash for knowledge-heavy assistants needing 1M context.

source: Telnyx model catalog analysis

severity: high


axiom: WebRTC browser calls cost $0.002/min vs $0.06/min for phone calls — a 30x cost difference. ALWAYS prefer WebRTC widget for demos and website interactions. Reserve phone numbers for inbound customer calls only.

source: Telnyx pricing analysis 2026-02-26


axiom: Set voice_speed to 0.95 and wait_seconds to 0.4 as default for all Australian business receptionist agents. This sounds natural and professional without being sluggish or robotic.

source: Live testing across multiple assistants

severity: medium


axiom: ALWAYS use async:true on webhook tools that write to CRM (GHL lead capture). The AI continues talking while the webhook fires in background. Use async:false ONLY for tools where the AI needs the response (availability checks, pricing lookups).

source: Webhook architecture best practice


axiom: Telnyx Cloudflare tunnel MCP URLs rotate on restart — NEVER use rotating tunnel URLs in production. Use persistent domain (ngrok static, Cloudflare named tunnel, or dedicated server) for MCP server connectivity.

category: infrastructure

source: Live MCP server failure analysis


axiom: For Australian number provisioning: create a Requirement Group ONCE with all regulatory docs (ABN, ID, address proof), then reuse it for all subsequent number orders. This eliminates the 72-hour validation wait for repeat orders.

source: Telnyx requirement groups documentation


axiom: The <telnyx-ai-agent> custom element is the production widget — use it for all customer-facing deployments. The raw @telnyx/webrtc SDK (v2.14.5) is for custom implementations only. For React apps use @telnyx/ai-agent-lib.

source: Telnyx SDK documentation


axiom: Agent handoff in unified mode is invisible to the caller — use this for specialist routing (e.g., billing questions transferred to billing assistant). Use distinct mode ONLY when you want the caller to know they are being transferred.

source: Telnyx multi-agent handoff documentation


axiom: Dynamic variables webhook has a 1-second timeout — if your CRM lookup takes longer, the call proceeds without the data. Design dynamic variable endpoints to be FAST (cache frequently, pre-compute where possible). Use tools for complex lookups that can happen during the conversation.

source: Telnyx memory documentation


axiom: Call recordings stored in Telnyx-owned S3 have download links that expire in 10 minutes. For production: configure custom storage (own S3/GCS/Azure) via /v2/custom_storage_credentials/{app_id} to retain permanent access to recordings.

category: recordings

source: Telnyx recording storage documentation


axiom: Use insight_group_id on ALL assistants to group conversation analytics. Set use_insights_for_memory:true for persistent cross-call memory. Configure insight webhooks for real-time post-call analytics delivery to your CRM.

category: insights

source: Telnyx AI Insights documentation


axiom: Telnyx supports canary deployments — create a new version of an assistant, route 10% of traffic to it, monitor insights, then scale to 100% or rollback. NEVER update production assistants directly — always use versioning.

category: deployment

source: Telnyx versioning and canary documentation


axiom: For SubAIVA customer onboarding: the repeatable pattern is (1) create assistant via API, (2) assign number from pre-provisioned pool, (3) configure webhook to customer GHL location, (4) deploy widget embed code, (5) verify telephony enabled. Steps 1-4 are fully automated via API.

source: Customer provisioning workflow analysis


axiom: Telnyx has an official MCP server (TypeScript, github.com/team-telnyx/telnyx-node) that exposes ALL Telnyx operations to Claude Desktop / Cursor. Install it locally for rapid Telnyx management without writing custom API calls.

category: tooling

source: Official Telnyx MCP server repo


axiom: The Telnyx AI Assistant API supports scheduled events — use this for automated follow-up calls and SMS reminders. This eliminates the need for external scheduling infrastructure (n8n cron jobs) for simple time-based outreach.

category: automation

source: Telnyx scheduled events API documentation


axiom: Noise suppression 'krisp' should be enabled for all tradie/trade customer assistants — callers from job sites have heavy background noise. Disable it for office-based receptionists where audio quality is already clean.

source: Live call quality analysis


axiom: VAPI is permanently eliminated from Genesis stack. Telnyx Direct provides 65-70% cost savings ($0.025-0.035/min vs $0.10-0.12/min). NEVER reference or use VAPI in any Genesis work.

source: VAPI elimination decision 2026-02-15


axiom: For vision-capable AI receptionist use cases (photo assessment, document verification), use MMS + vision-capable model (Groq/llama-4-maverick-17b or openai/gpt-4o). The widget supports image uploads during voice calls.

category: multimodal

source: Telnyx vision capability documentation

severity: low


axiom: Telnyx Cloud Storage is S3-compatible with unlimited free buckets. Use it for call recordings, knowledge base files, and CDN for demo assets instead of paying for external S3/Cloudfront.

source: Telnyx Cloud Storage documentation


axiom: The Genesis Voice Bridge MCP server exposes 13 tools to Telnyx AI assistants: project status, war room, memory search (Supermemory + Qdrant), knowledge graph (FalkorDB), decisions, agents, architecture, revenue, session progress. This is our competitive moat — no other voice agent platform has this depth of memory integration.

source: Genesis Voice Bridge server.py analysis


axiom: Australian DID number regulatory docs require: (1) business name + ABN, (2) contact person name + phone, (3) passport/government ID copy, (4) Australian address proof within 3 months. Processing takes ~72 hours. Prepare all docs BEFORE ordering to avoid delays.

source: Telnyx AU DID requirements


axiom: Telnyx media streaming over WebSocket enables real-time audio processing — use fork_start for secondary audio processing (sentiment analysis, fraud detection, real-time transcription audit). This is the foundation for advanced voice analytics features in future SubAIVA tiers.

source: Telnyx media streaming documentation


axiom: The send_message tool on AI assistants allows sending SMS from verified numbers during or after voice calls — use this for sending confirmation texts, appointment details, or follow-up links without leaving the voice conversation flow.

category: omnichannel

source: Telnyx AI messaging documentation


axiom: For production SubAIVA deployments: use JWT token exchange (backend generates telephony_credential) instead of anonymous login. This prevents API key exposure, enables usage tracking per customer, rate limiting, and parameter isolation. Anonymous login is for demos only.

category: security

source: Telnyx dual-track architecture documentation