docs: add Composer feature documentation (Alpha)

fern/composer.mdx

@@ -0,0 +1,286 @@
+---
+title: Composer
+subtitle: Build and configure voice AI agents through natural conversation
+slug: composer
+---
+
+<Warning>
+Composer is currently in **Alpha**. Features and behavior may change as we iterate based on user feedback.
+</Warning>
+
+## Overview
+
+Composer is Vapi's intelligent assistant that helps you build and configure voice AI agents through natural conversation. Instead of manually configuring settings and writing prompts, describe what you want to build and Composer handles the technical setup.
+
+Composer understands voice agent architecture and Vapi's capabilities. It can create agents, configure phone numbers, set up integrations, troubleshoot issues, and answer questions about Vapi features.
+
+**Why use Composer:**
+
+- **Faster development** — Build agents in minutes instead of hours by describing your use case
+- **Best practices built in** — Composer applies Vapi best practices automatically
+- **Lower barrier to entry** — No need to learn every API parameter or configuration option
+- **Troubleshooting support** — Composer can diagnose issues and suggest fixes
+
+## Get started
+
+<Steps>
+  <Step title="Open Composer">
+    Log into your [Vapi dashboard](https://dashboard.vapi.ai) and click the **Composer** option in the navigation, or use the chat widget.
+  </Step>
+  <Step title="Describe what you want to build">
+    Tell Composer what you need in plain language. The more context you provide, the better the result.
+
+    **Effective prompts:**
+    - "Help me build a restaurant reservation agent"
+    - "I need to set up a phone number for my agent"
+    - "Create an agent that can answer questions about my business"
+    - "My agent isn't transferring calls correctly, can you help?"
+  </Step>
+  <Step title="Answer clarifying questions">
+    Composer asks follow-up questions to understand your requirements, then takes action to build and configure your agent.
+  </Step>
+  <Step title="Test and iterate">
+    Test the agent Composer creates, then request adjustments as needed. Building the right agent is an iterative process.
+  </Step>
+</Steps>
+
+## What Composer can do
+
+### Capabilities
+
+- Create and configure assistants
+- Set up phone numbers
+- Configure integrations and webhooks
+- Update agent prompts and settings
+- Troubleshoot technical issues
+- Answer questions about Vapi features
+- Recommend best practices for your use case
+
+### Limitations
+
+- **Cannot delete resources** — Composer cannot delete assistants, tools, phone numbers, or any other resources. This is an intentional safety measure. Use the dashboard sidebar to delete resources manually.
+- **Cannot access external systems** — Composer operates within Vapi and cannot reach your CRM, database, or other third-party systems directly.
+- **Cannot make business logic decisions** — You provide the domain knowledge; Composer handles the technical configuration.
+- **Cannot test your agent** — You need to test the agent yourself and provide feedback.
+- **Cannot deploy to production automatically** — You control when and how changes go live.
+
+## Common use cases
+
+<AccordionGroup>
+  <Accordion title="Build a new agent from scratch">
+    **What you say:**
+
+    > "I want to build an agent for my dental office that can schedule appointments and answer common questions about our services."
+
+    **What Composer does:**
+    1. Asks about your specific requirements (hours, services, appointment types)
+    2. Creates an agent with an appropriate system prompt
+    3. Configures necessary tools (calendar integration, knowledge base)
+    4. Sets up phone number configuration
+    5. Provides testing guidance
+
+    **Your part:**
+    - Answer Composer's questions about your business
+    - Provide specific details (office hours, services offered, etc.)
+    - Test the agent and provide feedback
+
+    **Example conversation:**
+
+    ```txt title="Sample conversation"
+    You: "I want to build an agent for my dental office that can schedule
+    appointments and answer common questions."
+
+    Composer: "I'd be happy to help you build a dental office agent! Let me
+    ask a few questions:
+
+    1. What are your office hours?
+    2. What types of appointments do you offer?
+    3. Do you want the agent to book directly or collect information
+       for your staff to follow up?
+    4. What are the most common questions patients ask?"
+
+    You: "Office hours are Mon-Fri 9am-5pm. We do cleanings, exams, and
+    consultations. The agent should collect appointment requests and our
+    staff will confirm. Common questions are about insurance, parking,
+    and first-visit procedures."
+
+    Composer: "I've created your dental office agent. It's configured to:
+    - Collect appointment requests during business hours
+    - Answer questions about insurance, parking, and first visits
+    - Escalate to staff when needed
+
+    Would you like me to set up a phone number for testing?"
+    ```
+  </Accordion>
+
+  <Accordion title="Set up a phone number">
+    **What you say:**
+
+    > "I need to connect a phone number to my agent."
+
+    **What Composer does:**
+    1. Asks if you want to purchase a new number or import an existing one
+    2. Helps you select an area code or region
+    3. Configures the number to work with your agent
+    4. Provides the phone number for testing
+
+    <Tip>
+    If you need a specific area code for local presence, mention it upfront. If you're porting an existing number, have your account details from your current provider ready.
+    </Tip>
+  </Accordion>
+
+  <Accordion title="Troubleshoot issues">
+    **What you say:**
+
+    > "My agent keeps dropping calls when trying to transfer."
+
+    **What Composer does:**
+    1. Asks diagnostic questions (when does it happen, what number, etc.)
+    2. Checks your agent configuration
+    3. Identifies the issue (incorrect transfer format, missing permissions, etc.)
+    4. Fixes the configuration or guides you through the fix
+
+    **Common issues Composer can help with:**
+    - Call transfers not working
+    - Agent not responding correctly to specific inputs
+    - Phone number routing problems
+    - Integration failures (calendar, CRM, etc.)
+    - Voice quality or latency issues
+    - Prompt behavior not matching expectations
+  </Accordion>
+
+  <Accordion title="Integrate with external systems">
+    **What you say:**
+
+    > "I want my agent to check availability in our calendar before booking appointments."
+
+    **What Composer does:**
+    1. Explains integration options (API webhooks, direct integrations)
+    2. Helps configure the integration endpoint
+    3. Sets up the agent to call your API with the right parameters
+    4. Provides example requests/responses for testing
+
+    **Your part:**
+    - Provide your API endpoint URL
+    - Share authentication details (API keys, etc.)
+    - Describe the expected request/response format
+    - Test the integration with real scenarios
+
+    **Popular integrations:** Google Calendar, Calendly, Salesforce, HubSpot, booking systems, knowledge bases, and custom APIs.
+  </Accordion>
+</AccordionGroup>
+
+## Safety features
+
+Composer includes safeguards to prevent accidental or irreversible changes to your account.
+
+### No deletion capability
+
+Composer **cannot delete any resources** — assistants, tools, phone numbers, squads, files, or anything else. This is a deliberate safety measure, not a limitation.
+
+If you ask Composer to delete something, it directs you to do it yourself:
+
+```txt title="Deletion request example"
+You: "Delete my old test assistant"
+
+Composer: "I'm not able to delete resources to prevent accidental data loss.
+You can delete it yourself from the dashboard — use the sidebar on the left,
+go to Assistants, select the one you want to remove, and delete it from there."
+```
+
+<Note>
+Unlike creating or updating a resource (which can be undone or re-done), deletion is permanent. Requiring manual confirmation through the dashboard UI prevents accidental loss of important configurations.
+</Note>
+
+### Approval required for updates
+
+When Composer modifies an existing resource (like updating an assistant's prompt, changing a voice setting, or editing a tool configuration), it pauses and asks for your explicit approval first.
+
+**How the approval flow works:**
+
+<Steps>
+  <Step title="Composer proposes a change">
+    Composer shows you a summary of the update it wants to make.
+  </Step>
+  <Step title="You review and respond">
+    The chat interface displays **Approve** and **Deny** buttons. Click **Approve** to proceed or **Deny** to cancel.
+  </Step>
+  <Step title="Composer applies the change (if approved)">
+    If approved, Composer makes the update and confirms. If denied, no changes are made.
+  </Step>
+</Steps>
+
+```txt title="Approval flow example"
+You: "Change my agent's voice to sound more energetic"
+
+Composer: [Proposes update]
+→ UI shows: "Update Resource — Updating voice settings on assistant xyz"
+  [Approve] [Deny]
+
+You: [Clicks Approve]
+
+Composer: "Done! I've updated the voice settings. Test it out and let me
+know if you'd like to adjust further."
+```
+
+**Key details about approvals:**
+
+- **Tokens expire after 10 minutes** — if you don't respond in time, Composer needs to re-propose the change
+- **Each approval is specific** — approval tokens are cryptographically bound to the exact change being made; multiple updates each require individual approval
+- **Read operations don't require approval** — Composer can freely read and list your resources without permission
+- **Creating new resources doesn't require approval** — new assistants, tools, and other resources are additive and non-destructive
+
+## Tips for best results
+
+### Be specific about your use case
+
+Provide context about your industry, audience, and requirements upfront.
+
+```txt title="Compare prompt quality"
+Less effective: "I need an agent"
+
+More effective: "I need an agent for my e-commerce store that can track
+orders, answer product questions, and handle returns"
+```
+
+### Iterate in stages
+
+Build a basic working agent first, then layer on advanced features:
+
+1. **Phase 1** — Basic conversation flow
+2. **Phase 2** — Add integrations (calendar, CRM, knowledge base)
+3. **Phase 3** — Add advanced features (custom voices, complex routing)
+
+### Handle one task at a time
+
+Keep conversations focused on a single objective for best results.
+
+```txt title="Compare task scoping"
+Less effective: "Set up my phone number, fix the transfer issue, add
+Spanish support, and integrate with my CRM"
+
+More effective: "First, let's set up my phone number"
+[Complete that task]
+"Great! Now can you help me fix the transfer issue?"
+```
+
+### Ask Composer to explain
+
+If you're unsure about Vapi features or want to learn the API, ask directly:
+
+- "What's the best way to handle voicemail?"
+- "Should I use function calling or server URL for my integration?"
+- "Can you show me the API call you're making to create this agent?"
+
+<Tip>
+Ask Composer for the full configuration of an agent it builds. Save it in version control to use as a template for similar agents.
+</Tip>
+
+## Next steps
+
+Now that you know how Composer works:
+
+- **[Assistants quickstart](/assistants/quickstart):** Learn the fundamentals of building voice agents manually
+- **[Prompting guide](/prompting-guide):** Write effective system prompts for your agents
+- **[Tools overview](/tools):** Understand the tools and integrations available to your agents
+- **[Phone numbers](/phone-numbers/free-telephony):** Set up phone numbers for your agents

fern/docs.yml

@@ -115,6 +115,10 @@ navigation:
           - page: Vapi Guides
             icon: fa-light fa-book-open
             path: guides.mdx
+          - page: Composer
+            icon: fa-light fa-wand-magic-sparkles
+            path: composer.mdx
+            availability: pre-release
           - page: CLI quickstart
             icon: fa-light fa-terminal
             path: cli/overview.mdx