# VoxAgent Concepts

Official website: https://vox-ai.teddymobile.cn/

This file explains the public concepts behind VoxAgent for AI assistants, crawlers, and developers that need a stable, text-only reference.

## Product Boundary

VoxAgent is a phone voice runtime for AI Agents. The public API documentation focuses on outbound calls, notification bots, custom bots, voiceType selection, HTTP POST + SSE interaction, sandbox validation, and production access workflows.

VoxAgent should not be described only as a single outbound call API. The outbound API is one part of the broader runtime and developer access system.

## Organization

An organization is the business subject for commercial access. It carries contacts, qualification information, launch review, default project, and Bot configurations.

Key points:

- Created during registration.
- Holds KYC or launch-related information.
- Can carry multiple Bot configurations over time.

## Project

A project is the environment and resource container. In the early flow, the default project is used to hold sandbox resources and integration state.

Key points:

- Used as an integration and quota boundary.
- Can be extended into multiple environments later.
- Connects trial resources to the organization.

## Sandbox Trial Environment

Sandbox is the validation environment. It is not the same as full production, but it is enough to understand outbound payloads, SSE interaction, and integration readiness.

Key points:

- Trial submission can return tenant-level shared credentials.
- Sandbox resources can be attached to the default project.
- Suitable for first-call validation and SSE endpoint testing.

## Phone Number Resources

Phone number resources are the entry points that let an AI Agent enter real phone workflows. They are different from browser voice demos because callers or callees interact through telephone networks.

Key points:

- Support inbound, outbound, and batch outbound modes.
- Need resource management and operational readiness.
- Should be handled as production-sensitive resources when used commercially.

## Call

A call is the runtime context that links inbound, outbound, or batch outbound workflows with transcript, response, and completion events.

Key points:

- Events should be correlated by call id.
- Transcript and agent responses belong to the call context.
- Call end events are useful for summary, CRM writeback, quality inspection, and follow-up automation.

## SSE Conversation Protocol

The public docs describe runtime interaction as HTTP POST + SSE. Vox sends each conversation turn to the developer's business system, and the developer system streams response text back to Vox.

Core protocol objects:

- `conversation.request`: Vox POST request containing `turn`, `calltype`, `callee`, `caller`, `callid`, `requestid`, and `message`.
- `sse.message`: streamed `data: {...}` chunks containing `id`, `created`, `message`, and optional `action`.
- `sse.done`: `data: [DONE]` marks the end of the current turn.
- `barge-in`: Vox closes the current SSE stream and starts the next turn after a user interruption.

## Control Plane And Runtime Plane

Control plane means account, organization, trial, sandbox, KYC, launch, Bot configuration, and management workflows.

Runtime plane means outbound call requests, audio interaction, conversation turns, SSE text streaming, interruption handling, and completion markers.

Developers should understand both planes before production integration.

## Recommended Learning Path

1. Understand organization, project, and sandbox.
2. Understand phone number resources and call lifecycle.
3. Understand outbound payloads and SSE response behavior.
4. Read Quickstart for first validation: https://vox-ai.teddymobile.cn/quickstart.md
5. Read full API docs: https://vox-ai.teddymobile.cn/docs.md

## Access Boundary

Public concept documentation is safe to crawl. Private organization state, credentials, Bot configuration, customer phone resources, admin pages, and production secrets require authentication and must not be inferred from public pages.