> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ellaworx.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ellaworx.ai/_mcp/server. # Vapi Voice Assistant The Vapi deploy provider lets you push versioned prompts and tools from Ellaworx directly into **Vapi assistants**. Ellaworx creates or updates the assistant, creates and attaches its tools, imports assistants you already have in Vapi, and checks deployed assistants for drift. ## Vapi Account Setup Ellaworx authenticates to Vapi with a single **API key**. No other cloud setup is required. 1. Log in to the [Vapi Dashboard](https://dashboard.vapi.ai). 2. Copy the API key for the Vapi organization that should own your assistants. > **Note** > > Each Ellaworx environment uses its own credentials, so you can point `dev` and `prod` at different Vapi organizations by giving each environment a different key. --- ## Connection Setup in Ellaworx ### 1. Store the API Key as a Secret In Ellaworx, navigate to **Environments / Secrets** and add your Vapi API key as a secret (for example `VAPI_API_KEY`). ### 2. Add Vapi to an Environment 1. Open the environment (e.g. `dev`) and, under **Providers**, choose **Vapi** from **Select provider**, then click **Add**. 2. In the **Secret** field, pick the secret you created. You can also click **Add Secret** to create one inline. Ellaworx stores the key as a secret reference, not as plain text: | Field | Value | | :----------- | :---------------------------------------------------------------------------- | | **`apiKey`** | `${VAPI_API_KEY}` — a reference to your secret, decrypted only at deploy time | > \[!NOTE] > **Global environment:** If Vapi is configured on the Global (`*`) environment, its credentials apply to every environment automatically. Add Vapi to a specific environment only when it needs its own key. --- ## Agent Configuration A Vapi agent's provider configuration mirrors the Vapi assistant object. Before every deploy, Ellaworx validates it, checking model, voice and transcriber against schemas generated from Vapi's OpenAPI spec. * **Name**: The assistant name in Vapi. A top-level `name` is **required**. * **Model**: `model.provider`, `model.model` and `model.messages`. Your system prompt is placed in `model.messages` as a `system` message. * **Voice**: `voice.provider` and `voice.voiceId`. * **Transcriber**: `transcriber.provider` and its options. * **First Message**: What the assistant says when the call starts. > \[!IMPORTANT] > **Defaults for missing fields:** If the model, voice or transcriber is incomplete, Ellaworx fills it before deploying: `openai` / `gpt-4o` for the model, `openai` / `alloy` for the voice, and `deepgram` / `nova-2` for the transcriber. Set these explicitly if you want something else. ### Prompt Fields You can link registry prompts to these Vapi fields: the main system prompt, **First Message**, and the analysis prompts **Success Evaluation**, **Structured Data**, **Summary** and **Success**. The analysis prompts are written into the assistant's `analysisPlan`. --- ## Working with Tools Vapi tools are created as standalone tools in your Vapi organization and attached to the assistant by ID through `model.toolIds`. On deploy, Ellaworx resolves each tool reference (e.g. `my-tool@^1.0.0`) to a Vapi tool UUID, creating the tool if it doesn't exist in that environment yet or updating it if it does. ### Built-in Call Controls **End Call**, **DTMF**, **SMS** and **Transfer Call** can be switched on as simple flags on the agent. Ellaworx adds them to the assistant's inline `model.tools` list, so no separate tool is created. ### Supported Tool Types The Ellaworx tool editor supports the Vapi tool types: **API Request**, **Function**, **End Call**, **DTMF**, **SMS**, **Transfer Call**, **Code**, **Handoff**, **Bash**, **Computer**, **Text Editor**, **Query**, **MCP**, **Google Calendar Create Event**, **Google Calendar Check Availability**, **Google Sheets Row Append**, **Slack Send Message**, and the **GoHighLevel** calendar and contact tools. > \[!IMPORTANT] > **UUIDs only:** Vapi accepts only tool UUIDs in `model.toolIds`. If a reference there can't be matched to a tool Ellaworx deploys, the deploy fails instead of quietly shipping fewer tools. Add the tool to Ellaworx, or replace the entry with the tool's Vapi UUID. --- ## Importing Existing Assistants Vapi supports [agent import](/importing-agents). Ellaworx lists the assistants in your Vapi account (up to **300**), and for each one you import: * The assistant name becomes the agent name, and a stable key is derived from it. * The `system` messages in `model.messages` become a registry prompt named `-imported-system`. * Each tool in `model.toolIds` is imported as a tool at version `1.0.0`. Secret-like server fields (tokens, auth headers) are **stripped**, and you'll see a warning. --- ## Deploy Options ### Full Deploy A full deploy sends the whole assistant configuration — model, voice, transcriber, prompts and tools — to Vapi. ### Prompt-Only Deploy Vapi supports the **Prompt only** toggle in the deploy drawer. It pushes compiled prompts and nothing else: no tools, voice, model or transcriber rewrite. Ellaworx reads the live assistant from Vapi, replaces only the system prompt and **First Message**, and writes them back, so changes made in the Vapi dashboard are kept. > \[!WARNING] > Prompt-only deploys do **not** write the analysis-plan prompts (success evaluation, structured data, summary). Knowledge-base tools stay as they were at the last full deploy. --- ## Troubleshooting & Typical Errors ### Missing API Key **Error:** `VAPI_API_KEY not set in environment or auth config` * **Fix:** Add Vapi to the target environment (or the Global environment) and select the secret holding your API key. ### Missing Assistant Name **Error:** `Invalid VAPI config: ... Top-level "name" field is required` * **Fix:** Set a top-level `name` in the agent's Vapi provider configuration. ### Unresolved Tool Reference **Error:** `model.toolIds contains unresolved tool reference(s): ...` * **Fix:** Add each referenced tool to Ellaworx so it deploys with the agent, or replace the entry with the tool's Vapi UUID. Listing it only under the agent's tools won't clear this. ### Rate Limits **Symptom:** Vapi responds with `429` (or a temporary `5xx`) during a deploy or import. * **Fix:** Ellaworx automatically retries these responses with backoff, within a 70-second budget per agent. If it still fails, wait and redeploy. ### Assistant Deleted in Vapi **Symptom:** Verification reports the agent no longer exists on the provider. * **Fix:** Remove the agent's record from that environment, or redeploy. Removing an agent that's already gone from Vapi still succeeds. --- ## Deployment Verification 1. Click **Deploy** in Ellaworx. 2. In the [Vapi Dashboard](https://dashboard.vapi.ai), find your assistant and confirm the prompt, voice and tools. 3. Enable **Drift Detection** on the environment to have Ellaworx verify deployed assistants against their expected configuration daily. Only one environment per organization can have it enabled. #### [Learn more about Deployment](/deploying-agents)