Platform concepts

Sphoro Voice is a small number of objects with sharp edges between them. Almost every question that starts "where do I put…" is answered by knowing which object owns the thing. This page is that list, and nothing else.

The objects

Seven, and only the first two are on the path to a working call. The rest are things you add when a conversation outgrows a prompt.

Object	What it is	Lives for
Agent `agt_…`	The configuration a call runs under: which languages it speaks, the instructions it follows, the tools it may call, the number it dials from. The unit you version — one per use case, not one per customer.	Indefinitely. Create it once, use it for every call.
Call `call_…`	One conversation running one agent — dialled out, delivered by a carrier, or connected from a browser. Carries its own transcript, recording, end reason and analysis.	Minutes, then a record.
Knowledge base `kb_…`	Documents the agent answers from, chunked and indexed. Attached to an agent, or to one node of a flow.	Indefinitely.
Function	Something the agent can do mid-conversation — look up an order, book a slot, transfer the call. Named on the agent, executed by us, answered by you.	Per deployment.
Flow	A conversation too structured for one prompt, written as nodes and the edges between them. Stored on the agent rather than as its own object.	With its agent.
Journey `jny_…`	Automation across calls and days: dial, branch on how it went, wait, retry, fall back to a message.	Indefinitely, in published versions.
Project `prj_…`	A cost centre inside your account. Calls are attributed to one, and it can carry a monthly budget.	Indefinitely.

How they fit together

Read down for the call, across for what it can reach.

           you                          a carrier, or a browser
            │                                      │
            ▼  POST /v1/calls                      ▼  inbound
       ┌─────────────────────────────────────────────────┐
       │                      Call                       │
       └───────────────────────┬─────────────────────────┘
                               │ runs
                               ▼
       ┌─────────────────────────────────────────────────┐
       │                     Agent                       │
       │   languages · prompt · voice · tools · flow     │
       └───┬───────────────┬───────────────┬─────────────┘
           │ grounds on    │ may call      │ may follow
           ▼               ▼               ▼
     Knowledge base    Functions          Flow
                           │
                           │ may run
                           ▼
                       Workflow

       Call ──▶ events ──▶ webhooks, live feed, analytics
            └─▶ transcript, recording, summary, extractions

What owns what

The four boundaries that come up most, stated once so the rest of the site does not have to keep restating them.

The question	The answer
Where does the system prompt live?	On a language, inside the agent's `languages` list — not on the agent. An agent that speaks three languages has up to three prompts, and the first entry's prompt is the one everything else derives from. See writing the prompt.
Where does the voice live?	On the same language entry. Voice ids are not portable between vendors, so an entry can carry one id per vendor and the right one is picked when the chain settles on a vendor. See language and voice.
What is the difference between a flow and a journey?	A flow is inside one call — which part of the conversation you are in. A journey is outside it — which call in a sequence you are on, over days. See flows and journeys.
Is a project a tenant?	No. A project is a label for cost inside one account; it isolates nothing. Two projects can share agents, numbers and knowledge. See projects.

Personas: the idea, separated from the telephone

An agent is two things wearing one name — what the conversation is (prompt, voice, knowledge, flow) and how it reaches somebody (carrier, number, direction, mode). Those change on different schedules and usually by different people.

A persona is the first half on its own, so one idea can be deployed three times: on the inbound line, on the outbound campaign, and in the widget on your website — edited once. Personas covers when this is worth doing and when a plain agent is the simpler answer.

Identifiers

Every object carries a prefixed, opaque identifier. The prefix is not a promise about the format after it — treat the whole string as opaque and store it whole.

Prefix	Object
`agt_`	Agent
`call_`	Call
`kb_`	Knowledge base
`doc_`	A document inside a knowledge base
`jny_`	Journey
`prj_`	Project
`evt_`	An event, in a webhook body or the live feed

Store the id, not the name. Names are yours to change and several objects allow duplicates; ids are stable for the life of the object. The one place this bites is agents: renaming one is free, and code that looked an agent up by name stops finding it.

Seeing them

Every object above has a list endpoint, and they all page the same way. This is the quickest way to find out what your account already has:

Shell

for kind in agents personas knowledge_bases workflows journeys projects; do
  echo "== $kind"
  curl -s "https://voice.sphoro.com/v1/$kind?limit=5" \
    -H "Authorization: Bearer $SPHORO_API_KEY"
done

Where to go next

Kinds of agent is the next decision to make — a conversation, a keypad menu and a plain forwarding line are configured very differently, and picking the wrong one costs a rewrite. How a call runs is the same material from the other direction: not what the objects are, but what happens to them between your request and a finished record.