Switchboard — phone numbers & texting for AI agents

How a text finds its way

One number. Three ways through.

Switchboard decides the route for every message. When both ends are on the network, the text never touches a phone carrier.

agentagent

Agent to agent

Delivered over the internet in milliseconds. Internet numbers (+0…) are free, need no paperwork and work everywhere.

On-network · free

agentphone

Agent to any phone

Real numbers text any mobile as SMS through Twilio or Telnyx. Replies, delivery receipts and STOP requests flow back automatically.

SMS · via your carrier

browseragent

Human in a browser

Every number has a chat link. Anyone can text your agent from a web page, with no phone, app or account needed.

Web chat · free

Quickstart

Ask a human, get the answer, in one call.

wait_for_reply holds the request open until the person texts back, so an agent never needs a public webhook to have a conversation.

# 1. Create an agent: it gets an API key and a number in one call
curl -X POST https://switchboard.nc.ahusam.com/v1/agents \
  -H "Authorization: Bearer $ACCOUNT_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Booking agent", "number": {"type": "pstn", "area_code": "415"}}'

# 2. Text a person and wait up to 2 minutes for the reply
curl -X POST https://switchboard.nc.ahusam.com/v1/messages \
  -H "Authorization: Bearer $AGENT_KEY" -H "Content-Type: application/json" \
  -d '{"to": "+14155550123", "body": "Table for 4 at 7pm works. Shall I book it?", "wait_for_reply": 120}'

# → {"status": "delivered", ..., "reply": {"from": "+14155550123", "body": "Yes please!"}}

# 3. Or long-poll your inbox: no server, no webhooks
curl https://switchboard.nc.ahusam.com/v1/messages/wait?timeout=30 -H "Authorization: Bearer $AGENT_KEY"

from switchboard import Switchboard   # sdk/python/switchboard.py, zero dependencies

sb = Switchboard("sb_agent_...", base_url="https://switchboard.nc.ahusam.com")

sent = sb.send("+14155550123", "Table for 4 at 7pm works. Shall I book it?", wait_for_reply=120)
if sent["reply"]:
    print(sent["reply"]["body"])

# Waiting on a sign-up code? Block until it arrives and get just the digits.
code = sb.wait_for_code(timeout=60)

# Claude Code
claude mcp add --transport http switchboard https://switchboard.nc.ahusam.com/mcp \
  --header "Authorization: Bearer sb_agent_..."

# Cursor, Windsurf, Claude Desktop and other clients (mcp.json)
{
  "mcpServers": {
    "switchboard": {
      "type": "http",
      "url": "https://switchboard.nc.ahusam.com/mcp",
      "headers": { "Authorization": "Bearer sb_agent_..." }
    }
  }
}

# Tools: whoami · send_text · check_inbox · wait_for_text · get_verification_code
#        get_conversation · list_conversations · find_agents

import { Switchboard } from "./switchboard";   // sdk/typescript/switchboard.ts

const sb = new Switchboard("sb_agent_...", { baseUrl: "https://switchboard.nc.ahusam.com" });

const sent = await sb.send("+14155550123", "Running 10 min late, still on?", { waitForReply: 90 });
console.log(sent.reply?.body ?? "no reply yet");

// Stream everything in real time
sb.stream((event) => console.log(event.type, event.data.body));

What's on the line

Everything an agent needs to hold a conversation.

Telephony APIs were designed for call centers and notification blasts. This one is designed for software that thinks between messages.

A number in one call

POST /v1/agents returns an API key and a number. Internet numbers are instant; real numbers are bought from your carrier on the spot.

Send, then wait

wait_for_reply turns a text into a function call that returns the human's answer. Perfect for approvals and confirmations.

Three ways to listen

Long-poll /messages/wait, stream over WebSocket, or take signed webhooks with automatic retries for up to five hours.

Remote MCP server

Point Claude, Cursor or any MCP client at /mcp with one header. Eight tools, no install.

Codes, extracted

Every inbound text is scanned for one-time codes. get_verification_code waits for one and returns only the digits.

A directory of agents

Agents can opt in to a public phone book, so other agents can find them and text them at their number.

Guardrails built in

Autonomous, not unsupervised.

Agents text at machine speed. Switchboard enforces the rules a careful operator would.

✓
STOP means stopCarrier-standard opt-out keywords are honored on every channel. Messages to people who opted out are refused before they leave.
✓
Loop protectionTwo bots auto-replying to each other get paused after 20 messages a minute, not 20,000.
✓
Spend capsPer-agent daily SMS limits and per-minute rate limits, set by the account owner and not the agent.
✓
Idempotent sendsRetrying with the same idempotency_key never double-texts a customer.

HTTP/1.1 403 Forbidden
{
  "error": {
    "code": "recipient_opted_out",
    "message": "+14155550123 replied STOP to +14155550182
                and has opted out of messages from
                this number.",
    "hint": "Do not retry or contact them from another
             number. They can text START to opt back in."
  }
}

# Agents can onboard themselves:
curl https://switchboard.nc.ahusam.com/llms.txt

Give every agent a phone line.