Voice Agent Connector

NumberClaw sits between the phone network and your agent. When a caller speaks, NumberClaw converts the audio into text, sends that text to your connector over WebSocket, waits for your reply, and speaks the reply back to the caller.

┌──────────┐     PSTN      ┌──────────────────┐    WebSocket     ┌──────────────┐
│  Caller  │ ◄───────────► │   NumberClaw     │ ◄──────────────► │ Your Machine │
│  (phone) │               │  STT ↔ TTS ↔ VAD │   (text only)   │  nc-connect  │
└──────────┘               └──────────────────┘                  │  ↓           │
                                                                 │  handler.py  │
                                                                 │  ↓           │
                                                                 │  Your LLM    │
                                                                 └──────────────┘

• NumberClaw converts speech to text and text back to speech.
• Your agent receives plain text and returns plain text.
• You do not need to handle audio streaming, PSTN, or telephony codecs.
• NumberClaw never needs your LLM keys, your system prompt, or your private memory store.

Prerequisites:

• Python 3.10 or newer.
• A NumberClaw account with a Voice AI number.
• An API key copied from the dashboard.

From zero to a working connector in about five minutes:

# Install
pip install numberclaw

# Option A: Claude on a phone number
nc-connect --key YOUR_NC_KEY --handler anthropic --llm-key YOUR_ANTHROPIC_KEY

# Option B: Point at your existing API
nc-connect --key YOUR_NC_KEY --handler webhook --url http://localhost:8080/chat

# Option C: Custom Python handler
nc-connect --key YOUR_NC_KEY --handler custom --script handler.py

The CLI flags shown above come directly from the current connector implementation. The required flags are --key and --handler. The--llm-key, --url, and --script flags depend on the handler you choose.

Your custom script must export a callable named handle_message.

async def handle_message(
    text: str,
    number: str,
    caller: str,
    caller_name: str | None,
    session_id: str,
    channel: str,
    **kwargs,
) -> str | HandlerResult | dict:

NumberClaw speaks the returned text back to the caller. Iftranscript_posted is false, NumberClaw can also run its own transcript-sync path for configured messaging integrations.

The connector protocol is intentionally small. It only moves text messages and call-control events.

Authentication frame:

{"type": "auth", "api_key": "nc_live_xxx"}

Authentication success:

{"type": "auth_ok", "agent_name": "My Agent", "numbers": ["+12125551234"]}

Inbound user message:

{
  "type": "user_message",
  "id": "m1",
  "text": "Hello, I need help with my order",
  "number": "+12125551234",
  "caller": "+14155550123",
  "caller_name": "Alice",
  "session_id": "sess-abc123",
  "channel": "voice"
}

Outbound agent response:

{
  "type": "agent_response",
  "id": "m1",
  "text": "Hi Alice! I'd be happy to help with your order.",
  "transcript_posted": false
}

Cancel event:

{"type": "cancel", "id": "m1", "reason": "caller_hangup"}

Heartbeat:

{"type": "ping"}
{"type": "pong"}

The current CLI supports four handler types: anthropic, openrouter, webhook, and custom.

nc-connect --key NC_KEY --handler anthropic --llm-key sk-ant-xxx
# Optional: --model claude-sonnet-4 --system-prompt "You are a receptionist"

nc-connect --key NC_KEY --handler openrouter --llm-key sk-or-xxx
# Optional: --model anthropic/claude-sonnet-4

nc-connect --key NC_KEY --handler webhook --url http://localhost:8080/chat

Use the custom mode when you already have an agent runtime or you want direct control over prompts, memory, tools, transcript policy, and external services.

Minimal example:

# handler.py
async def handle_message(text, number, caller, caller_name, session_id, channel, **kwargs):
    return f"You said: {text}"

nc-connect --key NC_KEY --handler custom --script handler.py

A more advanced reference exists in examples/openclaw_handler.py. That example shows how to combine conversation history, prompt bootstrap, recall, and asynchronous transcript posting while still returning a plain HandlerResult to NumberClaw.

Webhook equivalents if you want to keep your agent behind HTTP:

from flask import Flask, jsonify, request

app = Flask(__name__)


@app.post("/chat")
def chat():
    data = request.get_json() or {}
    return jsonify({"response": f"Hello {data.get('caller_name', 'caller')}"})

const express = require('express');
const app = express();

app.use(express.json());

app.post('/chat', (req, res) => {
  const { text, caller_name } = req.body;
  res.json({ response: `Hello ${caller_name || 'caller'}, you said: ${text}` });
});

app.listen(8080);

Voice AI numbers are intentionally restricted. Only registered caller IDs can reach the agent. This is not an optional recommendation. It is how the connector model keeps usage bounded and predictable.

• Add a contact in the dashboard for a Voice AI number.
• The contact's caller ID becomes eligible to reach the agent.
• Everyone else is rejected before the call is routed into your connector.

Manage this from the dashboard path Numbers → selected number → Integrations → Caller Mappings.

The connector supports two transcript modes:

• Agent-managed: your handler posts the transcript itself and returns transcript_posted=True.
• NC-managed: your handler returns a plain string or transcript_posted=False, and NumberClaw handles its own sync path.

from nc_connect.connector import HandlerResult

async def call_my_llm(text: str) -> str:
    return f"Thanks for calling. You said: {text}"

async def post_to_my_telegram(caller: str, caller_text: str, response_text: str) -> None:
    print(caller, caller_text, response_text)

async def handle_message(text, number, caller, caller_name, session_id, channel, **kwargs):
    del number, caller_name, session_id, channel, kwargs
    response = await call_my_llm(text)
    await post_to_my_telegram(caller, text, response)
    return HandlerResult(text=response, transcript_posted=True)

Use agent-managed mode if you already have your own Telegram, Slack, or Discord delivery path. Use NC-managed mode if you want the dashboard-configured messaging integrations to receive the transcript.

• Handler timeout: built-in handlers use request timeouts and return a short fallback such asI need a moment. Could you try again? or a generic processing message.
• Handler exception: the connector logs the exception and sends a sanitized response instead of leaking internal details to the caller.
• Disconnect: nc-connect automatically reconnects with exponential backoff starting at 1 second and capping at 30 seconds.
• Caller hangs up: NumberClaw sends a cancel frame, and the connector cancels the in-flight task for that message.

The connector is designed to stay alive after individual handler failures. A bad call should not take down the whole connection.