Core concepts

Core concepts

A handful of objects show up across the dashboard and the API. Understanding them makes everything else straightforward.

Organizations (workspaces)

An organization is your workspace and the unit of tenancy. Every agent, phone number, call, recording, API key, and invoice belongs to exactly one organization. A user can be a member of several organizations and switch between them.

Most API endpoints are organization‑scoped and live under /api/orgs/{orgId}/…. When you authenticate with a user JWT you pass the org in the X-Org-Id header; when you authenticate with an API key, the org is taken from the key automatically — and the key is pinned to that org, so another org's {orgId} in the path is rejected.

Not every org‑scoped route accepts an API key yet; the credential matrix lists exactly which do.

Two API surfaces. The full dashboard API lives under /api/… and returns { success, data } envelopes; it accepts an API key or a user JWT. A separate, narrower automation surface lives under /api/v1/…, accepts an API key only (X-API-Key), and returns flat JSON — it's built for Zapier/Make/n8n‑style integrations. See Two API surfaces and Automation platforms.

Members, roles & departments

Organizations have members with a role — owner, admin, developer, viewer, or member. Owners and admins manage the workspace; you can also define custom roles and departments to control what each member sees and which numbers they use. See Team & workplace.

Agents

An agent is the configured voice assistant: a system prompt, a first‑response greeting, and a choice of providers (below). Agents can be attached to phone numbers, published as a public web widget, or invoked over the API. Each agent tracks its own calls and stats.

Providers (LLM, STT, TTS, telephony)

Every agent is assembled from four provider slots:

The available models, their pricing, and latency come from a central catalog (GET /api/catalog). TTS and STT are priced per model, and the builder shows a live per‑minute cost estimate based on your selections. See Catalog & providers and Custom models.

Sessions & calls

A session is a single live conversation — a phone call, a browser web call, or a chat exchange. While active it streams audio/text in real time; when it ends, Telenow persists a call record with its transcript, duration, outcome, and (optionally) a recording.

• Agent mode — the AI agent talks to the other party.
• Manual / softphone mode — a human team member talks, with Telenow bridging the browser and the carrier (used by the dialer).

You'll see sessions created via POST /api/sessions/init-web-call (browser) and POST /api/sessions/initiate-call (outbound PSTN), and finished calls under GET /api/orgs/{orgId}/calls.

Chat sessions

A chat session is a text‑only conversation with the same agent — no audio. The agent still uses its prompt, knowledge base, context variables, and tools, but replies in text. Chat powers the chat mode of the public widget and is also available programmatically on the automation surface: POST /api/v1/chat sends one turn (creating the session on the first call), then you keep passing the returned sessionId. Each request carries an identifier — your unique end‑user id — which binds the session to one person so a leaked session id can't be reused by someone else. See Chat API.

Phone numbers & carriers

A phone number is purchased through Telenow (or imported from your own carrier) and assigned to an agent or a team member. Carriers (Plivo, Twilio) can be configured platform‑side or brought yourself (BYOC) with your own credentials. Some destinations require compliance documents before a number is usable. See Phone numbers.

Knowledge bases (RAG)

A knowledge base is a collection of documents you upload; Telenow embeds them so an attached agent can answer from your content rather than only its base model. See Knowledge bases.

Recordings & transcripts

When enabled, calls are recorded and stored. You can list recordings, fetch a time‑limited signed URL to download the audio, and read the per‑turn transcript. See Calls, recordings & insights and the Recordings API.

Webhooks

A webhook endpoint is a URL Telenow POSTs events to — call.started, call.ended, recording.ready, transcript.ready, tool.invoked. Endpoints can be org‑wide or scoped to one agent, and can opt in to receive the recording URL and transcript inline. Deliveries are signed with HMAC‑SHA256. See the events reference.

Integrations & connectors

A connection stores credentials for an outside service (WhatsApp, a CRM, a spreadsheet, a payments provider, …) in an encrypted org‑scoped vault. A connection exposes one or more capabilities (e.g. whatsapp.send), and an agent tool binds to a { connectionId, capability } pair — so you can swap the vendor behind a capability without rebuilding the agent. Many connectors also support a per‑tool target (a specific spreadsheet, base, or form) whose columns Telenow auto‑discovers into tool parameters. Agents can also call your own HTTP APIs and MCP servers. See Integrations and WhatsApp.

API keys

An API key authenticates server‑to‑server API calls without a user login. Keys are organization‑scoped, carry a role, and are sent in the X-API-Key header. The secret (vai_live_…) is shown once at creation. Create them under Developers → API keys. See Authentication.

Plans, usage & billing

Each organization is on a plan with limits (monthly minutes, concurrency, included features) and a billing mode:

• Postpaid — usage runs up a balance that's invoiced monthly.
• Prepaid — the org runs on purchased credits and is hard‑stopped when the balance hits zero; you top up via Billing → Buy credits.

Telenow meters call minutes, LLM/STT/TTS usage, telephony, and connector usage per organization, against your plan's limits, and shows estimated cost in your chosen currency. See Usage & billing.