# Glyph: live voice

Talk with your agent out loud from any session, through your own Glyph account. The whole call lands in the session when you hang up.

Canonical page: https://themachine.myapps.ai/docs/connect/glyph

The Glyph channel lets you talk with your Machine agent live, by voice, the
way you'd phone a person. A **Live** button in every session opens a small
call window that floats over the chat. The voice speaks as your agent, knows
the session so far, and can use Glyph's own tools, such as web search and
images, while you talk. When you hang up, the whole transcript is posted into
the session, and the agent carries on from it.

The channel runs on your own [Glyph](https://glyph.myapps.ai) account. Glyph
provides the voice; Machine owns the agent. There's no switch to turn on: the
channel does nothing until you connect your own Glyph key.

Using Machine Desktop or the phone apps? See [Live](/docs/desktop/live). The
same Glyph key works there, and you can connect it from the desktop app too.

## What you need

- A Machine project you can edit connectors in.
- A Glyph account. Your Glyph plan decides which voices you get and how long
  you can talk.
- A **personal** Glyph API key. It starts with `glk_`. An organization key
  doesn't work.

## Set it up

### Create a Glyph API key

Sign in to [Glyph](https://glyph.myapps.ai), open **Settings → Developer
API**, and create a personal key. Copy it. Glyph's own
[quickstart](https://glyph.myapps.ai/docs#quickstart) shows the same steps.

Never paste the key into a chat with the agent. It belongs only in the
Settings form in the next step.

### Connect Glyph

Open the project's **Settings → Channels**. Glyph has its own card there,
marked **Your own account**. Click **Connect Glyph**, paste the key, and click
**Connect Glyph** again.

Machine checks the key with Glyph before saving it. The card then shows
**Connected** with the key's name in Glyph.

### Call from a session

Open any session in the project and click **Live** in the session header.
Allow the microphone when your browser asks. The call window shows
**Connecting…**, then **Listening**, and you can start talking.

## During a call

The call window floats over the chat, so you can keep reading and typing in
the session behind it. Drag it by its title bar to move it.

- **The title bar** shows who you're talking to and what's happening:
  **Listening**, **Speaking**, **You're talking**, or **Muted**.
- **The orb** in the middle pulses with the agent's voice. While the agent is
  talking, tap it to stop it and say something else.
- **The caption** shows what the agent is saying, with your last line below
  it.
- **Glyph's tools** show up as they work: the tool's name, what it's doing or
  found, and any images it made. Click an image to open it.
- **Mute** turns your microphone off and on. A ring around it swells as you
  speak, so you can see the microphone hears you.
- **Hold to talk** appears when **Talking** is set to **Hold to talk** (see
  [Live call settings](#live-call-settings)). Hold it, or hold Space or Enter
  on it, while you speak.
- **Minimize** shrinks the window to its title bar and controls. Click it
  again to expand it.
- **End call** (or the **×** in the title bar) hangs up.

The voice speaks as the session's agent, using the agent's own name. The
built-in default agent speaks as **Machine**. It knows the last part of the
session, so you can say _"what did you just change?"_ or _"walk me through
that plan"_.

The voice can't touch the session's files or connected apps during the call.
For work like that, it confirms what you want and the agent does it in the
session after you hang up.

## After the call

When you hang up, Machine posts the call into the session as one message,
headed with the agent's name and the call's length, for example _Live call
with Machine · 4 min_. The session shows it as a call card: each line that was
said, Glyph's tool results set apart, and the images those tools made.

The agent reads the transcript like any message and does what you asked for
during the call. That work uses your Machine credits, like a typed message.

A second call in the same session continues the first one on Glyph's side, so
the voice remembers what you talked about. If you close the page during a
call, the call ends and what was said is still posted.

## Live call settings

Click **Manage** on the Glyph card. Under **Live calls**, each change saves at
once and applies to every call in the project.

| Setting | Choices |
| :--- | :--- |
| **Voice** | **Glyph's default**, or a named voice from the **Live engine** or **Classic engine** list. Which voices work depends on the engine your Glyph plan uses. |
| **Language** | **Detect automatically**, or English, Spanish, French, German, Portuguese, Italian, Japanese, Hindi, Ukrainian, or Chinese. |
| **Talking** | **Hands-free**, or **Hold to talk**. |
| **When it answers** | **After a short pause**, or **When you've finished your thought**. |
| **Room** | **Quiet room or headphones**, **Normal**, or **Noisy room or laptop speakers**. Shown only with **After a short pause**. |
| **Pause before answering** | **Short — quick back-and-forth**, **Normal**, or **Long — I pause to think**. Shown only with **After a short pause**. |

**Hold to talk**, **When it answers**, **Room**, and **Pause before
answering** apply on Glyph's Classic engine. On laptop speakers, choose the
noisy room so the voice doesn't answer its own echo.

## No Glyph key yet?

If the project has no Glyph key, **Live** opens a short note instead of a
call: **Connect Glyph to talk live**. Click **Open Channels** to go to the
project's **Settings → Channels**, or **Not now** to close it.

## Your key

- Machine stores the key on its server. Your browser and the agent never see
  it. Each call gets a fresh, short-lived link to Glyph that Machine never
  stores.
- One Glyph key per project. **Manage → Replace key** swaps in a new one, and
  **Disconnect** removes it; **Live** then asks you to connect again.
- Revoking the key in Glyph cuts off every call at once. Live then says
  _"Glyph no longer accepts this bot's key. Reconnect Glyph in Channels."_
- Connecting, replacing, disconnecting, and changing settings need permission
  to edit the project's connectors. Anyone who can see a session can call
  from it; a private session stays private.

## Troubleshooting

| What you see | Fix |
| :--- | :--- |
| _"Glyph did not accept that key."_ | The key was copied incompletely or was revoked. Create a new one in Glyph. |
| _"Use a personal Glyph key ..., not an organization key."_ | Create a personal key under Glyph **Settings → Developer API**. |
| _"Your browser blocked the microphone."_ | Allow the microphone for this site in your browser, then click **Live** again. |
| _"Glyph's player isn't allowed on this site yet, so this call runs without Glyph's tools."_ | The call still works, but without web search, images, and Glyph's other tools. |
| The voice answers itself, or cuts you off | Set **Room** to **Noisy room or laptop speakers**, or use headphones. |
| The voice answers before you finish | Set **Pause before answering** to **Long**, or **When it answers** to **When you've finished your thought**. |
| _"Ask a workspace admin to connect Glyph."_ on the card | You can't edit this project's connectors. Ask an admin to connect the key. |

## For developers

The web app, Machine Desktop, and the phone apps all use the same API routes,
under the project's channels:

| Route | What it does |
| :--- | :--- |
| `GET /projects/{projectId}/channels/glyph/installation` | The connection, or `null`, with the key's name and Live settings |
| `POST /projects/{projectId}/channels/glyph/connect` | Check a personal key (`api_key`) with Glyph and store it |
| `DELETE /projects/{projectId}/channels/glyph/installation` | Disconnect |
| `PUT /projects/{projectId}/channels/glyph/settings` | Save the Live call settings |
| `POST /projects/{projectId}/channels/glyph/player` | A one-call Glyph player link for a session (`session_id`) |
| `POST /projects/{projectId}/channels/glyph/live` | Answer a WebRTC offer (`session_id`, `sdp`, `instructions`) with a live Glyph call |
| `POST /projects/{projectId}/channels/glyph/live/{glyphSessionId}/turns` | Save what was said in a call to Glyph |

Connect, disconnect, and settings need the project's connector-write
permission.

The [SDK](/docs/sdk) (`@kortix/sdk`) wraps them as `getGlyphInstallation`,
`connectGlyph`, `disconnectGlyph`, `updateGlyphSettings`, `getGlyphPlayer`,
`startGlyphLive`, and `saveGlyphTurns`. Its shared call client runs the call
itself: `startPlayerCall` (Glyph's player, with its tools) and
`startVoiceCall` (a direct WebRTC call), `voiceInstructions` to prime the
voice with the session, `voiceTranscriptMessage` to write the transcript
message, and `parseLiveCallTranscript` to read one back as a call card. The
settings choices are exported as `GLYPH_VOICES`, `GLYPH_LANGUAGES`,
`GLYPH_ROOM_OPTIONS`, and `GLYPH_PAUSE_OPTIONS`.