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

# ElevenLabs voice-agent KB

> Connect a workspace-specific ElevenLabs conversational-AI agent to your Switchbord knowledge base.

Switchbord can mirror your workspace knowledge base into an ElevenLabs
conversational-AI agent so voice calls answer from the same facts Margaret
sees in chat. This doc covers the one-time setup, the sync flow, and the
operational controls.

## What gets synced

Every row in `workspace_knowledge_entries` whose `tags` array contains **`kb`**
or **`memory`** is a candidate. That is:

* The curated FAQ/doc/policy entries operators write via the Knowledge Base UI
  (`kb`).
* Long-term notes Margaret has saved via the `writeWorkspaceMemory` tool
  (`memory`).

Each entry is pushed to the configured ElevenLabs agent's knowledge base. The
remote document ID is persisted on `workspace_knowledge_entries.elevenlabs_document_id`
so repeat syncs are idempotent — new rows are created, existing rows are
updated in place.

## Setup

1. **Get an ElevenLabs API key** from
   [elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys).
2. **Create (or pick) a conversational-AI agent** at
   [elevenlabs.io/app/conversational-ai](https://elevenlabs.io/app/conversational-ai).
   Copy its agent ID (format: `agent_...`).
3. In Switchbord, go to **Settings → Integrations → AI → Voice (ElevenLabs)**.
4. Paste the API key (stored per-workspace in the Supabase Vault) and the
   agent ID (stored in `workspaces.elevenlabs_agent_id`).
5. Click **Test connection** — this calls
   `GET /v1/convai/agents/{agent_id}` with your key and reports the agent
   name on success.

## Sync flow

### From the settings UI

The same page has a **Knowledge-base sync** card with two buttons:

* **Plan (dry run)** — reads the workspace KB and reports which entries
  would be created vs. updated, without touching ElevenLabs.
* **Sync now** — reads the API key from the vault, then POSTs (or PATCHes)
  every candidate entry to the ElevenLabs agent's KB.

### From Margaret

Operators with the **admin** role can ask Margaret:

> "Push our KB to the ElevenLabs agent."

Margaret calls the `syncElevenLabsKnowledge` tool. The default is a dry run
that reports the plan in chat. Setting `dryRun: false` surfaces a HITL
approval card in the ToolApprovalCard pattern — once approved, Margaret
makes the live push.

### From the API

```bash theme={null}
curl -X POST https://app.switchbord.io/api/elevenlabs/kb/sync \
  -H "Content-Type: application/json" \
  --data '{"dryRun": false}' \
  --cookie "..."
```

Response shape:

```json theme={null}
{
  "dryRun": false,
  "agentId": "agent_abc",
  "candidates": 12,
  "succeeded": 12,
  "failed": 0,
  "actions": [
    { "entryId": "…", "title": "Orari di apertura", "verb": "create", "ok": true, "documentId": "doc_…" }
  ]
}
```

## Security

* API key lives in the per-workspace Supabase Vault (secret kind
  `elevenlabs-api-key`). Only the masked hint is returned to the UI.
* Agent ID is plaintext on `public.workspaces` — not a secret.
* Sync + settings endpoints require `requireSettingsAccess` (owner/admin
  role). The Margaret `syncElevenLabsKnowledge` tool additionally requires
  the admin tool-access role and a HITL approval before a live push.

## Known limitations (ship 1)

* ElevenLabs KB document payload shape may evolve. The sync route defaults
  to `dryRun: true` so operators can preview before hitting the remote API.
* No delete path yet — removing a row in Switchbord does not remove the
  document from ElevenLabs. Track via
  [BORD-TBD](https://linear.app/gbvai/issue/BORD-322).
* Test-connection currently hits `GET /v1/convai/agents/{agent_id}`. If
  ElevenLabs changes their error codes the UI surfaces the raw HTTP status.