Developer Documentation
Production-ready voice agents with sub-second latency, reliable tool calling, and bidirectional app communication. No infrastructure to manage.
Real-time voice over WebRTC with optimized STT/TTS pipelines.
Bidirectional: agent drives your UI, app sends events back.
Native connectors, MCP servers, HTTP APIs, or 7,000+ apps via Zapier.
Web, mobile, or phone from a single config.
Real-time streaming out of the box. Zero setup.
Synthetic Simulation calls, Post evals, recordings, transcripts, and retained evidence.
Quick Start
Go from zero to a working voice UI in under an hour.
Create a free account, configure your voice agent with a system prompt, and get a phone number and API key in minutes.
Create accountYour backend proxies a single API call to generate short-lived connection tokens. Keep your API key server-side.
# Your backend endpoint
curl -X POST "https://vocalbridgeai.com/api/v1/token" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"participant_name": "User"}'Pick your framework, install, and connect in a few lines. Audio, transcripts, and heartbeats are handled automatically.
npm install @vocalbridgeai/sdkimport { VocalBridge } from '@vocalbridgeai/sdk';
const vb = new VocalBridge({
auth: { tokenUrl: '/api/voice-token' },
participantName: 'User',
});
// Live transcript streaming
vb.on('transcript', ({ role, text }) => {
console.log(`[${role}] ${text}`);
});
// Handle agent-triggered actions
vb.on('agentAction', ({ action, payload }) => {
handleAction(action, payload);
});
await vb.connect();
// Mic is live. Agent audio plays automatically.npm install @vocalbridgeai/reactimport { VocalBridgeProvider, useVocalBridge, useTranscript }
from '@vocalbridgeai/react';
function App() {
return (
<VocalBridgeProvider
auth={{ tokenUrl: '/api/voice-token' }}
participantName="User">
<VoiceUI />
</VocalBridgeProvider>
);
}
function VoiceUI() {
const { state, connect, disconnect } = useVocalBridge();
const { transcript } = useTranscript();
return (
<div>
<button onClick={state === 'connected' ? disconnect : connect}>
{state === 'connected' ? 'End Call' : 'Start Voice Chat'}
</button>
{transcript.map((e, i) => (
<p key={i}><b>{e.role}:</b> {e.text}</p>
))}
</div>
);
}# Xcode package dependencies
https://github.com/vocalbridgeai/sdk.git
product: VocalBridge
branch: main
commit Package.resolvedFetch short-lived voice tokens from an authenticated backend route; do not embed API keys in production iOS apps.
import VocalBridge
let vb = VocalBridge(options: .init(
auth: .tokenURL(URL(string: "https://example.com/api/voice-token")!),
participantName: "User",
debug: true
))
let subscription = vb.onEvent { event in
switch event {
case .transcript(let entry):
print("[\(entry.role.rawValue)] \(entry.text)")
case .agentAction(let action):
print("Action:", action.action, action.payload)
default:
break
}
}
try await vb.connect()
try await vb.sendAction("user_clicked_buy", payload: ["productId": "123"])
try await vb.toggleMicrophone()
await vb.disconnect()
subscription.cancel()Use the Vocal Bridge CLI to review call logs, save candidate versions, and deploy them independently across environments. See Versions & Environments for CLI and API examples.
# Install
pip install vocal-bridge
# Authenticate
vb auth login
# Review call logs and transcripts
vb logs
# Save a candidate without changing production (prepare candidate.json first)
vb agent version save --config-file candidate.json --label candidate
vb agent version deploy candidate --environment staging
# Evaluate a call against an objective (Pilot only)
vb eval <session_id> --objective "Schedule a meeting"
# View full integration docs
vb docsKey Feature
Bidirectional communication between your voice agent and your app. The agent can drive your UI, and your app can notify the agent.
The agent triggers actions in your UI during conversation.
vb.on('agentAction', ({ action, payload }) => {
if (action === 'show_product') {
showProductCard(payload.productId);
}
if (action === 'navigate') {
router.push(payload.path);
}
});Your app sends events to the agent to keep it in context.
// User clicked a buy button in your UI
await vb.sendAction('user_clicked_buy', {
productId: '123',
quantity: 2
});
// Agent responds: "Great choice!"Handle agent-triggered actions with a hook.
import { useAgentActions } from '@vocalbridgeai/react';
function VoiceUI() {
useAgentActions((action, payload) => {
if (action === 'show_product') {
showProductCard(payload.productId);
}
if (action === 'navigate') {
router.push(payload.path);
}
});
// ...
}Send events to the agent from any component.
import { useVocalBridge } from '@vocalbridgeai/react';
function BuyButton({ productId }) {
const { sendAction } = useVocalBridge();
return (
<button onClick={() =>
sendAction('user_clicked_buy', {
productId, quantity: 1
})
}>Buy Now</button>
);
}
// Agent responds: "Great choice!"
Configure client actions from the dashboard or via vb config set --client-actions-file actions.json. Each action has a name, description, and direction. See the full developer guide for the complete reference.
Bring Your Own Agent
Already have a chatbot, RAG system, or LLM agent? Give it a voice. Vocal Bridge handles the real-time voice layer while your existing agent handles domain logic.
import { VocalBridge } from '@vocalbridgeai/sdk';
const vb = new VocalBridge({
auth: { tokenUrl: '/api/voice-token' },
});
// One callback — SDK handles the rest
vb.onAIAgentQuery(async (query) => {
// Forward to your existing agent
const answer = await yourAgent.ask(query);
return answer; // spoken back to the user
});
await vb.connect();import { useAIAgent } from '@vocalbridgeai/react';
function MyApp() {
// One hook — queries are forwarded automatically
useAIAgent({
onQuery: async (query) => {
const answer = await yourAgent.ask(query);
return answer; // spoken back to the user
},
});
return <VoiceUI />;
}
How it works: User speaks → voice agent determines domain question → calls your hosted endpoint or sends query_agent via data channel → your agent answers → response is spoken back. Use the full dashboard Test tab to hear this flow with Haiku standing in for your agent.
Passive Observer Mode
A Vocal Bridge agent that never speaks. It joins a session, transcribes multi-speaker audio with speaker diarization, and streams real-time coaching suggestions to your app via the data channel.
vb agent create --style Listener or pick "Listener" in the dashboard
import { VocalBridge } from '@vocalbridgeai/sdk';
const vb = new VocalBridge({
auth: { tokenUrl: '/api/voice-token' },
});
vb.on('agentAction', ({ action, payload }) => {
switch (action) {
case 'live_transcript': {
const { speaker_id, text, is_final } = payload;
if (is_final) appendFinal(speaker_id, text);
else updateInterim(text);
break;
}
case 'coaching_suggestion':
// payload.guidance is Markdown — render with any renderer.
renderCoachingCard(payload);
break;
case 'speaker_map_update':
// payload.mapping = { S0: {name, org, role, confidence}, ... }
refreshSpeakerLabels(payload.mapping);
break;
}
});
await vb.connect();import { useAgentActions } from '@vocalbridgeai/react';
function ListenerUI() {
useAgentActions((action, payload) => {
if (action === 'live_transcript') {
const { speaker_id, text, is_final } = payload;
if (is_final) appendFinal(speaker_id, text);
else updateInterim(text);
} else if (action === 'coaching_suggestion') {
renderCoachingCard(payload);
} else if (action === 'speaker_map_update') {
refreshSpeakerLabels(payload.mapping);
}
});
return <YourTranscriptAndCoachingPanels />;
}
Your custom_prompt drives both when coaching fires and what it says. See the full developer guide for the complete action schemas, prompt design patterns, and how to ground coaching in your own data via MCP.
Developer Tools
npm install @vocalbridgeai/sdk
Connect, stream transcripts, send/receive client actions, and manage audio. Works in any JS environment.
npm install @vocalbridgeai/react
React hooks and Provider. useVocalBridge(), useTranscript(), and useAgentActions() for idiomatic React.
VocalBridge
Swift package for native iOS apps: token auth, connection lifecycle, microphone controls, transcripts, and client actions.
pip install vocal-bridge
Manage agents, review call logs, download recordings, update prompts, and access the full developer docs with vb docs — all from your terminal.
Native slash commands inside Claude Code. Manage your agent, stream debug events, and update configs without leaving your AI assistant.
# Claude Code
/plugin marketplace add vocalbridgeai/vocal-bridge-marketplace
/plugin install vocal-bridge@vocal-bridge
# Or via npx
npx skills add vocalbridgeai/vocal-bridge-claude-pluginAlso supports Flutter/Dart and Kotlin (Android) via WebRTC SDKs. See the full developer guide for platform-specific instructions.
Save version does not deploy. Saving updates the editable configuration and records an immutable snapshot. Deploy selects a saved version for one named environment, without changing the editable configuration or other environments. Keep production on v1 while staging tests v2, then promote the same tested version. Vocal Bridge manages platform updates; you manage your agents through the dashboard, CLI, or API. Existing agents keep working without any setup changes.
In the dashboard, choose Save version and review the diff against the latest saved version. In Versions, choose Deploy, select the environment, and review its currently deployed version versus the candidate. Select the deployed environment in the test panel. To stop one environment without deleting saved versions, choose Undeploy beside it and review the impact.
Deployment previews are bound to the reviewed target. Changing the environment or display name requires a new diff review, even while a previous request is loading. Closing and reopening the dialog discards that review. Confirmation submits the reviewed agent, immutable version, environment, display name, and expected current deployment; target inputs stay locked during deployment. API clients must retain the same environment and display name between preview and deploy. The CLI retains its selected target while previewing and confirming.
Changing the dashboard environment slug loads that target's existing friendly name, including a custom production name. A new target starts with a blank optional name so the server derives it from the slug. Select the slug before entering a rename. CLI/API clients can omit --display-name / display_name to preserve an existing name or derive a new one; an explicit name intentionally renames that environment.
The public deploy-preview API accepts display_name and returns the effective post-deploy label in environment.display_name, without creating or renaming an environment. Send the same target payload to preview and deploy. Omitted, null, or empty-string display names preserve an existing name or derive a new one; invalid display names are rejected during preview as well as deployment. Environment metadata is separate from the immutable agent configuration, so a label-only rename can have zero configuration changes in the diff.
Echo top-level preview expected_display_name unchanged to deploy, including null for a new environment, alongside expected_deployed_version_id. It contains the stored name before the proposed rename; concurrent same-version renames return 409. Omission retains older clients' version-only guard. Dashboard and CLI send both fields automatically.
Connector ownership transfer: connected accounts move with the agent, and the recipient gains control of those connections. Authorization attempts that were not completed before transfer must be restarted by the recipient. Disconnect before transfer if a connected account must not move.
Existing connection grants, scopes, provider account identity, snapshots, and deployments are preserved. Operations already accepted by an external provider may finish; transfer does not cancel remote requests or transfer ownership of the external account. Revocation affects every environment sharing that connection.
API keys are revoked on ownership transfer. Existing agent-scoped keys stop authorizing new requests after the transfer completes. The recipient must mint fresh keys and update integrations/CLI login. Untransferred agents, account keys, saves/deploys/rollbacks, and same-owner updates keep their keys. Failed transfers roll back revocation; already-issued connection tokens and active calls are not cancelled.
The former owner remains an Admin collaborator, preserving the established contract. Transfer changes ownership and billing; it is not a clean access hand-off. The recipient must remove that access separately and review other collaborators, shared links, and external OAuth grants.
Creation and transfer share the same logical-agent limit (plan plus partner agent slots), separate from phone-environment capacity. Versions and environments remain one logical agent. If concurrent requests compete for the final slot, one returns 403 without creating or transferring an agent. Pending and failed non-deleted agents count; deleted agents do not. Existing over-limit agents and deployed versions remain unchanged.
Exports and save/deploy diffs redact recognized credential fields, including bot_token, provider_token, and X-Auth-Token. The CLI also masks known secret paths and escapes terminal controls. Keep free-text labels/prompts free of secrets and exports private.
Keep exported configuration private. Redaction does not remove secrets from older downloads or revoke credentials. Rotate any exposed credentials, then save and deploy a new configuration; version history is immutable.
POST /api/v1/token requires an API key. Its optional environment is a trusted server-side selector, not an anonymous-browser authorization boundary. Customer token proxies must authorize callers, allowlist input fields, and set a fixed server-owned environment; never forward untrusted JSON wholesale. Public shared links stay production-only. Use separate agents/accounts for separate access boundaries.
Version requests are rate limited. Handle 429 with backoff and obtain fresh state before retrying; preview endpoints are not intended for bulk export.
Existing deployed agents keep their current connections and running calls. Saving a candidate does not revoke credentials or redeploy production. Use separate agents and sandbox credentials when test calls need independent external access.
Outbound consent does not transfer. An ownership change removes the logical agent's prior consent across all environments. The recipient must explicitly accept the Outbound Calling Terms of Use before starting new outbound calls. Restoring or deploying an older version cannot restore consent.
In the dashboard, accept the outbound terms and Save version. CLI users can run vb agent version save --config-file outbound-candidate.json --accept-outbound-tos. Public API clients send outbound_tos_accepted: true to POST /api/v1/agent/versions. Saving acceptance does not deploy. If the deployed version already enables outbound calling, new calls can resume after acceptance, subject to the recipient's existing usage limits and entitlements. --yes alone is not consent.
Untransferred agents and same-owner updates retain their acceptance. Transfer does not change snapshots, deployment pointers, phone resources, or inbound/web availability, and does not terminate already-admitted calls. A failed transfer rolls back the consent reset along with ownership.
Only the current owner can accept new outbound terms. Edit/Admin collaborators, including a former owner retained as Admin, cannot record outbound_tos_accepted: true on the owner's behalf: fresh attempts return 403 before saving. This restriction also applies if ownership changes during the request. Existing owner consent remains valid: older dashboards echoing true can keep editing, without replacing the first acceptance timestamp. Ordinary collaborator saves without new acceptance remain supported. Legacy API/classic edits enforce the same ownership checks. Consent is shared agent policy, not version configuration.
Creation and transfer share the same logical-agent limit (plan plus partner agent slots), separate from phone-environment capacity. Versions and environments remain one logical agent. If concurrent requests compete for the final slot, one returns 403 without creating or transferring an agent. Pending and failed non-deleted agents count; deleted agents do not. Existing over-limit agents and deployed versions remain unchanged.
Saving a version that newly enables outbound calling requires the current owner's plan or a partner outbound grant, even for a web-only candidate. Telephony access and accepted terms do not grant outbound access.
The dashboard and public version API return a client error when that allowance is missing. Denied saves do not record consent, change the draft, create a version, or deploy.
Existing outbound-enabled configurations can still be saved or edited after a downgrade; disabling outbound does not require outbound entitlement. New calls remain subject to runtime entitlements and usage limits. Restoring an older snapshot cannot bypass the check when it newly enables outbound.
Explicit version deployment of a phone/both snapshot with outbound enabled rechecks the current owner's outbound plan/grant and accepted terms. Both version-deploy APIs return 403 before provisioning when either is missing. Save owner consent first, or save and deploy a version with outbound disabled. Existing deployments, inbound/web availability, and legacy save/redeploy contracts are unchanged; runtime call gates still apply.
production. Legacy PATCH /api/v1/agent, vb prompt set/edit, and vb config set/edit still save and deploy to production. Do not use them to prepare a staged-only candidate. Existing token clients still default to production; agent identity and API keys stay the same.
Legacy updates still save and deploy, but now return 409 Conflict if another editor saves after the source draft was read. Refresh and review before retrying; the newer draft and live production stay intact. This also applies when restoring production phone resources.
With Save version or vb agent version save, explicit outbound consent and the version save succeed together. If acceptance cannot be recorded, the version is not saved and your existing configuration stays unchanged. The first acceptance timestamp is preserved; saving an unchanged configuration can record consent without a duplicate version. Preview never records consent. Legacy save-and-deploy may retain accepted consent even if deployment fails.
Each agent can have 50 environments total, including production, independently of the owner-wide phone quota. Web-only, failed, inactive, and pending environments all count. Reuse stable names such as qa or staging; avoid a new slug for every build. A new environment beyond the cap returns 403 before allocation. Existing deployments, including installations already above the cap, remain available and can be redeployed. Undeploy releases one environment's runtime resources but keeps its record, deployment audit, and saved versions.
Version descriptions reject terminal controls, including ANSI/OSC escapes; printable Unicode, newline, and tab remain supported. The CLI escapes controls in older stored notes. Deployment display_name must be a string or null, with at most 100 printable characters. Invalid metadata returns a client error, not a server error.
Requires CLI 0.27.0+. Authenticate with vb auth login; select an agent with vb agent use AGENT_UUID for account keys. VOCAL_BRIDGE_API_URL chooses the Vocal Bridge API endpoint; --environment chooses a deployment within your agent. Changing environments does not require changing your API endpoint.
Create candidate.json with your changes. This web-only example avoids provisioning a test phone number:
{
"greeting": "Hello from the release candidate.",
"custom_prompt": "You are a helpful support assistant.",
"deploy_targets": "web"
}vb agent version list
vb agent environment list
vb agent version save --config-file candidate.json --label rc-2 --description "Ready for QA"
vb agent version diff 1 rc-2
vb agent version show rc-2 --json
vb agent version restore 1 --label restored-v1
vb agent version deploy rc-2 --environment staging --display-name Staging
# After QA: use the actual immutable version number from save/list.
vb agent version label rc-2 approved --description "QA passed"
vb agent version deploy 2 --environment production
# Roll back production; staging and version history are unchanged.
vb agent version deploy 1 --environment production
# Stop staging without deleting versions or changing production.
vb agent environment undeploy stagingSave/deploy/undeploy preview the change and require confirmation. Without a terminal, supply --yes. --json suppresses the printed preview and returns only the final response; it does not bypass confirmation. There is no CLI --dry-run: cancel the preview or use the preview API. A no-change save may reuse the latest version (created: false); use the returned ID.
Every version and environment command supports --json. versions/environments are aliases. Use vb agent version restore REF to preview and save an older snapshot as a new immutable version without deploying it. Omit the label in vb agent version label REF to clear it. Omit --config-file to snapshot the saved editable configuration, not unsaved browser changes. Deploy defaults to production if the environment is omitted; undeploy requires an explicit environment.
In the dashboard, Versions → View displays a historical snapshot (edit access required; view-only collaborators see the history, not each version's configuration) and Open as editable draft loads it into the editor. Saving creates a new version and leaves every environment unchanged. Overview and Versions pair each active phone number with its deployed immutable version and environment.
When first enabling outbound calling in a phone-enabled candidate, use vb agent version save --config-file outbound-candidate.json --accept-outbound-tos to accept the Outbound Calling Terms of Use. This saves only; deploy separately. API clients send outbound_tos_accepted: true in the save body. --yes alone does not accept outbound terms.
CI/CD: retain an approved immutable UUID and run vb agent version deploy VERSION_UUID --environment production --yes --json after your approval step. Labels can change; UUIDs and version numbers cannot. A nonzero exit needs inspection before retry.
Call https://vocalbridgeai.com/api/v1 from your backend with X-API-Key and JSON Content-Type. Account keys also require X-Agent-Id: AGENT_UUID; agent-scoped keys do not. REF accepts a UUID, version number, or case-insensitive label; URL-encode path references.
| Method / endpoint | Request and response |
|---|---|
GET /api/v1/agent/versions | versions, environments, and latest 50 deployments audit entries. |
POST /api/v1/agent/versions/preview | config, optional full_snapshot/source_version_id → base_version, next_version_number, changes, summary. No mutation. |
POST /api/v1/agent/versions | Same config fields plus optional label, description, expected_latest_version_id, outbound_tos_accepted → version, changes, summary, created, deployed: false. |
POST /api/v1/agent/versions/diff | {"from":"1","to":"rc-2"} → from_version, to_version, changes, summary. |
GET /api/v1/agent/versions/REF | version with redacted config. |
PATCH /api/v1/agent/versions/REF | label and/or description → updated metadata. Null clears; omitted fields stay unchanged. |
POST /api/v1/agent/versions/REF/deploy-preview | environment, optional display_name → environment with the effective post-deploy label, stored expected_display_name, from_version, to_version, changes, summary. No mutation. |
POST /api/v1/agent/versions/REF/deploy | environment, optional display_name, expected_deployed_version_id, expected_display_name → version, environment, deployment, changes, summary. |
POST /api/v1/agent/environments/ENVIRONMENT/undeploy-preview | No body → current environment/version, resource and sharing impact, changes, and expected_deployed_version_id, expected_deployment_status, expected_updated_at. On an inactive or failed environment with retained resources it previews cleanup with a null version expectation. needs_operator_reconciliation marks retained capacity that no retry can release; contact support instead of retrying. No mutation. |
POST /api/v1/agent/environments/ENVIRONMENT/undeploy | Echo all three preview expectations → inactive environment, undeploy audit, prior version, and cleanup_pending. Only the agent owner can undeploy an environment whose preview reports phone_will_be_released or telephony_reservation_will_be_stranded; an Admin collaborator gets 403. API keys are issued only for agents you own. |
Public version operations return HTTP 200 on success. Version summaries include id, version_number, label, description, source, and creator/timestamp metadata. Changes contain path, kind (added/removed/changed), before, and after; summary.change_count counts changes.
Use these documented /api/v1 routes for CLI and external automation. Dashboard access follows the agent's existing collaborator permissions; test-only collaborators can select active environments but cannot read full version configurations.
Version history defaults to 50 rows per page. Use API limit (1–100) and before_version, or CLI --limit and --before-version. Follow pagination.next_before_version until null. The dashboard has Older versions / Newer versions controls. Deployed summaries remain visible on every page; old versions are not pruned.
config to POST /api/v1/agent/versions/preview. Review the diff against the latest saved version.POST /api/v1/agent/versions with expected_latest_version_id set to the preview's base_version.id. Retain the returned version.id.{"environment":"staging","display_name":"Staging"} to that immutable version's /deploy-preview. Review the diff against the version deployed to staging and its effective post-deploy label./deploy with expected_deployed_version_id from the preview's environment.deployed_version_id. For a new environment, send explicit null; omitting the field skips the preview-to-deploy comparison.If a label was previewed, deploy its returned to_version.id so relabeling cannot change the approved target. Existing agents have a baseline v1. If state changes after preview, the write is rejected so you can review a fresh diff.
{
"environment": "staging",
"display_name": "Staging",
"expected_deployed_version_id": null
}The null above is for a new environment only; for an existing deployment use the ID from its preview. On 409 Conflict, inspect state, wait for any in-progress deployment, and obtain a fresh preview and approval. Do not silently retry or remove the expectation.
Undeploy has a separate read-only preview. Echo its expected_deployed_version_id, expected_deployment_status, and expected_updated_at to confirmation. It deactivates the selected environment before retiring phone/routing resources, so new sessions fail closed even if cleanup must be retried. For phone and both targets, redeploy may provision a different phone number because a retired number is not guaranteed to be available again. If cleanup_pending is true, run the same preview-and-confirm flow again; inactive or failed cleanup previews return a null version expectation, and retrying an inactive environment does not create another undeploy audit. Only the agent owner can undeploy an environment that releases its phone number, or one whose preview reports telephony_reservation_will_be_stranded: an Admin collaborator receives 403 and the dashboard control is disabled with that reason, because both outcomes are irreversible and spend capacity from the owner's telephony quota. The second flag marks an undeploy that cannot prove the reserved telephony slot is unused, so the slot stays held until support reconciles it and no cleanup retry can release it. An Admin can still undeploy a web-only environment. Versions, other environments, collaborator access, and sharing settings remain unchanged. Undeploying production stops new public talk-link sessions until production is deployed again; configuration-share links remain available.
curl --fail-with-body -X POST "https://vocalbridgeai.com/api/v1/token" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-Agent-Environment: staging" \
-H "Content-Type: application/json" \
-d '{"participant_name":"QA tester","environment":"staging"}'Add X-Agent-Id for account keys. The response includes environment, version_id, and version_number alongside the usual token fields. Your SDK still consumes the normal token response; no SDK environment flag is required. Authorize environment selection in your backend and keep keys server-side.
Missing/inactive named environments fail instead of falling back to production. Omitting environment keeps the production default. This selector applies to web-token calls; do not assume outbound-call APIs accept it.
Agent-specific integration guides describe the version deployed to production, not the saved draft. Dashboard copy/preview and vb docs / GET /api/v1/docs follow the same contract. Deploy to production and refresh the guide after changing modes, tools, or client actions. Account-key docs without a selected agent remain generic. Guides do not select a named environment, even when the tester is set to staging; inspect that environment's deployed snapshot separately.
vb debug and vb debug --poll use production's deployed debug_mode. Saving an enablement or disablement does not change access until deployment. Existing owner/admin and API-key permissions still apply. Debug streams and stored events remain agent-wide rather than environment-specific.
If production is inactive or unavailable, guide and debug requests fail without exposing the saved draft. Reading these guides does not change versions, deployments, phone resources, keys, or billing.
full_snapshot and outbound_tos_accepted must be JSON booleans, not strings, numbers, or null. Omission defaults to false. "full_snapshot": false preserves partial model-setting merges; "full_snapshot": "false" is rejected. Only explicit true records new outbound consent; previously accepted consent remains valid. CLI flags already send booleans. Invalid flag types are rejected before saving or recording consent.custom_prompt / mode, not legacy prompt / style. Omitted fields stay unchanged. Partial model_settings groups merge; other supplied fields and arrays replace their old values.vb agent version restore 1 --label restored-v1. Direct API clients first fetch GET /api/v1/agent/versions/REF, then send the complete returned version.config, full_snapshot: true, and source_version_id: version.id to both preview and save, with the preview's base version as expected_latest_version_id. This replaces model settings, restores redacted credentials from the selected snapshot, creates a new immutable version, and never deploys automatically.__VB_SECRET_KEPT__ placeholders intact. Diffs redact secrets, but prompts/config exports can still contain sensitive business information. Protect exported files and review artifacts.api_tools[].url) are fully redacted in CLI/API-key exports, all dashboard historical-version reads, and every version/deployment diff, including older stored audits. This covers userinfo, arbitrary query credentials, and opaque path tokens, even on ordinary endpoint URLs. Preserve each tool's stable id (or name for older snapshots): reordered tools restore their own URL from source_version_id; an explicit replacement URL is honored. Live execution, stored snapshots, and access to the current editable configuration are unchanged. Previously downloaded artifacts are not retroactively redacted; rotate any credentials exposed in them.[a-z0-9][a-z0-9_-]{0,62}. Friendly display_name allows 100 characters. First deploy creates the environment; preview does not.Versions share one logical agent and owner account. Saving and labeling do not consume agent slots, provision phones, or create billable calls. Test calls are real usage, including web-only QA calls. Production, staging, shared links, and collaborator calls use the owner's allowance.
min(plan agent limit + partner agent slots, 50) reservations. Production and staging phones use two slots; redeploying the same environment reuses one. Legacy phone creation/retry uses the same pool. Web-only environments reserve no phone slot, but calls still use minutes.vb agent environment list or GET /api/v1/agent/versions; the billing page counts logical agents, not phone reservations.vb config set --deploy-targets phone (or both) provisions the missing phone/dispatch before publishing production. Current owner entitlement and shared phone capacity, including partner slots, apply; denial returns 403. A retired number is not guaranteed to return. Existing phone resources are reused when present; named environments are unchanged. A failed deployment can leave the new snapshot saved while production stays on its prior version; inspect history before retrying after a timeout. Concurrent changes require refresh/retry. Ordinary edits to an already complete phone deployment do not buy another number.session_id is reused. Version changes do not disconnect active calls. Issued tokens are not cryptographically revoked, but admission rejects new sessions for inactive environments.vb docs or GET /api/v1/docs.400: invalid config, label/reference, environment, or missing outbound acceptance. 401/403: credentials, access, or deployment entitlement/capacity. 404: agent/version lookup failed. 409: stale preview or concurrent deployment. 429: rate limit; back off, then refresh the preview. Dashboard schema validation can return 422.
For 500 or network timeouts, inspect GET /api/v1/agent/versions, environment status, and deployment history before retrying. An error response is not proof that external resources were unchanged. Read the JSON detail for the specific failure.
Get the full copyable backend workflow and integration reference with vb docs or GET /api/v1/docs.
The full developer guide covers API reference, authentication details, all SDK methods, AI Agent mode, native connectors, MCP tools, post-processing, and more.
vb docs
Create your free account, deploy an agent, and integrate it into your app. No credit card required.