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 UI | Agent API | After enable |
|---|---|---|
| Connection | Setup 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
| Resource | URL |
|---|---|
| LLM index | https://voicetta.com/llms.txt |
| OpenAPI | https://voicetta.com/setup-openapi.json |
| MCP package | @voicetta/setup-mcp |
| Host guides | Setup Host Guides |
Base API URL: https://api.voicetta.com/v1/setup
AgentEnvelope
Every authenticated step returns an AgentEnvelope:
{
"session_id": "ses_...",
"status": "awaiting_consent",
"message_for_user_agent": "Ask the user to open the consent URL.",
"actions_completed": ["session_created"],
"pending_human_steps": [],
"human_required": null,
"handoff": null
}Poll pending_human_steps. Each item is consent, payment, or tool and includes the dashboard URL. When human_required is present on a single response, relay that URL too. Resume when the list is empty.
Setup flow
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
POST /v1/setup/sessions
Content-Type: application/json
X-Partner-Agent: claude
{"partner_agent": "claude"}Response: session_id, consent_url, agent_claim_token, status. Keep agent_claim_token in the agent process. Do not show it to the human.
2. Human consent, then claim
Send the human to consent_url. They sign in as the workspace owner and choose Authorize. The consent page does not reveal the bearer.
After that, exchange the claim token once:
POST /v1/setup/sessions/{session_id}/claim
Content-Type: application/json
{"agent_claim_token": "..."}409 with AWAITING_CONSENT means the human has not finished. Poll. A successful response returns setup_access_token one time. Later calls use:
Authorization: Bearer setup_...TTL: 24 hours, bound to one session_id. The claim token cannot be reused.
3. Profile → assistant → knowledge
POST /v1/setup/sessions/{session_id}/profile
POST /v1/setup/sessions/{session_id}/assistant
POST /v1/setup/sessions/{session_id}/knowledgeEach step returns an updated envelope with the next message_for_user_agent.
4. Phone (optional)
POST /v1/setup/sessions/{session_id}/phoneSkipping telephony (skip_phone: true) moves on. Buying a number returns a payment step whose URL is /pricing?setup_session={session_id}. The dashboard posts human-step/complete when the human finishes. Poll pending_human_steps on GET /v1/setup/sessions/{session_id}.
5. Tool catalog and selection
GET /v1/setup/tools/catalog
GET /v1/setup/tools/catalog?category=PMS&industry=Hospitality
POST /v1/setup/sessions/{session_id}/tools/selectList only available tools. UI label for each item is Connection.
6. Enable or skip tools
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}/toolsEnabling a tool that needs a dashboard connection returns human_required and adds a tool entry to pending_human_steps. The human finishes it under Connections. That page posts:
POST /v1/setup/sessions/{session_id}/human-step/complete
Content-Type: application/json
{"step": "tool", "tool_id": "sms"}Payment uses {"step": "payment"}. Both routes use the dashboard cookie, not the setup bearer, and only the workspace owner can call them. When the last selected tool is enabled or skipped, the session advances to test_pending on its own. POST /sessions/{id}/advance still does that check if you call it yourself. Do not send tool secrets in payload.
7. Test call and handoff
POST /v1/setup/sessions/{session_id}/test-call
GET /v1/setup/sessions/{session_id}/handoffReturn 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_sessionvoicetta_wait_for_consentvoicetta_get_session_statusvoicetta_list_tools_catalogvoicetta_get_tool_detailsvoicetta_submit_business_profilevoicetta_configure_assistantvoicetta_upload_knowledgevoicetta_request_phone_numbervoicetta_select_toolsvoicetta_enable_toolvoicetta_skip_toolvoicetta_get_tools_statusvoicetta_advance_sessionvoicetta_register_webhookvoicetta_run_test_callvoicetta_get_handoff_summary
voicetta_create_setup_session keeps agent_claim_token. voicetta_wait_for_consent polls POST /claim and stores the bearer. Remote URL: https://mcp.voicetta.com/mcp. Stdio is npx -y @voicetta/setup-mcp. VOICETTA_SETUP_SESSION_ID and VOICETTA_SETUP_ACCESS_TOKEN only resume an existing session.
Webhooks (optional)
Agents without push support can poll GET /sessions/{id}. For async steps (phone provisioning, OAuth), register:
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-Agentorpartner_agentfor attribution (claude,chatgpt,cursor,custom). - When status is
completed, stop and deliver the handoff.