Skip to content
Chatvia Docs
On this page

Getting started

Core concepts

Get in touch: Ahmad Mayahi, creator of Chatvia, Spectra and Shakomako

A short tour of the objects your team will see across the dashboard and the API.

Workspaces, teammates, chatters

Chatvia is built around three roles. Keep them straight and the rest of the product makes sense.

  • Workspace: the company account. One per customer. This is what makes Chatvia multi-tenant: each customer's data stays in their own workspace. The workspace owns agents, sources, functions, and connectors. Without a license key, an install has one workspace, with no limit on agents (see what needs a key). Four Enterprise security features need an Enterprise license key. A workspace can have a monthly message limit.
  • Teammates: the people inside the workspace who manage agents. They sign in to the dashboard. Each teammate has a role that picks which agents they can reach and what they may do there (set up the agent, train sources, read chats, and more). Invite them from Teams in the top nav.
  • Chatters: the end-users who talk to agents. They sign in on an agent's chat page (/chat/{agent}) and only see the agents they have been granted access to. Chatters never see the dashboard. Invite them workspace-wide from Workspace → People → Chatters, or per agent from the agent's Chatters page (under Access).

Each agent has its own signing secret for identity verification. You find it on the agent's Security → Identity page.

Agents

An agent is one chatbot. There is no agent "type". Every agent can do every job. It has:

  • A name.
  • A persona: the system instructions the model follows.
  • A model: which LLM the agent uses, and how creative its answers are.
  • An appearance: colors, avatar, text labels.
  • A set of sources: its knowledge.
  • Optional tools: workspace functions and MCP connectors the agent is allowed to call.
  • Three surfaces: the ways chatters reach it.

Surfaces

Every agent is exposed through three surfaces at once. A single Setup page configures appearance, persona, starters, model, and branding once. Those choices apply across all three surfaces. Some sections, like Behavior, change with the surface tab you pick. The code to put an agent on your site is on the separate Deploy page.

  • Hosted Chat: the standalone chat at chat.example.com/chat/{agent}. Useful for embed, iframe, or SSO scenarios.
  • Widget: an embeddable floating chat bubble. One <script> tag drops it onto any host page.
  • Bar: a search-style trigger that opens a full-screen chat modal. A first-class surface, configured per agent.

A chatter who has access to several agents can switch between them in the hosted chat, from My Agents in its menu.

Sources

Anything an agent can answer from. Sources live per agent. There is no workspace-wide knowledge base page. Four kinds:

Type What goes in Used for
Files PDF, Word, Markdown, audio, video Long-form documents
Web A URL (Chatvia crawls child pages) Public sites, docs portals
Text Pasted plain text Short policies, FAQs
Q&A Explicit question + answer Direct overrides, canonical replies

All sources are parsed into chunks, embedded into vectors, and indexed. Search works by meaning and by keywords, so chatters don't need to use the exact wording in the source.

Tools (Functions and Connectors)

Tools are first-class in Chatvia. The workspace owns the catalog. Each agent picks which tools it is allowed to call.

  • Functions: webhook-backed custom tools. The workspace defines them once in Workspace → Integrations → Functions, then attaches them per agent.
  • MCP Connectors: branded one-click integrations (GitHub, Slack, Notion, Linear, Stripe, Atlassian, ...) plus custom MCP servers added by URL. Set up at workspace level in Workspace → Integrations → Connectors, attached per agent.

Each connector tool has a tri-state permission: allow, require approval, or blocked. You set it on the connector, so it applies to every agent that uses it. Approval-required tools pause the turn at a checkpoint until the person in the chat approves or denies the call. Only the Hosted Chat can show this, so other surfaces don't get these tools.

Conversations

Every chat thread creates a conversation between a chatter and an agent. Each conversation:

  • Belongs to one chatter.
  • Holds a stream of messages (user, assistant, and agent for replies a teammate writes during a human handoff).
  • Can be tagged with a topic, sentiment, and tone.
  • Has a handoff status: ai (default), pending (the chatter requested a human), human (a teammate took over), or returned (the teammate handed the chat back to the AI).

Teammates browse them in Chatlog, with filters for date, topic, sentiment, country.

Tokens and keys

Three different credentials. They are easy to mix up:

Credential Where it's made Who holds it What it does
API key Workspace → Integrations → API Keys Your servers Authenticates calls to the public API at yoursite.com/docs/api
Signing secret The agent's Security → Identity page Your servers Signs sign-in tokens for a protected agent
Sign-in token Signed by your server with the agent's secret Your end-users (chatters) Logs a chatter into one specific agent for up to 24 hours

API keys and signing secrets never leave your backend. Sign-in tokens are short-lived and may be embedded in the browser (widget data-auth, chat ?token=).

Prompts

A prompt is a named system-instruction block, saved at the workspace level. Attach one to many agents instead of pasting the same instructions everywhere. Prompts live in Workspace → Library → Prompts.

Search guides, settings and commands.