# iblai-api-agent-voice

> Mirrored from [`iblai/vibe`](https://github.com/iblai/vibe) · [`skills/agents/iblai-api-agent-voice/SKILL.md`](https://github.com/iblai/vibe/blob/main/skills/agents/iblai-api-agent-voice/SKILL.md). This page is generated — edit it in the repository, not here.

> **With a screen:** `/iblai-vibe-agent-voice` (Voice tab) and
> `/iblai-vibe-agent-screenshare` (Screen tab) mount the same data — this
> skill is their headless twin.

Configure how an agent speaks and listens. **Scope: per agent** — every field
here applies to every user of the agent. Two resources hold it:

- **Agent settings** (`…/mentors/{mentor}/settings/`): the chat voice
  (`voice_provider` + `openai_voice` / `google_voice` / `iblai_voice`),
  `voice_instructions`, `transcription_language`,
  `transcription_instructions`, and the `show_voice_call` /
  `show_voice_record` switches.
- **Call configuration** (`…/call-configurations/`, one row per agent): call
  style, language, AI provider, call voice, and screen sharing
  (`enable_video` + two prompts).

Endpoints verified against the live schema
(`https://api.iblai.app/dm/api/docs/schema/`, version 4.411.0) on 2026-10-02.

## Auth & conventions

- **Base URL:** `https://api.iblai.app`
- **Header:** `Authorization: Api-Token $IBLAI_API_KEY` on every request.
- **Path vars:** `{org}` = `$IBLAI_ORG`, `{username}` = `$IBLAI_USERNAME`,
  `{mentor}` = the agent's unique id.
- **Prefix:** every path below starts with
  `https://api.iblai.app/dm/api/ai-mentor/orgs/{org}/users/{username}` (written `…`).
- Call configurations are admin-only (organization admins).
- Not connected yet? Run **`/iblai-api-login`** first to populate `IBLAI_ORG`,
  `IBLAI_USERNAME`, and `IBLAI_API_KEY`.

## Reads

- **GET** `…/mentors/{mentor}/settings/` — current voice fields. The response
  also embeds the agent's `call_configuration` object, never `null`: its `id`
  is `null` until a POST creates the row, so POST first. Voice fields come
  back as voice **names** (e.g. `"alloy"`), not ids.
- **GET** `…/voices/` — the voice catalog. Query: `provider`
  (`browser | openai | google | iblai | elevenlabs`), `search`, `page`,
  `page_size`, `ordering`. Each voice: `{ id, name, provider, language,
  description, audio_url }` (`audio_url` is a playable sample).
- **GET** `…/voices/{id}/` — one voice.
- **GET** `…/call-configurations/?mentor={mentor}` — the agent's call
  configuration (an array; use the first item). Also filters by `mode`,
  `search`, `ordering`.
- **GET** `…/call-configurations/{id}/` — one call configuration.

## Writes

- **PUT** `…/mentors/{mentor}/settings/` — voice fields
  (`multipart/form-data`; send only the changed keys, as in
  `/iblai-api-agent-setting`):
  ```json
  {
    "voice_provider": "browser | openai | google | iblai",
    "openai_voice": "number (voice id from /voices/?provider=openai)",
    "google_voice": "number (voice id)",
    "iblai_voice": "number (voice id; cannot be cleared: \"\" is a 400, 0 or an empty value changes nothing)",
    "voice_instructions": "string (tone, pace, emotion; \"\" clears)",
    "transcription_language": "string (ISO 639-1, e.g. \"es\"; \"\" = auto-detect)",
    "transcription_instructions": "string (jargon, names; \"\" clears)",
    "show_voice_call": "boolean (voice calls on/off)",
    "show_voice_record": "boolean (dictation microphone on/off)"
  }
  ```
  `voice_provider` picks which `*_voice` field applies; `browser` uses the
  listener's device and no voice id. `voice_instructions` reaches OpenAI as
  speech `instructions` and Google as a synthesis `prompt`; other providers
  ignore it.
- **POST** `…/call-configurations/` — create the agent's call configuration
  (only when the GET returns none):
  ```json
  {
    "mentor": "uuid (required)",
    "mode": "realtime | inference",
    "language": "string (e.g. \"en\", max 10)",
    "llm_provider": "openai | google | azure_openai | iblai",
    "tts_provider": "openai | google | elevenlabs | azure_openai",
    "stt_provider": "openai | google | deepgram | cartesia | azure_openai",
    "openai_voice_id": "number | null",
    "google_voice_id": "number | null",
    "use_function_calling_for_rag": "boolean",
    "enable_video": "boolean (screen sharing; realtime mode only)",
    "screensharing_system_prompt": "string",
    "screensharing_proactive_prompt": "string"
  }
  ```
- **PATCH** `…/call-configurations/{id}/` — change any of the fields above
  (send only the changed keys).
- **PUT** `…/call-configurations/{id}/` — replace the row (send `mentor` too).

There is no DELETE for call configurations.

## Example

Turn screen sharing on and set the opener for an agent whose call
configuration already exists:

```bash
API="https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME"
ID=$(curl -s "$API/call-configurations/?mentor=$MENTOR" \
  -H "Authorization: Api-Token $IBLAI_API_KEY" | jq '.[0].id')
curl -X PATCH "$API/call-configurations/$ID/" \
  -H "Authorization: Api-Token $IBLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enable_video": true, "screensharing_proactive_prompt": "I can see your screen now. What would you like help with first?"}'
```

## Notes

- **Names out, ids in:** settings return voice names; writes take voice ids.
  Resolve a name with `GET …/voices/?provider=
&search=<name>`.
- **Absent = unchanged:** leaving a field out of the settings PUT keeps it.
  Clear `voice_instructions` / `transcription_instructions` with `""`, never
  `null`.
- **Screen sharing needs a live call:** `enable_video` only works in
  `realtime` mode, and only when `show_voice_call` is on.
- **Default screen prompt:** a new call configuration starts with the
  platform's screen-guidance text in `screensharing_system_prompt`.
- **Pricier OpenAI speech:** non-empty `voice_instructions` switches OpenAI
  synthesis to an instruction-capable model that costs more.