Create an enterprise and shops

How to spin up a new enterprise and its sub-teams (shops) in Avoca, and wire each shop to be call-ready. Generic procedure — same flow whether you're standing up a new real client, a test replica, an internal sandbox, or a one-off team.

The flow has two stages:

1. Create the org structure (enterprise + sub-teams). Steps 1-2.
2. Wire each sub-team to be callable (voice assistant, configuration, phone, routing). Steps 3-7.

If you only need the structure (no calls), stop after Step 2.

Step 1: create the enterprise

Use the Avoca admin's enterprise create flow. The UI exposes "enterprise" as the first-level container; in the data model an enterprise IS a team (the top-level team for its org), and sub-teams (the shops) reference it via a parent-team / enterprise-id relationship.

Required: a name for the enterprise. Conventions exist but aren't enforced — pick what makes the enterprise easy to grep for later.

Step 2: create sub-teams (one per shop)

Inside the enterprise, create one sub-team per shop / location / unit that will receive its own inbound number. Each sub-team owns its own voice assistant, prompt, configuration, and phone numbers.

The sub-team is the unit that calls land on. Five-shop enterprise → five sub-teams.

Step 3: create a voice assistant for each sub-team

Navigate to Admin → Voice Assistants in the v1 web app (https://app.avoca.ai/admin/voice-assistants) and click New.

Fill in the New Voice Assistant modal:

• Team: select the sub-team you just created. If it doesn't appear, hard-refresh (see stale-cache caveat above).
• Name: voice assistant name (typically matches the team).
• Use case: inbound for standard inbound-call assistants. (outbound and speed_to_lead are for other call patterns.)

Source: apps/web/components/admin/voice-assistants/NewAssistantModal.tsx.

Step 4: add a configuration

Open the new voice assistant and navigate to the Configurations section. Click Add Config.

This creates an assistant_configs row associated with the voice assistant. The config carries the blueprint_version_id (for MULTI_AGENT mode), tool overrides, voice/transcriber/LLM choices, and the multi-agent override JSON.

A voice assistant can own multiple configs (version history, A/B variants). The one referenced by voice_assistants.default_assistant_config_id is what gets compiled to Vapi at runtime.

Pick the config shape based on which pattern this team uses (see Legacy vs Blueprint):

• Blueprint (Multi-Agent mode): in Add Config, choose From Blueprint + Multi Agent. The Blueprint dropdown lists all Blueprints in multi_agent_blueprints. Pick one; blueprint_version_id populates with its current version. If your Blueprint doesn't appear, hard-refresh (stale-cache caveat).
• Legacy: skip the Blueprint option; configure prompt / tools / sub-agents inline on the config row. (Most new work goes to Blueprint; Legacy is only relevant if you're matching an existing Legacy client.)

Step 5: provision the inbound phone number

Navigate to Admin → Phone Numbers (https://app.avoca.ai/admin/phone-numbers) and click + Create New.

In the Purchase Number dialog:

• Enter an area code (match the team's geography if it matters; otherwise any US area code works).
• Click Search. Twilio returns available numbers in that area code.
• Pick a number and click Purchase to confirm.

The purchase action:

1. Purchases the number from Twilio (~$1/mo recurring plus per-minute usage).
2. Registers it in Vapi as a phone-number resource.
3. Inserts a row in Avoca's phone_numbers table linked to the team.
4. Configures Twilio's voice webhook to Avoca's inbound-routing endpoint.
5. Configures Vapi's server.url for tool-call dispatch.

After purchase the number is live and reachable. Direct dial works, and any test harness (e.g., Hamming) can dial it.

Source: apps/web/app/(restricted)/(protected)/admin/phone-numbers/.

Step 6: provision a test phone number (optional)

Use this if the team needs a separate Hamming-callable number for isolated test traffic. Skip if you only need the production inbound number.

On the voice assistant page, find the Advanced section. Click Provision a Test Number.

This purchases a SEPARATE Twilio number (additional ~$1/mo), registers it in Vapi, and:

• Sets is_test_phone = true on the new phone_numbers row.
• Sets voice_assistants.test_inbound_call_phone_id to the new number's ID.
• Sets the Vapi phone's server.url to include ?isTest=true&postCall=<value>, which is how the avoca-next dispatcher detects Hamming test traffic and applies tool-call mocks.
• For Blueprint (MULTI_AGENT) mode: also creates the persistent Vapi squad that Hamming's chat-bridge can target.

Cost note

Each sub-team that gets BOTH numbers (inbound + test) carries ~$2/mo recurring in Twilio rental fees plus per-minute call charges. Multiply by sub-team count when scoping.

Step 7: set up provider-agnostic routing

On the voice assistant page, click Set up for provider-agnostic routing.

The name sounds optional. It isn't. Without this, mocks, post-call workflow, and observability all skip the team.

"Provider" = the voice AI platform that runs the agent. Avoca supports Vapi (primary) and ElevenLabs (alternative). Provider-agnostic routing makes Twilio call Avoca's routing endpoint first, which then picks the provider per-call based on assistant_configs.platform.

The action (setupProviderAgnosticRoutingAction):

1. Registers the phone in Vapi (if not already).
2. Registers it in ElevenLabs (if not already).
3. Points Twilio's voice URL at AVOCA_INBOUND_VOICE_URL (Avoca's routing webhook).
4. Points Twilio's voice fallback URL at Vapi's direct webhook (safety net).
5. Points Twilio's status callback at Avoca's dispatcher.

Order matters: ElevenLabs' phone import overwrites Twilio webhook settings, so the Twilio update must run last.

Why this is effectively required

Skipping provider-agnostic routing costs you:

Lost without it	Why
Tool-call mocks	Mock interception runs in Avoca's dispatcher. Direct Twilio→Vapi routing skips the dispatcher.
Per-call platform switching	Hard-pointed Twilio webhooks lock the number to one provider.
Status callbacks to Avoca	Lifecycle events never reach Avoca's webhooks. Post-call workflow doesn't fire.
Recording / observability via Avoca	Same — nothing reaches the dispatcher.
Provider fallback safety net	Only exists if this setup ran.

For Blueprint shops (Vapi-only) the ElevenLabs registration is a throwaway side-effect, but the Twilio→Avoca wiring is still what makes mocks, post-call workflow, and observability work.

Save before navigating away

Save before navigating away

The voice-assistant admin page does NOT auto-save. You can configure inbound number, test number, provider-agnostic routing, and other settings in sequence — but if you navigate away or refresh before clicking Save, every change is lost.

Make it a routine: after every meaningful change, click Save before moving on.

CRM mapping

Wiring a CRM (AutoOps, HouseCall Pro, etc.) to each shop is a separate concern — see the relevant CRM page under /clients/avoca/crms/. The how-to above gets you a callable voice assistant; CRM mapping connects it to an external system of record.