Quick start
Five steps take you from an empty console to a live assistant on your site:
- Sign in to the console at /admin with the account your workspace owner created.
- Create a chatbot from the Chatbots tab. Give it a name, a product or use case, and (optionally) start from a template.
- Load your knowledge in the chatbot's Approved information tab so answers stay grounded in your content.
- Brand it and embed it: set the colour and links, then copy the widget snippet or share the chat link.
- Turn on live chat so an agent can take over any conversation from the operator console.
Core concepts
A few words that show up throughout the console:
| Term | What it means |
|---|---|
| Organization | Your workspace. It holds your chatbots, knowledge, team, plan and usage. Everything is scoped to it. |
| Chatbot | One assistant with its own name, branding, knowledge, links and channels. You can run several. |
| Approved information | The knowledge base (RAG) the assistant is allowed to answer from. Only approved entries are ever used. |
| Live chat / handoff | A human agent taking over a conversation from the AI, from the operator console. |
| End user | A visitor who talks to a chatbot. For private bots they can be given a login or an access code. |
| Admin / operator | A member of your team who manages chatbots or answers live chats in the console. |
Build a chatbot
Open the Chatbots tab and use the create form at the bottom of the grid.
- Name - what the assistant is called (for example "Acme Assistant"). This becomes its link.
- Product / use case - what it helps with. Used in the default persona and landing copy.
- Tagline & brand colour - shown on the chat header and landing page.
- Buy / contact link - an optional call-to-action the assistant can point people to.
- Template - optionally pre-fill safety and screening settings for a use case; everything stays editable.
After it is created, click Edit to open the full settings page: persona, webhook, live-chat availability, access mode and channels. Each opens in its own view with a Back button, so you are never lost in a wall of panels.
Load your knowledge (RAG)
Open a chatbot's Approved information tab (the RAG action in the grid). This is what keeps answers accurate: the assistant answers from these entries and says it doesn't have approved information when a topic is not covered.
- Paste text as titled entries - a fact, a policy, an FAQ answer.
- Import a document and it is split into searchable pieces automatically.
- Review & approve - imported entries land as pending and are only used once approved, so nothing goes live by accident.
Branding & the landing page
Every chatbot gets a shareable landing page and a branded chat surface. From the chatbot's settings and the Landing action you control:
Use the landing link as a standalone destination (in an email, a bio, a QR code) or embed the assistant directly on your own site - see Embed & API.
Suggestion chips & action forms
Suggestion chips
The quick-question chips above the chat input are fully configurable per chatbot. In the chatbot's settings, enter one suggestion per line. They give visitors an obvious first move and steer them toward what the assistant answers best.
Custom forms (actions)
You can define your own forms - text and data only - that the assistant can present. Each field has a type and validation that runs both in the browser and on the server:
| Field type | Validated as |
|---|---|
| Text / Long text | Free text, with a required flag. |
| Must be a valid email address. | |
| Phone | Digits and common phone characters. |
| Number | Numeric only. |
| Date | A valid calendar date. |
| Choice | One of the options you define. |
A submitted form can file a ticket (a helpdesk request) or capture a lead, depending on the target you pick.
Embed it & the API
Web widget (no code)
From the API panel, copy the widget snippet and paste it before </body> on your site. A floating bubble opens the assistant in your brand colour:
<script src="https://tolkia.io/widget.js"
data-tenant="your-chatbot-key" async></script>Direct link
Share the chatbot's link (from the Chatbots grid, Open) - a full-page branded chat, no install needed.
API
Prefer to build your own surface? Create an API key in the API access tab and call the chat endpoint with it. The panel shows the exact request and the error codes:
| Code | Meaning |
|---|---|
401 | Missing or invalid API key. |
429 | Rate limited or monthly quota reached. |
400 | Bad request. |
Live chat & human handoff
The operator console (the Console link on each chatbot) is where your agents watch live visitors and take over conversations.
- Live visitors - who is on your site right now, what page they are on, and whether they are browsing or chatting. Invite anyone into a conversation.
- Take over - jump into an AI conversation as a human; the visitor sees they are now talking to a person.
- Availability - set office hours, an auto-assign rule and a proactive greeting from the chatbot's live-chat settings.
- Disable human chat - a chatbot can run AI-only; turn live chat off in its settings and no handoff is offered.
Access control
Each chatbot has a visibility mode, set in its Access settings:
| Mode | Who can use it |
|---|---|
| Public | Anyone with the link or widget. Best for marketing and support. |
| Private (per user) | Only end users you provision, each with their own login. Best for members or clients. |
| Access code | Anyone who enters a shared code you set. Best for gated cohorts or events. |
For private bots you add end users (with a password you set or an auto-generated one) and grant them access per chatbot. Auto-generated passwords always include special characters for strength.
Team & roles
Invite colleagues from the Team tab and give each the least access they need. Roles are enforced on the server, not just hidden in the UI:
| Role | Can do |
|---|---|
| Admin | Everything in the organization: chatbots, knowledge, team, keys, plan and reports. |
| Editor | Manage chatbots and their knowledge and branding. |
| Viewer | Read-only access to reports and configuration. |
| Safety | A focused role for reviewing and approving knowledge and handling safety-critical items. |
Every meaningful action is written to an audit log you can review from the console.
Plans, quotas & usage
Your organization is on a plan that sets a monthly message quota and a chatbot allowance. Both are visible in the console.
- Message quota is enforced: once your organization reaches its monthly limit, general conversations pause with a friendly message until the next cycle or an upgrade. Safety-critical replies are never withheld.
- Chatbot allowance is shown on the Chatbots tab as
used / limit. Going over your plan's allowance shows a reminder to upgrade - it does not hard-block you, so a launch is never stuck waiting on billing. - Unlimited is represented by
0on a plan (shown as∞).
Reports & visitor journeys
The Reports tab summarizes conversations, leads and tickets over time. Per chatbot you can:
- See conversation volume and outcomes.
- Open Visitor journeys to replay a full conversation, shown side by side.
- Export leads and reports to CSV for your CRM or spreadsheet.
Security notes
Tolkia defends the chat surface for you:
- No unauthorized conversation access - visitor identities are server-issued high-entropy tokens, so one visitor cannot read another's conversation by guessing an id.
- No script injection - visitor input and your branding fields are escaped before rendering; the chat cannot be used to run scripts in another person's browser.
- Safe attachments only - attachment links are validated; forbidden or off-host content is rejected.
- Role and ownership checks on every request - the console enforces who owns what on the server, so hiding a button is never the only line of defense.