| System | Responsibility |
|---|---|
| CXB API | Auth, bots, campaigns, calls, CRM integrations, settings, recordings, API keys, fleet routing |
| CXB Core | Live media execution: STT, LLM, TTS, tools, transfer, recordings, post-call packaging |
| CXB Console | Admin and operator interface on top of CXB API |
| CXB Dialler | Campaign pacing, SIP dial attempts, AMD screening, and attach orchestration |
Runtime Role
CXB API does not run the live audio pipeline. It prepares the information needed for the call and stores the result after CXB Core finishes.What It Owns
| Area | What CXB API owns |
|---|---|
| Auth and users | JWT login, roles, admin users, agent/supervisor access boundaries |
| Bot config | Bot CRUD, prompts, policy config, provider config, tools, transfer settings, RAG attachment |
| Runtime config | /api/v1/config/{bot_id} response consumed by CXB Core at call start |
| Calls | Call records, transcripts, events, analysis, QC, stable recording access URLs |
| Campaigns | Campaign CRUD, CSV ingestion, number pools, retry settings, attempt reports |
| Fleet routing | Health-checks CXB Core fleet servers and picks available capacity for direct dialout |
| Carriers and SIP | LiveKit trunk mapping, DID lookup, outbound trunk selection |
| CRM integrations | API-key dialout, CRM pre-fetch, post-call push, variable mapping |
| Knowledge base | Document upload, chunking, embeddings, vector-database search, bot attachment |
| Agent Desk | Queue state, timeout policy, handoff records, agent/supervisor APIs |
Important Modules
| Module | Why it matters |
|---|---|
| App entrypoint | FastAPI app, startup checks, Mongo/Redis startup, route registration, trunk health loop |
| Settings | Environment settings for MongoDB, Redis, JWT, CXB Core, LiveKit, storage, Agent Desk |
| Config route | Runtime config endpoint called by CXB Core |
| Config service | Builds the call-time config contract from stored bot/settings data |
| Results route | Receives final call results from CXB Core |
| Call service | Stores call results and sends CRM post-call payloads |
| SIP route | CRM/admin dialout endpoint and SIP lookup helpers |
| Fleet service | Fleet health checks and best-server selection |
| Campaigns route | Campaign creation, lifecycle actions, upload, reporting |
| Knowledge services | Knowledge-base ingestion, embedding, vector-database search |
| API keys route | CRM API key management |
| Agent Desk route | Agent Desk queue and handoff APIs |
API Boundaries
CXB API exposes three broad kinds of API:| API type | Used by | Purpose |
|---|---|---|
| Admin APIs | CXB Console | Bots, calls, campaigns, settings, users, carriers, knowledge bases |
| Internal APIs | CXB Core / CXB Dialler | Runtime config, SIP lookup, call result delivery, fleet checks |
| External APIs | CRMs | API-key dialout and post-call webhooks |
X-CXBCore-Secret. CRM-triggered dialout uses X-API-Key so external systems do not need admin JWTs.
Data Stores
| Store | Use |
|---|---|
| MongoDB | Durable source of truth for users, bots, calls, campaigns, settings, API keys, KB metadata |
| Redis | Runtime cache and Agent Desk state/listener support |
| Vector database | Knowledge-base vector search |
| S3 / MinIO / Spaces | Call recordings and uploaded assets, depending on deployment |
Operational Checks
When debugging CXB API, start with the surface that owns the failing state:| Symptom | First place to check |
|---|---|
| CXB Core cannot fetch config | Bot status, active hours, the config route, the config service |
| Direct dialout picks the wrong worker | cxbcore_fleet settings and the fleet service |
| Campaign rows do not progress | Campaign status, dialler health, campaign_calls indexes, CXB Dialler logs |
| Call result missing | CXB Core result outbox, the results route, call storage logs |
| CRM did not receive result | Integration config, the call service, post-call push logs |
| Recording does not play | recording_key, recording access token, storage settings, fleet recording backend |
| RAG answer is wrong | KB attachment, document status, vector-database collection, trigger instructions |
Engineering Rules
- Keep live media logic out of CXB API. That belongs in CXB Core.
- Keep durable business state out of CXB Core. That belongs in CXB API and MongoDB.
- Do not expose raw recording URLs to CRMs when stable CXB API recording links are available.
- Do not hard-code client-specific behavior in shared API code; use bot config, system settings, brand config, or integration config.
- Protect production startup with real
JWT_SECRETandCXBCORE_SECRETvalues.
Related Docs
Architecture
How the four services fit together.
Call lifecycle
How a call moves through CXB Core and CXB API.
Services and boundaries
Ownership rules and key modules for each service.
CRM dialout API
How external systems trigger calls through CXB API.