---
title: "Create an AI phone agent"
method: POST
path: "/phone"
---

# Create an AI phone agent

`POST /phone`

Create an AI phone agent powered by the latest voice model. Use GET /phone/voices to browse available voices. Only name is required — everything else has sensible defaults.

## Request body

- CreatePhoneAgentPublicDto
  - `name` string, required — Agent display name
  - `type` 'inbound' | 'outbound' — Agent type: "inbound" (receives calls, default) or "outbound" (makes calls)
  - `voice_id` string, nullable — Voice ID from the /phone/voices endpoint. Omit for default voice.
  - `language` string[] — ISO-639-1 language codes the agent should speak. A subset of {en, es, fr, de, hi, ru, pt, ja, it, nl} can be combined freely. Any other code (e.g. "ar", "tr", "zh") must be the only entry.
  - `first_message` string, nullable — What the agent says when it picks up (default: "Hello?")
  - `instructions` string[], nullable — Training scenario IDs to attach to this agent
  - `handoff_phone_number` string, nullable — Phone number to transfer to when handing off to a human (E.164 format)
  - `use_org_knowledgebase` boolean, nullable — Whether the agent can search your knowledge base during calls (default: false)
  - `actionIds` string[], nullable — Action IDs the agent can call during conversations

## Response `200`

Default Response

- PhoneAgentDto
  - `id` string, required
  - `org_id` string, required
  - `phone_number` string, nullable, required
  - `name` string, nullable, required
  - `type` 'inbound' | 'outbound', required
  - `language` string[], required
  - `accent` string, nullable, required
  - `handoff_phone_number` string, nullable, required
  - `speed` number, nullable, required
  - `interruptible` boolean, required
  - `actionIds` string[], nullable, required
  - `instructions` string[], nullable, required
  - `data_collection_fields` string[], nullable, required
  - `data_collection_webhook_url` string, nullable, required
  - `model` 'oppie-vox' | 'oppie-vox-turbo' | 'oppie-vox-2' | 'oppie-vox-livekit', required
  - `voice_id` string, nullable, required
  - `first_message` string, nullable, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `provider_external_id` string, nullable, required
  - `flow` unknown, required
  - `custom_llm` string, nullable, required
  - `use_org_knowledgebase` boolean, required
  - `background_noise_preset` 'office' | 'bar' | 'city-street', nullable, required
  - `recording_enabled` boolean, required
  - `stt_keyterms` string[], required
  - `stt_model` 'deepgram/flux-general' | 'deepgram/nova-3' | 'deepgram/nova-3-medical' | 'cartesia/ink-whisper' | 'elevenlabs/scribe_v2_realtime' | 'xai/stt-1' | 'assemblyai/universal-3-5-pro' | 'speechmatics/enhanced', nullable, required
  - `tts_speed_pct` integer, nullable, required
  - `failover_transfer_destination_id` string, uuid, nullable, required

## Other responses

- `500` — Internal Server Error

---

[API](https://skmtc.net/open/apis/opencx-api.md) · [All operations](https://skmtc.net/open/apis/opencx-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/open/opencx-api/versions/57b06b52302d/schema)