Core Concepts

Understanding the key building blocks of VOCALS.

Tenants

A tenant is an isolated workspace in VOCALS. Each tenant has its own:

• Providers (API keys and configurations)
• Agents (AI phone agents)
• Phone numbers
• Call logs and analytics
• API keys and webhooks

Users belong to a tenant via membership. VOCALS supports multiple tenants, each with isolated data and configuration.

Agents

An agent is an AI-powered phone assistant configured with:

• System prompt — Instructions defining the agent's personality and behavior
• Providers — Which STT, LLM, and TTS services to use
• Welcome message — Optional greeting played at the start of each call
• Language — The language the agent speaks
• Barge-in sensitivity — How sensitive the agent is to the caller interrupting (very_low/low/medium/high/very_high)
• Max call duration — Automatic hang-up after a set time

Each phone number is assigned to one agent.

Providers

VOCALS uses a provider abstraction layer — each stage of the voice pipeline (STT, LLM, TTS) can use any supported provider. This allows you to:

• Mix providers (e.g., Deepgram for STT + Anthropic for LLM + ElevenLabs for TTS)
• Switch providers without code changes
• A/B test different provider combinations

Supported providers

Type	Providers
STT	Deepgram, ElevenLabs, OpenAI Whisper, Alibaba Qwen, Fish Audio
LLM	OpenAI, Anthropic Claude, Google Gemini, Moonshot Kimi
TTS	ElevenLabs, OpenAI TTS, Resemble AI, Fish Audio

The Voice Pipeline

Every call flows through a three-stage pipeline:

1. STT (Speech-to-Text) — Caller audio is streamed via WebSocket to the STT provider, which returns text transcripts in real-time
2. LLM (Language Model) — The transcript and conversation history are sent to the LLM, which generates a response as a stream of tokens
3. TTS (Text-to-Speech) — Response text is synthesized into audio and streamed back to the caller

The pipeline processes each stage in a streaming fashion for minimal latency. Sentence boundaries are detected during LLM streaming so that TTS can start before the full response is generated.

Barge-in

Barge-in allows callers to interrupt the agent mid-sentence. When voice activity is detected during TTS playback, the agent stops speaking and listens to the caller. This is controlled by the agent's barge-in sensitivity setting.

Sessions

Each active call has a session stored in Redis containing:

• Call metadata (SID, direction, phone numbers)
• Conversation history (user and assistant messages)
• Provider usage and timing metrics

When a call ends, the session is persisted to PostgreSQL as a call log for long-term storage and analytics.

Webhooks

VOCALS can notify your application of events via webhooks:

• call.started — A call has connected
• call.ended — A call has completed
• call.failed — A call encountered an error
• transcript.ready — A conversation transcript is available

See Webhooks for configuration details.

Knowledge Base

Agents can be augmented with a knowledge base — a collection of text entries that provide reference information the agent can draw on during conversations. This is useful for FAQs, product details, pricing, or any domain-specific content the agent should know without embedding it all in the system prompt.

Entries can be added from raw text, a web URL, or an uploaded document, and are managed programmatically via the Knowledge Base API.

Teams

VOCALS supports team collaboration within a tenant. Tenant owners can invite team members via email, and each member gets access to the shared workspace. Team size limits depend on your subscription tier. See Billing for details on tier limits.

Deleting things

Deleting is permanent. There is no undo and no recycle bin, so every Delete action in the dashboard opens a confirmation dialog first. The dialog names the exact item you are about to remove, for example Delete provider "Deepgram"?, so you can check you picked the right row before confirming.

For the deletions with the widest impact - an agent, a SIP provider, or a tenant - the dialog also asks you to type the item's name before the delete button becomes active.

A few things are worth knowing before you confirm:

• Providers: the stored API key is never shown back to you, so recreating a deleted provider means entering the key again. Agents using it stop working until you do.
• Agents: the agent, its knowledge base, and its phone number assignments go with it. Calls already logged are kept.
• SIP providers: calls stop being routed through that connection, and its phone numbers are released from their agents.