---
title: "Create Voice Agent Group"
method: POST
path: "/api/v1/voice-ai/voice-agent-groups"
tags: ["voice_agent_groups"]
---

# Create Voice Agent Group

`POST /api/v1/voice-ai/voice-agent-groups`

Create a new voice agent group with an auto-created first agent.

## Request body

- VoiceAgentGroupCreate
  - `name` string, required
  - `entries` VoiceAgentGroupEntry[]
    - `label` string, required — Label for the transfer target. Max 39 chars because it's prefixed with 'transfer_to_voice_agent__' (25 chars) for a 64-char platform limit.
    - `description` string, nullable
    - `voice_agent_id` string, uuid, required
    - `transfer_config` VoiceTransferScenarioConfig — Operator-configurable transfer behavior for a voice agent entry. Lives on the TARGET entry — the Reservations entry defines how other agents transfer TO Reservations, regardless of which source agent initiates.
      - `condition` string, nullable
      - `pre_instruction` string, nullable
      - `post_instruction` string, nullable
      - `transfer_announcement` 'silent' | 'announced'
      - `speak_first_message_on_transfer` boolean
      - `languages` string[]
  - `enabled` boolean
  - `direction` 'inbound' | 'outbound' — Whether the group handles inbound calls or outbound calls.

## Response `201`

Successful Response

- VoiceAgentGroupRead
  - `id` string, uuid, required
  - `pre_pickup_enabled` boolean
  - `pre_pickup_mode` 'audio' | 'text' | 'synthesized' — How a group's pre-pickup message is sourced before the AI picks up. - AUDIO: play the operator-uploaded file at ``pre_pickup_audio_object_key``. - TEXT: synthesize ``pre_pickup_text`` live with the group's TTS voice at call time. - SYNTHESIZED: a message pre-rendered from ``pre_pickup_text`` with an operator-chosen provider/voice/language (the "recipe" columns), stored to the same audio slot as AUDIO and played identically by the worker. Enum grows, never renames.
  - `pre_pickup_text` string, nullable
  - `pre_pickup_voice_provider` 'elevenlabs' | 'cartesia' — TTS provider used to synthesize a SYNTHESIZED pre-pickup message. Stored on ``VoiceAgentGroup.pre_pickup_voice_provider`` (as a plain string column) and used to dispatch synthesis to the matching TTS client.
  - `pre_pickup_voice_id` string, nullable
  - `pre_pickup_language` string, nullable
  - `pre_pickup_variants` VoicePrePickupVariant[]
    - `language` string, required
    - `text` string, required
    - `voice_provider` 'elevenlabs' | 'cartesia', required — TTS provider used to synthesize a SYNTHESIZED pre-pickup message. Stored on ``VoiceAgentGroup.pre_pickup_voice_provider`` (as a plain string column) and used to dispatch synthesis to the matching TTS client.
    - `voice_id` string, required
    - `audio_object_key` string, nullable
    - `audio_filename` string, nullable
    - `dtmf_digit` string, nullable
    - `greeting` string, nullable
  - `pre_pickup_menu_grace_seconds` number, nullable
  - `name` string, required
  - `entries` VoiceAgentGroupEntry[]
    - `label` string, required — Label for the transfer target. Max 39 chars because it's prefixed with 'transfer_to_voice_agent__' (25 chars) for a 64-char platform limit.
    - `description` string, nullable
    - `voice_agent_id` string, uuid, required
    - `transfer_config` VoiceTransferScenarioConfig — Operator-configurable transfer behavior for a voice agent entry. Lives on the TARGET entry — the Reservations entry defines how other agents transfer TO Reservations, regardless of which source agent initiates.
      - `condition` string, nullable
      - `pre_instruction` string, nullable
      - `post_instruction` string, nullable
      - `transfer_announcement` 'silent' | 'announced'
      - `speak_first_message_on_transfer` boolean
      - `languages` string[]
  - `enabled` boolean
  - `direction` 'inbound' | 'outbound' — Whether the group handles inbound calls or outbound calls.
  - `tenant_id` string, uuid, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `pre_pickup_audio_filename` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/getanana/apis/cleon-api.md) · [All operations](https://skmtc.dev/getanana/apis/cleon-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getanana/cleon-api/revisions/fbb95eac3965/schema)