Voice channels

Call a phone number and talk to YOUR coding agent. A voice channel makes the Claude Code or openclaw session you already have open phone-reachable, in its own context — with its tools, its memory, its whole session. The caller speaks; the transcribed turn is injected into your running agent as input; the agent replies in-session; the reply is spoken back over the phone. Tool calls, DTMF, transfers, and "say a final line then hang up" all work.

No audio ever reaches your machine — speech-to-text and text-to-speech run in-network, and only text crosses to your agent. A small connector (a Claude Code channel / an openclaw extension) holds a Saperly manual-mode websocket and bridges it to your agent. The agent connects out, so it needs no public URL.

How it works

  ☎ caller                                                     ☎ caller
     │  speech                                            speech  ▲
     ▼                                                            │
  speech-to-text ──text──▶  Saperly  ──────▶ text-to-speech
   (in-network)                 │   manual-mode websocket    ▲  (in-network)
                                ▼                            │ directive
                       ┌──────────────────┐                 │
                       │   connector      │                 │
                       │ (channel/plugin) │─────────────────┘
                       └──────────────────┘   reply tool → directive
                                │  turn injected as input
                                ▼
                    YOUR agent (its tools + memory)

  audio never touches your machine  ·  speech-to-text + text-to-speech stay in-network

The connector holds one websocket per Saperly connection and multiplexes every live call on it. Each caller turn carries a request_id; your reply must echo it so the right call gets the right directive. The wire contract is the manual-mode protocol — the connectors just adapt it to your agent's native event + tool surface.

Prerequisites

• Bun — the connectors are Bun packages.
• A Saperly manual connection and its manualSecret (from the dashboard: Connections → your manual connection). See Connections.
• A phone number pointed at that connection (Numbers page → set the line's handler to your manual connection). See Numbers.

The base URL accepts https://… (derives wss), http://localhost:8787 (derives ws), or a bare host (defaults to wss).

Call your agent — the demo

Claude Code

The saperly-voice connector is a Claude Code channel (an MCP server, per the channels reference) that also holds the Saperly websocket.

/saperly-voice:configure baseUrl=https://api.saperly.com connectionId=conn_123 secret=mc_abc123

claude --dangerously-load-development-channels plugin:saperly-voice

<channel source="saperly-voice" kind="inbound_call" request_id="…" …>

{
  "request_id": "req_…",   // from the <channel> tag — echo it verbatim
  "kind": "speak",          // speak | wait | hangup | transfer | send_dtmf
  "text": "…",              // required for speak
  "end_call": false,         // speak: hang up after the line plays
  "to": "+1…",              // required for transfer (E.164 or SIP URI)
  "digits": "123#",         // required for send_dtmf
  "timeout_ms": 5000,        // wait: optional gather timeout
  "reason": "…"             // hangup: optional
}

openclaw

The saperly-voice-openclaw connector is an openclaw extension loaded by the Gateway. It registers the saperly_voice_reply agent tool and holds the Saperly websocket; each call routes to a stable per-call session saperly-voice:<call_id>, so a multi-turn call stays in one conversation.

{
  plugins: {
    enabled: true,
    allow: ["saperly-voice"],
    entries: {
      "saperly-voice": {
        enabled: true,
        config: {
          baseUrl: "https://api.saperly.com",
          connectionId: "conn_123",
          // Prefer the env var for the secret:
          // manualSecret: "mc_…",
        }
      }
    }
  }
}

Reply / directive reference

Every reply (Claude Code) and saperly_voice_reply (openclaw) maps to one manual-mode directive. Invalid args (e.g. a speak with no text, an unknown kind) are rejected by the tool with a correctable message and never sent to the live call.

Always echo the request_id from the incoming turn, and answer within ~18s or the caller hears a short hold line.

Next steps

• Manual mode — the underlying event/directive protocol these connectors speak.
• Connections — creating the manual connection and finding its manualSecret.
• Voice — calls, lifecycle, and outbound calling.
• Core concepts — the Saperly model and how a call flows.