Voicetta
    Sign InGet Started

    Voicetta Docs

    Setup Host Guides

    Platform-specific guides for provisioning Voicetta via Claude MCP, Cursor MCP, ChatGPT Actions, and raw REST.

    On this page

    Use these guides to test and run Voicetta setup from your AI host. The canonical contract is the Setup API playbook; each host is a thin adapter.

    Why it matters for your business

    • Save money: validate one flow once, reuse across Claude, Cursor, and ChatGPT.
    • Work faster: copy-paste configs per host instead of rediscovering endpoints.
    • Standardize service: every host follows the same consent → handoff sequence.
    • Delight every Guest: consistent handoff regardless of which AI tool they use.

    Prerequisites

    Claude Desktop (remote MCP)

    This section is Setup MCP. It provisions a new agent, and no API key goes in the config.

    To place a call from a workspace you already have, connect Claude to https://api.voicetta.com/mcp with your workspace API key. See Claude.

    Add the hosted Setup server. No token goes in the config.

    json
    { "mcpServers": { "voicetta-setup": { "url": "https://mcp.voicetta.com/mcp" } } }

    E2E scenario

    1. Ask Claude: "Provision Voicetta for my hotel using voicetta_create_setup_session."
    2. Open the returned consent_url in a browser and authorize as the workspace owner.
    3. Ask Claude to call voicetta_wait_for_consent. It stores the bearer for the rest of the process.
    4. Submit profile, configure the assistant, upload knowledge, skip or pay for a phone, select tools.
    5. When pending_human_steps lists a tool or payment, finish that page in the dashboard. The page reports back.
    6. Record the test call and fetch the handoff. It includes login_url and the phone when one was bought.

    Stdio is the fallback: npx -y @voicetta/setup-mcp with VOICETTA_SETUP_API_URL=https://api.voicetta.com. The same tools run. VOICETTA_SETUP_SESSION_ID and VOICETTA_SETUP_ACCESS_TOKEN only resume a session that already exists.

    Cursor (MCP)

    Prefer the remote URL. Stdio is the same tool list when a local process is required.

    json
    { "mcpServers": { "voicetta-setup": { "url": "https://mcp.voicetta.com/mcp" } } }

    E2E scenario

    1. Prompt: "Create a Voicetta setup session with partner_agent cursor."
    2. Complete consent in the browser when given consent_url.
    3. Call voicetta_wait_for_consent. Do not paste a bearer into the config.
    4. List the catalog, select sms, enable it, and finish the connection in the dashboard when pending_human_steps says so.
    5. Confirm the envelope status reaches completed after the test call and handoff.

    ChatGPT (GPT Actions / OpenAPI)

    Import https://voicetta.com/setup-openapi.json as a custom GPT Action. Authentication stays off until POST /sessions/{id}/claim returns setup_access_token. Use that bearer for the later steps. Do not ask the human to copy it out of the consent page.

    E2E scenario

    1. Upload or link the OpenAPI spec to a GPT.
    2. Instruction: "Follow the Voicetta agent setup playbook. Start with POST /v1/setup/sessions."
    3. When human_required appears, show the URL to the user and wait.
    4. Continue with Bearer auth for remaining endpoints.
    5. End with GET /v1/setup/sessions/{id}/handoff.

    Raw REST (curl)

    For agents without MCP or Actions — including custom or regional LLM hosts.

    Create session

    bash
    curl -sS -X POST "https://api.voicetta.com/v1/setup/sessions" \ -H "Content-Type: application/json" \ -H "X-Partner-Agent: custom" \ -d '{"partner_agent":"custom"}'

    List tool catalog (no auth)

    bash
    curl -sS "https://api.voicetta.com/v1/setup/tools/catalog?category=PMS"

    Authenticated steps

    bash
    export SETUP_TOKEN="setup_..." export SESSION_ID="ses_..." curl -sS "https://api.voicetta.com/v1/setup/sessions/${SESSION_ID}" \ -H "Authorization: Bearer ${SETUP_TOKEN}" curl -sS -X POST "https://api.voicetta.com/v1/setup/sessions/${SESSION_ID}/profile" \ -H "Authorization: Bearer ${SETUP_TOKEN}" \ -H "Content-Type: application/json" \ -d '{"profile":{"business_name":"Demo Hotel","industry":"Hospitality"}}' curl -sS "https://api.voicetta.com/v1/setup/sessions/${SESSION_ID}/handoff" \ -H "Authorization: Bearer ${SETUP_TOKEN}"

    E2E checklist

    • POST /sessions returns consent_url and agent_claim_token
    • After consent, POST /sessions/{id}/claim returns a bearer that works on GET /sessions/{id}
    • Profile, assistant, knowledge steps advance status
    • GET /tools/catalog lists guesty, sms, calcom
    • POST /tools/select and /tools/{id}/enable return envelope or human_required
    • GET /handoff returns login, phone, and next steps

    Automated route checks (CI)

    Backend pytest verifies Setup API routes are mounted and the public catalog responds:

    bash
    cd voicetta-backend-app poetry run pytest tests/test_setup_api_routes.py -q

    Troubleshooting

    SymptomFix
    401 on session stepsCall voicetta_wait_for_consent or POST /claim after the human authorizes
    409 AWAITING_CONSENT on claimThe human has not authorized yet. Keep polling
    400 state transitionCall steps in order; check message_for_user_agent
    pending_human_steps is not emptyThe human still has to finish that dashboard page
    Tool enable returns human_requiredSend the human to the URL. The dashboard posts human-step/complete

    Related pages