> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpgenie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Preselected voices

> Platform-curated voice options available to all users when setting up a genie

Preselected voices are the platform-level voice options shown to users during genie setup. Regular users can browse all active voices; creating, updating, and deleting entries is restricted to admins.

***

## Actions

### `all`

Returns all preselected voices, ordered by `sort_order`. Regular users see only active voices (`is_active: true`). Admins see all voices regardless of active status.

**Response**

```json theme={null}
{
  "voices": [
    {
      "id": "voice-uuid",
      "voice_id": "external-voice-id",
      "label": "Rachel",
      "description": "Warm, professional female voice",
      "gender": "female",
      "sort_order": 0,
      "is_active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "count": 12
}
```

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "preselected-voices",
    action: "all",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/preselected-voices \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "preselected-voices",
      "action": "all"
    }'
  ```
</CodeGroup>

***

### `create`

Adds a new preselected voice to the platform library. **Admin only.**

<ParamField body="voice_id" type="string" required>
  Platform voice identifier to add to the curated list.
</ParamField>

<ParamField body="label" type="string" required>
  Display name shown to users.
</ParamField>

<ParamField body="description" type="string">
  Optional description of the voice character or style.
</ParamField>

<ParamField body="gender" type="string" required>
  Must be `"male"` or `"female"`.
</ParamField>

<ParamField body="sort_order" type="number" default="0">
  Display order position.
</ParamField>

<ParamField body="is_active" type="boolean" default="true">
  Whether the voice is visible to regular users.
</ParamField>

**Response** — `201`

```json theme={null}
{
  "voice": {
    "id": "voice-uuid",
    "voice_id": "external-voice-id",
    "label": "Rachel",
    "description": "Warm, professional female voice",
    "gender": "female",
    "sort_order": 0,
    "is_active": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": null
  }
}
```

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "preselected-voices",
    action: "create",
    data: {
      voice_id: "external-voice-id",
      label: "Rachel",
      description: "Warm, professional female voice",
      gender: "female",
      sort_order: 1,
      is_active: true,
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/preselected-voices \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "preselected-voices",
      "action": "create",
      "data": {
        "voice_id": "external-voice-id",
        "label": "Rachel",
        "description": "Warm, professional female voice",
        "gender": "female",
        "sort_order": 1,
        "is_active": true
      }
    }'
  ```
</CodeGroup>

***

### `update`

Updates a preselected voice entry. **Admin only.** Only the fields you supply are changed.

Pass the voice UUID as the request `id`. All data fields below are optional.

<ParamField body="label" type="string">
  Updated display name.
</ParamField>

<ParamField body="description" type="string">
  Updated description.
</ParamField>

<ParamField body="gender" type="string">
  Updated gender. Must be `"male"` or `"female"`.
</ParamField>

<ParamField body="sort_order" type="number">
  Updated display order position.
</ParamField>

<ParamField body="is_active" type="boolean">
  Toggle visibility for regular users.
</ParamField>

**Response**

```json theme={null}
{
  "voice": { /* updated preselected voice object */ }
}
```

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "preselected-voices",
    action: "update",
    id: "voice-uuid",
    data: {
      label: "Rachel (Updated)",
      is_active: false,
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/preselected-voices \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "preselected-voices",
      "action": "update",
      "id": "voice-uuid",
      "data": {
        "label": "Rachel (Updated)",
        "is_active": false
      }
    }'
  ```
</CodeGroup>

***

### `delete`

Permanently removes a preselected voice from the platform library. **Admin only.** Irreversible.

**Parameters**

| Field | Type   | Required | Description                                   |
| ----- | ------ | -------- | --------------------------------------------- |
| `id`  | string | Yes      | Preselected voice UUID (passed as request ID) |

**Response**

```json theme={null}
{ "success": true, "message": "Preselected voice deleted successfully" }
```

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "preselected-voices",
    action: "delete",
    id: "voice-uuid",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/preselected-voices \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "preselected-voices",
      "action": "delete",
      "id": "voice-uuid"
    }'
  ```
</CodeGroup>

***

## Voice object fields

| Field         | Type                   | Description                                   |
| ------------- | ---------------------- | --------------------------------------------- |
| `id`          | string                 | Unique preselected voice identifier           |
| `voice_id`    | string                 | External voice identifier                     |
| `label`       | string                 | Display name shown to users                   |
| `description` | string \| null         | Optional description                          |
| `gender`      | `"male"` \| `"female"` | Voice gender                                  |
| `sort_order`  | number                 | Display order position                        |
| `is_active`   | boolean                | Whether the voice is visible to regular users |
| `created_at`  | string \| null         | ISO 8601 creation timestamp                   |
| `updated_at`  | string \| null         | ISO 8601 last-updated timestamp               |

***

## Error codes

| Code               | Meaning                               |
| ------------------ | ------------------------------------- |
| `VALIDATION_ERROR` | Missing or invalid required parameter |
| `NOT_FOUND`        | Preselected voice not found           |
| `FORBIDDEN`        | Admin access required                 |
| `INTERNAL_ERROR`   | Unexpected server error               |