Connect a line to your agent.

Overview

A line is one phone number + one email address (handle@cosvoice.com) attached to one Chief of Staff, typically a Grok Bot. The line answers calls as that Bot (running a real intake: who, what, amounts, dates, options, next step), places calls, receives texts and email, and writes a debrief (summary, outcome, structured notes, transcript) after every call.

Three ways to use it, all backed by the same tool surface:

• MCP at https://cosvoice.com/mcp — the fastest way to give an agent the line.
• REST at https://cosvoice.com/api/v1 — the same tools as plain HTTPS.
• Webhooks — signed POSTs to your URL when calls, texts, or email arrive.

Authenticate with a per-line API key from Settings → Connect: Authorization: Bearer cv_live_…

Connect Grok Bot (MCP)

Add the server to your agent's MCP configuration. The server is stateless Streamable HTTP; each request carries the bearer key.

{
  "mcpServers": {
    "cosvoice": {
      "url": "https://cosvoice.com/mcp",
      "headers": { "Authorization": "Bearer cv_live_…" }
    }
  }
}

Then paste the Grok Bot skill from Settings → Connect into your bot's standing instructions. It teaches the bot to brief calls like a human assistant, to poll for the outcome, and never to claim a booking that wasn't confirmed.

A brief that works

place_call({
  "to": "+13235550100",
  "callee_name": "Osteria Mozza, host stand",
  "purpose": "Book a table for two this Friday at 7:30 under Graham. If 7:30 is gone, take anything between 7:00 and 8:30. Give the line's number as the callback.",
  "desired_resolution": "A confirmed reservation with a time.",
  "paths": { "voicemail": "Leave the request and the callback number.", "no_availability": "Ask about Saturday at the same time." },
  "max_minutes": 6
})

Agent-driven setup

You don't have to click through onboarding. Sign up, create a setup key on the first onboarding screen, add the MCP server to your agent, and tell it what you want. The key exposes two tools until a line exists — search_numbers and create_line — and then becomes the line's key automatically.

You: "Set up my CosVoice line. Call it Lloyd, area code 949, my mobile is 714-555-0123. Don't text me."

Agent → search_numbers({ area_code: "949" })
Agent → create_line({ name: "Lloyd", phone_number: "+1949…", owner_phone: "+17145550123", sms_opt_in: false })
Agent → update_settings({ instructions: "We prefer 7:30 dinners…" })
Agent → set_webhook({ url: "https://…" })

Some connector UIs only accept a URL. Use https://cosvoice.com/mcp/k/<key> in that case and treat the URL as a secret; rotate the key if it leaks.

MCP tools

Calls are asynchronous. After place_call, poll get_call (every ~20s) until status is completed, no-answer, busy, or failed, or wait for the call.completed webhook.

Integrations

Your agent connects to CosVoice once. Partners with an official agent interface are proxied through the same MCP server as namespaced tools (for example instacart__create_shopping_list_page), authenticated with CosVoice's partner key or your linked account, logged per call, and attributed to CosVoice where the partner supports it. Partners without an agent interface are handled by phone: the line calls them. That is why the list covers every restaurant, pharmacy, and contractor, not just companies with APIs.

• Live: available through the gateway now (Instacart via its official MCP; lists and recipes become carts you check out).
• Connect: available once you link your account (OAuth) in Settings → Integrations.
• By phone: no official agent channel; the line does it with a real call (OpenTable, Resy, Tock venues, pharmacies, airlines, home services).
• Coming: an official interface exists or is announced; not wired yet.

REST equivalents: GET /api/v1/integrations, GET /api/v1/integrations/tools, POST /api/v1/integrations/:partner/:tool.

History & notes

History is one table for every call, text, and email the line has handled, with search and CSV export (/desk/history, GET /api/v1/history?format=csv). Each call carries a debrief, a transcript, and notes: you add them on the call page; your agent adds them with annotate_call to record what it did about the call.

Email forwarding

Everything sent to handle@cosvoice.com is stored (subject, sender, text) and forwarded to the inbox you set in Settings → Email forwarding. Relay mode re-sends the content from hello@cosvoice.com with Reply-To set to the original sender and works for any inbox. Forward original mode passes the message through intact (attachments included) but requires the destination to be a verified address on our mail account; if it fails we relay instead. Your agent also gets email.received and can re-forward with forward_email.

Texting & compliance

Texts to your line always work. Texts from your line are application-to-person messaging: US carriers deliver them only from numbers registered under a 10DLC brand and campaign. CosVoice registers as the brand and runs one conversational campaign covering every line; until that is approved, replies may be filtered (the desk shows the status).

• Opt-in is explicit (the checkbox at onboarding or in Settings) and recorded with a timestamp and source.
• STOP, UNSUBSCRIBE, CANCEL, END, QUIT opt a number out; the line sends one confirmation and nothing else. START re-subscribes. HELP returns who we are and how to reach support.
• Opted-out numbers are refused by send_text and the API.
• The owner's own texts to the line get an intelligent reply; strangers are logged and never auto-messaged.

REST API

Base URL https://cosvoice.com/api/v1. JSON in, JSON out. 240 requests per minute per key.

curl https://cosvoice.com/api/v1/calls/CALL_ID \
  -H "Authorization: Bearer cv_live_…"

{ "ok": true, "id": "…", "direction": "outbound", "status": "completed",
  "outcome": "Reserved · Friday 8:15pm · party of 2",
  "summary": "…", "notes": { "reservation": { … }, "action_items": [ … ] },
  "transcript": [ { "role": "assistant", "text": "Hi, this is Lloyd…" }, … ] }

Webhooks

Set a URL in Settings → Connect. We POST JSON with headers X-CosVoice-Event, X-CosVoice-Delivery, X-CosVoice-Timestamp, and X-CosVoice-Signature: v1=<hex>. Failed deliveries retry with backoff (1m, 5m, 15m, 1h, 4h).

Verify the signature

const expected = "v1=" + crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(`${req.headers["x-cosvoice-timestamp"]}.${rawBody}`)
  .digest("hex");
if (!timingSafeEqual(expected, req.headers["x-cosvoice-signature"])) return 401;

Owner line & contacts

Your mobile is the owner line. When you call or text from it, the line treats what you say as instructions for your Chief of Staff, captures each ask as an owner_instruction event, and reads a summary back. Owner texts get an intelligent reply.

• Approved people reach you warmly and can leave detailed messages.
• VIP people are treated as urgent; use this for family.
• Blocked numbers get a brief, polite wall.
• Everyone else meets a helpful but guarded assistant that never shares your details.

How calls work

Audio runs over a full-duplex speech-to-speech model (Grok Voice), so the line listens while it talks and can be interrupted like a person. Mid-call it can take messages, log callbacks, record reservations, and look things up. It introduces itself as your assistant on outbound calls and confirms it's an AI whenever asked.

On voicemail it leaves a short message with the ask and the line's number as the callback. Calls have a hard cap (default 10 minutes outbound, 30 inbound). Every call ends with a debrief in your desk, your inbox, and your webhook.

Voice & persona

Give your CoS a voice. Every line runs on Grok Voice, a full-duplex speech-to-speech model, and you shape it in Settings → Voice & persona or with update_settings:

• Voice: 26 Grok voices; the recommended set stays clear at phone bandwidth.
• Style: warm, brisk, formal, or playful. Changes how the line carries itself (openers, sentence length, small talk), not the facts or the red lines.
• Speed: 0.8× to 1.2×.
• Pronunciations: up to 20 words the line should say a particular way (your last name, your street, your regular restaurant). Applied as the model's pronunciation dictionary and repeated in its instructions.
• Greeting and standing instructions: the first line on inbound calls and the context it always has.
• Hear it: “Call me” places a short call to your mobile with the current settings.

Replace voicemail

Forward the calls you miss on your own mobile to your line with your carrier's conditional call forwarding (busy, unanswered, unreachable). Twilio tells the line the call was forwarded from your number, so it answers as your assistant covering a missed call ("You've reached Graham's phone, this is Lloyd, his assistant. He can't pick up right now, but I can help") and runs the full intake instead of taking a message. The debrief is tagged Missed on mobile.

• Verizon and its MVNOs: dial *71 + your line's 10 digits; *73 cancels. *72 forwards everything.
• AT&T and T-Mobile (and their MVNOs): *61*1<line># (no answer), *67*1<line># (busy), *62*1<line># (unreachable); #61# etc. cancel. *21*1<line># forwards everything.
• Android phone menus expose the same three conditions under Call forwarding. iPhone's Settings → Phone → Call Forwarding is all-calls only; use the carrier codes for missed-calls-only.

Settings → Replace voicemail shows the codes pre-filled with your number and a one-minute test. Forwarded calls use your plan's minutes like any inbound call.

Minutes & billing

Starter is $29 a month with 60 minutes, Plus $69 with 200, Pro $149 with 600. Minutes are connected call time (inbound and outbound), rounded up per call; overage is $0.25 a minute on every plan. Texts to the line and email don't use minutes. Periods run on your line's monthly anniversary. Founding members get Plus for $49 a month, locked for 12 months.

Security

• Every record is scoped to your line; nothing crosses lines.
• Sessions are HttpOnly, SameSite cookies with CSRF tokens on every change.
• API keys are shown once and stored hashed. Revoke any time.
• Phone webhooks are signature-verified; the voice fleet only accepts streams from our carrier account.
• Webhooks to you are signed with a per-line secret you can rotate.
• We store transcripts and structured notes, not audio recordings.