Voice agents, from business case to production. With the code.

# one goal, one metric, read from the call logindustry: Healthcaregoal: Reduce no showsmetric: no_show_ratebaseline: 18%target: 11%window: 90 daysowner: ops_leadnot_optimizing_for: [handle_time, csat]   # yet

# scope.md  (this becomes v1 of the instructions)## Supported intents- reschedule_appointment- confirm_appointment- cancel_appointment- clinic_hours_and_directions## Refused- clinical advice- billing disputes- anything about another patient## Escalation ruleTransfer to the front desk queue after one clarifying question.## Done whenno_show_rate moves from 18% toward 11% in 90 days

curl -X POST https://api.telnyx.com/v2/ai/assistants \  -H "Authorization: Bearer $TELNYX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "Front Desk",    "model": "moonshotai/Kimi-K2.6",    "instructions": "You book, confirm and reschedule patient appointments for Riverside Family Clinic. The caller is {{full_name}}. Never confirm an action before the tool returns. Ask one clarifying question, then transfer.",    "greeting": "Thanks for calling Riverside Family Clinic. This call may be recorded. How can I help?",    "voice_settings": { "voice": "Telnyx.KokoroTTS.af_heart" },    "transcription": { "model": "deepgram/flux" },    "telephony_settings": { "noise_suppression": "krisp" },    "dynamic_variables": { "full_name": "there" }  }'

curl -X POST https://api.telnyx.com/v2/texml/ai_calls/{connection_id} \  -H "Authorization: Bearer $TELNYX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "From": "+13125550100",    "To": "+13125550123",    "AIAssistantId": "{assistant_id}",    "AIAssistantDynamicVariables": {      "full_name": "Maria Alves",      "location": "Riverside Family Clinic",      "department": "Primary Care"    }  }'# the instructions reference them as {{full_name}}, {{location}}, {{department}}# inbound: send X-Full-Name as a SIP header, or answer the dynamic variables webhook

"tools": [  {    "type": "webhook",    "webhook": {      "name": "book_appointment",      "description": "Book a confirmed appointment slot for a verified patient",      "url": "https://api.riversideclinic.example/v1/appointments",      "method": "POST",      "timeout_ms": 3000,      "headers": [{ "name": "Authorization", "value": "Bearer YOUR_TOOL_TOKEN" }],      "body_parameters": {        "type": "object",        "properties": {          "patient_id": { "type": "string" },          "slot_id": { "type": "string" },          "idempotency_key": { "type": "string" }        },        "required": ["patient_id", "slot_id", "idempotency_key"]      }    }  },  {    "type": "transfer",    "transfer": {      "from": "+13125550100",      "targets": [{ "name": "Front desk", "to": "+13125550199" }]    }  }]# error taxonomy, each mapped to a spoken response in the instructions# NO_AVAILABILITY       offer the next two slots# PATIENT_NOT_FOUND     verify date of birth once, then transfer# EHR_TIMEOUT           retry once, then offer a callback

# conversation test: a scripted caller, scored against a rubriccurl -X POST https://api.telnyx.com/v2/ai/assistants/tests \  -H "Authorization: Bearer $TELNYX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "Front Desk happy path",    "destination": "+13125550100",    "telnyx_conversation_channel": "phone_call",    "instructions": "Caller wants to move a Tuesday appointment to Thursday afternoon.",    "rubric": [      { "name": "Tool first", "criteria": "Never confirms a booking before book_appointment returns" },      { "name": "Refusal", "criteria": "Declines clinical questions and offers a transfer" }    ],    "max_duration_seconds": 180  }'# run it against a new version before you promote that versioncurl -X POST https://api.telnyx.com/v2/ai/assistants/tests/{test_id}/runs \  -H "Authorization: Bearer $TELNYX_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "destination_version_id": "{version_id}" }'

# save new instructions as a version, without promoting itcurl -X POST https://api.telnyx.com/v2/ai/assistants/{assistant_id} \  -H "Authorization: Bearer $TELNYX_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "instructions": "<v2 instructions for Front Desk>", "promote_to_main": false }'# send 10% of calls to the new version; the rest stay on maincurl -X POST https://api.telnyx.com/v2/ai/assistants/{assistant_id}/canary-deploys \  -H "Authorization: Bearer $TELNYX_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "rules": [ { "serve": { "rollout": [ { "version_id": "{version_id}", "weight": 10 } ] } } ] }'# numbers hold for a week: promote. Otherwise delete the canary deploy.curl -X POST https://api.telnyx.com/v2/ai/assistants/{assistant_id}/versions/{version_id}/promote \  -H "Authorization: Bearer $TELNYX_API_KEY"

# stream conversation events to your monitoring, trace every turn in Langfusecurl -X POST https://api.telnyx.com/v2/ai/assistants/{assistant_id} \  -H "Authorization: Bearer $TELNYX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "websocket_settings": {      "enabled": true,      "url": "wss://events.riversideclinic.example/telnyx",      "auth_ref": "events_token"    },    "observability_settings": {      "status": "enabled",      "host": "https://cloud.langfuse.com",      "public_key_ref": "langfuse_public_key",      "secret_key_ref": "langfuse_secret_key"    }  }'# thresholds live in your own alerting, for example:#   p95 turn latency  > 1000 ms     page#   transfer rate     > 35%         review#   no_show_rate     weekly business review

# 1. define the fields to extract from every conversationcurl -X POST https://api.telnyx.com/v2/ai/conversations/insights \  -H "Authorization: Bearer $TELNYX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "no_show_drivers",    "instructions": "Extract the fields below from the conversation.",    "json_schema": {      "type": "object",      "properties": {        "reschedule_reason": { "type": "string" },        "new_slot_offered": { "type": "boolean" },        "transferred": { "type": "boolean" },        "transfer_reason": { "type": "string" }      }    }  }'# 2. group insights and deliver results to your webhookcurl -X POST https://api.telnyx.com/v2/ai/conversations/insight-groups \  -H "Authorization: Bearer $TELNYX_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "weekly_review", "webhook": "https://api.riversideclinic.example/telnyx/insights" }'# 3. assign the insight to the group, then set it on the assistant:#    "insight_settings": { "insight_group_id": "{group_id}" }curl -X POST https://api.telnyx.com/v2/ai/conversations/insight-groups/{group_id}/insights/{insight_id}/assign \  -H "Authorization: Bearer $TELNYX_API_KEY"

# the second agent starts from the firstcurl -X POST https://api.telnyx.com/v2/ai/assistants/{assistant_id}/clone \  -H "Authorization: Bearer $TELNYX_API_KEY"# rename it, then assign numbers: clones skip telephony and messaging settingscurl -X POST https://api.telnyx.com/v2/ai/assistants/{new_assistant_id} \  -H "Authorization: Bearer $TELNYX_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "Front Desk Dental" }'# already running on Vapi, ElevenLabs or Retell? import itcurl -X POST https://api.telnyx.com/v2/ai/assistants/import \  -H "Authorization: Bearer $TELNYX_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "provider": "vapi", "api_key_ref": "vapi_api_key" }'

# Telnyx skills for your coding agentnpx skills add team-telnyx/ai --skill <SKILL> --agent <AGENT># or, in Claude Code, the Telnyx plugin/plugin marketplace add team-telnyx/ai/plugin install telnyx-ai@telnyx# remote MCP server, authenticated with your API keyhttps://api.telnyx.com/v2/mcpAuthorization: Bearer $TELNYX_API_KEY