Object model

Everything in Voicebot hangs off a two-level ownership chain.

Tenant                      ← you, as our customer
├── Tenant administrator    ← holds the tenant API key
├── Trunk                   ← the voice path to your telephony
└── Account                 ← a unit inside your organisation
    ├── User                ← a person who signs in
    ├── Number / Pool       ← numbers this account may dial from
    ├── Scenario            ← call flow definition
    ├── Agent               ← a scenario bound to a number and a schedule
    └── Communication       ← one dialable unit: one recipient, one run

Tenant

The top-level container. In a cloud deployment there are many tenants on one installation and they are fully isolated from each other. In an on-premises deployment there is normally one.

A tenant is issued by us, never self-created. The endpoints live on the Tenant API, which is reachable only from the internal network.

POST/v1/internal/tenant
POST/v1/internal/tenant/{sid}/api-key

Account

A unit inside your organisation: a department, a brand, a region or a client of yours. Accounts are where all the day-to-day work happens, and they are the isolation boundary for scenarios, numbers and call data.

This is the entity your system mirrors: when a unit appears on your side, an account appears on ours.

POST/v1/internal/account
GET/v1/internal/account

Caution

Account creation is on the Tenant API. An account-level key cannot create accounts. That would let a unit create its own siblings. If you get a 403 here, you are holding the wrong key.

User

A person who signs in. Users are scoped: a tenant administrator sees the whole tenant, an account-level user sees one account. Capability gates the action; scope gates the objects it may touch.

GET/v1/user

Read Identity and access for how roles and capabilities resolve.

Working entities

Entity	What it is	Lives on
Number	one number Voicebot may dial from or receive on	Account API
Number pool	a group of numbers one agent answers on	Account API
Scenario	the call flow: what is said, heard, decided	Account API
Scenario version	an immutable published snapshot of a scenario	Account API
Agent	a scenario bound to a gateway: one number, or a pool	Account API
Communication	one dialable unit: one recipient, one run, one row	Account API
Trunk	the SIP path between Voicebot and your telephony	Tenant API

Trunks and numbers

A number is a logical record inside Voicebot saying “this identifier belongs to this account”. A trunk is the actual signalling path to your carrier.

Registering numbers without a working trunk produces a system that accepts every dispatch request and never rings anybody. They are configured by different people at different times. See phase 1, step 3.