Core concepts

Every term the rest of the documentation uses, with a link to the page that owns it. The first half is the model you need before building; the table at the end defines everything else.

Workspace

The boundary everything belongs to: agents, tools, keys, numbers, calls, credit and the people who can see them. Members hold ADMIN, EDITOR or VIEWER. The dashboard calls it an organization. See workspaces and roles.

Agent

One object, config, plus what it attaches: tools, MCP servers, FAQs and handoff targets. channel is voice, video or text and decides which model slots exist; prompt is where the behaviour lives. Only name is required. See agents overview and channels.

Draft and published

Every write lands on the draft. Live traffic (phone numbers, batches, API calls that omit agent_version) runs the latest published version, an immutable snapshot. Publishing validates the draft, freezes it as the next version and pins each attached tool to its current published version; republishing a tool changes nothing live until the agent is published again. The dashboard’s test panel and agent_version: "draft" run the draft directly. See versions.

Tool

One capability the model can call mid-conversation: name, description, a json_schema of arguments, and an ordered tree of operations (call an API, run TypeScript, branch, speak, hand off, transfer, end the call). A tool has its own draft and published versions and must be published before an agent can attach it. See tools overview.

Agent task

An agent nobody talks to: it takes named inputs (vars), uses tools, and returns typed output fields. Same draft/publish lifecycle as an agent. Use one for research, classification and drafting. See agent tasks.

FAQ

A named list of question/answer pairs attached to an agent or task through faqs. The questions go in the prompt; the agent fetches your written answer with a generated tool. FAQs have no draft or versions: an edit reaches every attaching agent from its next session. See FAQs.

Handoff and transfer

	Goes to	Built with	Channels
Handoff	Another Talqing agent; the platform keeps running the conversation	`handoffs` on the agent, or the `handoff` operation	All
Transfer	A human on a real phone number; Talqing steps out	The `transfer` operation	Phone calls

See handoffs and transfer.

Conversation, call, chat and session

Noun	What it is
Conversation	A thread with one person: a web chat, a Telegram thread, a phone call, or their phone and WhatsApp calls and messages on one of your numbers. Holds the items (messages, tool calls, tool results), each with the `channel` it arrived on
Call	One voice or video session, by phone or in a browser
Chat	One text session, open from its first message until the agent’s `end_call` or `POST /v1/chats/{chat_id}/end`
Session	One agent run inside a conversation (one call or one chat). Usage, cost, latency and the close reason are per session

An agent configured to continue a thread adds a new session to the same conversation on every call or chat. See conversations.

Contact and `contact_key`

A contact is the person across all their conversations, with the userdata accumulated about them. You identify one with contact_key: your own stable string, 1–256 characters, unique in the workspace. On your phone and WhatsApp numbers Talqing builds it instead: phone:<your number>:<their number>, one contact across calls, WhatsApp calls and WhatsApp messages. Omit it on a web call or chat and a single-use key is minted, so the same person arrives as a stranger each time. Platform-built keys use these prefixes, which your own keys must not: phone:, telegram:, whatsapp:, sip:, stream:, agent_copilot:, tool_copilot:, task_copilot:. See text conversations.

Userdata, vars and system variables

Root	Holds	Written by
`{{userdata.field}}`	What you know about the person. Merged onto the contact record, so it is there next call	The request that starts a session, and any tool
`{{vars.name}}`	Configuration of the session, declared on the agent with a default	The request that starts a session only
`{{system_vars.…}}`	Seven platform keys: `human_phone_number`, `agent_phone_number`, `direction` (empty on web calls, API chats and Telegram), `channel`, `now`, `date`, `time` (need `timezone` on the agent)	The platform

All three are visible to the model and may be read aloud. Credentials belong in a secret, read as {{secrets.NAME}} inside a tool. See variables and userdata.

Provider key, personal access token, secret

Credential	What it is	Read back?
Provider key	Your own OpenAI, Deepgram, ElevenLabs… key that runs the agent (BYOK). `PUT /v1/byok/{provider}`	Last 4 characters only
Personal access token	Talqing’s API credential, `Authorization: Bearer`. Acts as its creator with their live role	Shown once
Secret	A workspace value a tool sends, as `{{secrets.NAME}}`. The model never sees it	Last 4 characters only

See provider keys, authentication and secrets.

Credits and the platform fee

Provider spend goes to your own accounts. Talqing charges only a platform fee, debited from the workspace’s prepaid credit: $0.0035 per voice minute, $0.01 per video minute, $0.0001 per answered text message. A workspace at zero credit cannot start new calls or chats. See pricing and credits.

Other terms

Term	Meaning
Agent team	Several agents sent on one call request; `members[0]` answers, the rest are reachable by handoff. Agent teams
Avatar	An Anam face for a `video` agent, billed by wall-clock minute. Video avatars
Batch	A recipient list worked through on a schedule with pacing and retries: call, email or WhatsApp. Batch calling
BYOK	Bring your own key: every model runs on your provider account. Provider keys
Cascade	Speech-to-text → language model → text-to-speech, three swappable parts. Models
Close reason	How a call or chat ended. Some reasons waive the platform fee. Close reasons
Endpointing	Deciding the caller has finished speaking. Speech-to-text and turn detection
Integration	A connection to an outside service: an MCP server whose tools an agent calls, or a channel like Telegram. Integrations
Item	One entry in a conversation: a message, a tool call or a tool result. Conversations
MCP	Model Context Protocol: servers you attach to an agent, and Talqing’s own server for coding agents. MCP servers, our MCP server
Operation	One entry in a tool’s ordered tree; twelve kinds. Operation tree
Priority lane	`llm.priority`, a provider’s faster lane billed at its priority rates. Priority lane
Realtime	One speech-to-speech model instead of the cascade. Realtime
Trigger	Binds an inbound integration event (a Telegram message) to the text agent that answers it. Triggers

Build a voice agent

Put the vocabulary to work in the dashboard.

Agents overview

Every field of an agent config.

Get started

Build

Guides

Workspace

Agent

Draft and published

Tool

Agent task

FAQ

Handoff and transfer

Conversation, call, chat and session

Contact and `contact_key`

Userdata, vars and system variables

Provider key, personal access token, secret

Credits and the platform fee

Other terms

Next

Build a voice agent

Agents overview

​Workspace

​Agent

​Draft and published

​Tool

​Agent task

​FAQ

​Handoff and transfer

​Conversation, call, chat and session

​Contact and contact_key

​Userdata, vars and system variables

​Provider key, personal access token, secret

​Credits and the platform fee

​Other terms

​Next

Build a voice agent

Agents overview

Workspace

Agent

Draft and published

Tool

Agent task

FAQ

Handoff and transfer

Conversation, call, chat and session

Contact and `contact_key`

Userdata, vars and system variables

Provider key, personal access token, secret

Credits and the platform fee

Other terms

Next