---
name: voice-ai-agent
description: Use when creating, configuring, testing or connecting a Telnyx AI Assistant to phone calls for support, scheduling or IVR automation. Start here for the end-to-end workflow; choose a telnyx-ai-assistants SDK skill for language-specific API examples.
version: "1.1.0"
author: Telnyx
type: skill-md
---

# Voice AI Agent

Build a hosted assistant with instructions, speech recognition, speech synthesis and tools. For direct model completions without an assistant, use the [inference skill](https://telnyx.com/.well-known/agent-skills/edge-inference/SKILL.md).

## Before starting

- Use a Telnyx API key from the user's approved secret source. Keep it on a trusted server; do not embed it in browser code or logs.
- Assistant creation and WebSocket testing do not require a phone number. AI processing is billable; PSTN calls also incur telephony and number rental charges.
- Use an existing owned number when phone calls are requested. Confirm purchase scope and cost before ordering a new number.
- The Bash examples require `curl` and `jq`. Save resource IDs as each step succeeds. After an ambiguous timeout, reconcile existing resources before repeating a create or purchase.

## Create an assistant using current defaults

```bash
set -euo pipefail
assistant=$(curl --fail-with-body --max-time 30 -sS \
  https://api.telnyx.com/v2/ai/assistants \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "customer-support-agent",
    "instructions": "You are a helpful support assistant. Be concise and ask before taking actions on the customer account.",
    "greeting": "Hello! How can I help?"
  }')
ASSISTANT_ID=$(jq -er '(.data // .).id | select(type == "string" and length > 0)' <<< "$assistant")
printf 'Assistant ID: %s\n' "$ASSISTANT_ID"
```

The payload intentionally omits `model`, `voice_settings` and `transcription` so the API selects its current model, TTS and STT defaults. Inspect the returned values before choosing explicit settings. An inference model or standalone speech voice is not necessarily supported by assistants.

Creation can return a top-level assistant object; accept a `data` wrapper too. List responses use `data`. Update an assistant with `POST /v2/ai/assistants/{assistant_id}`, using the current schema rather than invented `system_prompt`, `llm_settings` or `stt_settings` fields.

For new tool integrations, create shared tools and attach `tool_ids`; inline `tools` are deprecated for new integrations. Use the current [assistant API contract](https://github.com/team-telnyx/ai/blob/main/skills/telnyx-ai-assistants-curl/references/api-details.md) for tools, knowledge retrieval and supported settings.

## Test before adding telephony

Use `wss://api.telnyx.com/v2/ai/assistants/{assistant_id}/conversation` and the [realtime conversation guide](https://developers.telnyx.com/docs/inference/ai-assistants/realtime-conversations) for authentication, PCM16 audio, sample rates and lifecycle events. A successful create response alone does not verify a conversation.

## Connect an owned phone number

Use the phone number resource ID, not its E.164 value or a number-order ID. Retrieve the assistant's default TeXML app and check its route before assigning the number:

```bash
set -euo pipefail
ASSISTANT_ID="YOUR_ASSISTANT_ID"
PHONE_NUMBER_ID="YOUR_PHONE_NUMBER_RESOURCE_ID"
BASE_URL="https://api.telnyx.com/v2"

assistant=$(curl --fail-with-body --max-time 30 -sS "$BASE_URL/ai/assistants/$ASSISTANT_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY")
app_id=$(jq -er '(.data // .).telephony_settings.default_texml_app_id | select(type == "string" and length > 0)' <<< "$assistant")
curl --fail-with-body --max-time 30 -sS "$BASE_URL/texml_applications/$app_id" \
  -H "Authorization: Bearer $TELNYX_API_KEY" | \
  jq -e --arg app "$app_id" --arg url "$BASE_URL/ai/assistants/$ASSISTANT_ID/texml" \
    '(.data // .) | .id == $app and .active == true and .voice_url == $url and (.voice_method | ascii_upcase) == "GET"' >/dev/null

# Stop if another connection owns the number; reconcile before changing it.
curl --fail-with-body --max-time 30 -sS "$BASE_URL/phone_numbers/$PHONE_NUMBER_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY" | \
  jq -e --arg id "$PHONE_NUMBER_ID" --arg app "$app_id" \
    '(.data // .) | .id == $id and ((.connection_id // "") == "" or .connection_id == $app)' >/dev/null
curl --fail-with-body --max-time 30 -sS -X PATCH "$BASE_URL/phone_numbers/$PHONE_NUMBER_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --arg app "$app_id" '{connection_id: $app}')" | \
  jq -e --arg id "$PHONE_NUMBER_ID" --arg app "$app_id" \
    '(.data // .) | .id == $id and .connection_id == $app'
```

These checks and the assignment are not atomic with other writers. If the default app is absent or its route fails validation, inspect the configuration rather than creating or overwriting resources blindly. Place a real authorized test call after assignment; a matching connection ID does not prove that the assistant answers.

## Configuration, troubleshooting and cleanup

- Use the [speech skill](https://telnyx.com/.well-known/agent-skills/stt-tts/SKILL.md) when selecting assistant `voice_settings` or `transcription` overrides. Keep defaults for a basic setup.
- For a model validation error, use the assistant default or select a supported model; do not guess a replacement model ID. The [Models API instructions](https://telnyx.com/ai/inference-models.md) cover live inference discovery.
- For calls that do not answer, recheck the owned number's `connection_id`, the TeXML app's active state and GET voice route, and the account's calling permissions/balance.
- Stop retrying spending-limit errors and inspect the existing [inference spending limits](https://developers.telnyx.com/docs/inference/spending-limits). Those limits do not cover every voice/telephony charge.
- Measure audio and tool behavior in the actual workload; this skill makes no fixed latency guarantee.
- Delete only resources created for the test and authorized for cleanup. Removing an assistant does not release a rented number.

See [current Voice AI pricing](https://telnyx.com/pricing/voice-ai-agents): the voice-engine subtotal and included hosted speech are distinct from LLM tokens, telephony, number rental and optional add-ons.
