Voicetta
    Voicetta.

    Voicetta Docs

    Agent Setup Playbook

    Step-by-step guide for external AI agents provisioning Voicetta via the Setup API, MCP, or REST.

    On this page

    Agent Setup Playbook

    This playbook is for external AI agents (Claude, ChatGPT, Cursor, custom bots) that provision Voicetta on behalf of a human Guest.

    Why it matters for your business

    • Save money: one agent session replaces repeated manual onboarding support.
    • Work faster: profile, assistant, knowledge, phone, and tools in one guided flow.
    • Standardize service: every host uses the same Setup API contract.
    • Delight every Guest: the human receives a ready handoff card with login and forwarding steps.

    Terminology bridge

    When human-facing docs say Connections in app.voicetta.com, the Setup API uses Tools:

    Human UIAgent APIAfter enable
    ConnectionSetup Tool (tool_id)Capability (voice action)

    Examples:

    • UI: "Connect Guesty" → API: tool_id: guesty → Capability: guesty_search_reservations
    • UI: "SMS channel" → API: tool_id: sms → Capability: send_sms_confirmation

    Do not send connection or integration in Setup API requests. Use tool_id from the catalog.

    Discovery

    ResourceURL
    LLM indexhttps://voicetta.com/llms.txt
    OpenAPIhttps://voicetta.com/setup-openapi.json
    MCP package@voicetta/setup-mcp
    Host guidesSetup Host Guides

    Base API URL: https://api.voicetta.com/v1/setup

    AgentEnvelope

    Every authenticated step returns an AgentEnvelope:

    json
    { "session_id": "ses_...", "status": "awaiting_consent", "message_for_user_agent": "Ask the user to open the consent URL.", "actions_completed": ["session_created"], "human_required": { "type": "consent", "url": "https://app.voicetta.com/setup/consent?...", "instructions": "Authorize Voicetta setup in the browser." }, "handoff": null }

    When human_required is present, pause automation and instruct the human. Resume after they complete the step.

    Setup flow

    mermaid
    flowchart LR A[Create session] --> B[Human consent] B --> C[Profile] C --> D[Assistant] D --> E[Knowledge] E --> F[Phone] F --> G[Select tools] G --> H[Enable tools] H --> I[Test call] I --> J[Handoff]

    1. Create session

    http
    POST /v1/setup/sessions Content-Type: application/json X-Partner-Agent: claude {"partner_agent": "claude"}

    Response: session_id, consent_url, status.

    2. Human consent

    Send the human to consent_url. After login and authorization, Voicetta issues a scoped Bearer token:

    Authorization: Bearer setup_...

    TTL: 24 hours, bound to one session_id.

    3. Profile → assistant → knowledge

    http
    POST /v1/setup/sessions/{session_id}/profile POST /v1/setup/sessions/{session_id}/assistant POST /v1/setup/sessions/{session_id}/knowledge

    Each step returns an updated envelope with the next message_for_user_agent.

    4. Phone (optional)

    http
    POST /v1/setup/sessions/{session_id}/phone

    May return human_required for payment (type: payment) or forwarding instructions. Poll GET /v1/setup/sessions/{session_id} until status advances.

    5. Tool catalog and selection

    http
    GET /v1/setup/tools/catalog GET /v1/setup/tools/catalog?category=PMS&industry=Hospitality POST /v1/setup/sessions/{session_id}/tools/select

    List only available tools. UI label for each item is Connection.

    6. Enable or skip tools

    http
    POST /v1/setup/sessions/{session_id}/tools/{tool_id}/enable POST /v1/setup/sessions/{session_id}/tools/{tool_id}/skip GET /v1/setup/sessions/{session_id}/tools

    OAuth and marketplace tools often return human_required with a URL. Credentials-based tools may accept payload from the agent when agent_can_submit_credentials is true.

    7. Test call and handoff

    http
    POST /v1/setup/sessions/{session_id}/test-call GET /v1/setup/sessions/{session_id}/handoff

    Return the handoff JSON to the human: login URL, Voicetta phone, forwarding instructions, tool status, and next steps.

    MCP mirror

    The @voicetta/setup-mcp package exposes one MCP tool per Setup API step:

    • voicetta_create_setup_session
    • voicetta_get_session_status
    • voicetta_list_tools_catalog
    • voicetta_submit_business_profile
    • voicetta_configure_assistant
    • voicetta_upload_knowledge
    • voicetta_request_phone_number
    • voicetta_select_tools
    • voicetta_enable_tool
    • voicetta_skip_tool
    • voicetta_get_tools_status
    • voicetta_run_test_call
    • voicetta_get_handoff_summary

    Set VOICETTA_SETUP_SESSION_ID and VOICETTA_SETUP_ACCESS_TOKEN after consent.

    Webhooks (optional)

    Agents without push support can poll GET /sessions/{id}. For async steps (phone provisioning, OAuth), register:

    http
    POST /v1/setup/sessions/{session_id}/webhooks/register {"webhook_url": "https://your-agent.example/hooks/voicetta"}

    Events: phone.provisioned, tool.enabled, test_call.completed.

    Rules

    • Only document and call tools Voicetta can actually perform.
    • Never include passwords in handoff — reference Google OAuth or the password set at consent.
    • Use X-Partner-Agent or partner_agent for attribution (claude, chatgpt, cursor, custom).
    • When status is completed, stop and deliver the handoff.

    Related pages