On this page
Core Concepts#
Gydr is built around a small set of objects. Understanding how they relate to each other makes the rest of the documentation easier to follow. This page walks through each one in plain terms.
How the objects fit together#
The diagram below shows the containment hierarchy. Every level is explained in the sections that follow.
Account
└── Widget (the chatbot you embed on your site)
└── Skill (instructions + capabilities; one or more per widget)
├── Knowledge Base (content the chatbot can answer from)
│ └── products | FAQs | documents | locations
└── Plugin (external integration; zero or more per skill)
└── Shopify | REST API | MCP Connector | …Account#
An account is the top-level container. Every widget, knowledge base, team member, and billing record belongs to exactly one account. When you sign up for Gydr, you create an account. A team member can belong to more than one account and switch between them in the Console.
Widget#
A widget is the deployable chatbot. It is what you embed on your website using the Widget SDK. Each widget has a name, a persona (set through its skills), and an API key you use in the embed code.
Widgets use a save-file model: edits live in named save files and nothing reaches visitors until you explicitly publish a save. This means you can iterate on configuration without affecting live traffic.
Publish to go live
A new widget starts in an unpublished state and is invisible to visitors. Open the widget editor in the Console, make your changes, save them to a save file, then publish that save. After publishing, visitors see the updated chatbot immediately.
Skill#
A skill holds a chatbot's persona instructions and connects it to Knowledge Bases and Plugins. You write the instructions in plain text: the chatbot's name, tone, what topics it should focus on, and what it should avoid.
One widget can have multiple skills, and the chatbot selects the right skill based on the conversation context. In practice, most widgets start with a single skill.
Knowledge Base#
A knowledge base is a searchable collection of content that the chatbot can draw on when answering questions. You attach knowledge bases to a skill; one skill can use more than one.
There are four knowledge base types:
| Type | Use it for |
|---|---|
product_catalogue | Items in a product catalogue — names, SKUs, prices, descriptions |
faq | Question-and-answer pairs for support content and policies |
document | Free-text pages, articles, or documentation |
location | Physical places with addresses, hours, and contact details |
Content you add to a knowledge base is not immediately answerable. The chatbot retrieves answers using vector search, which requires an embedding step. After writing records — through the Console or the Knowledge Base API — trigger a sync. The chatbot can answer from those records once the sync finishes.
Plugin#
A plugin connects a skill to an external service. During a conversation, the chatbot can call the plugin to look up live data or take an action. Plugins are attached to skills, not directly to widgets.
Available plugin types include Shopify (read product and order data), REST API (call any HTTP endpoint), and MCP Connector (connect to a remote Model Context Protocol server). New plugin types are added over time; the full list is in the Console under Plugins.
Session and Visitor#
A session is a single conversation. It starts when a visitor opens the chatbot and ends when they close it or the session times out. Each session has a unique ID and belongs to a widget.
A visitor is the person having the conversation. By default, visitors are anonymous. If you pass a stable visitorId in the embed code — for example, your own user ID after login — Gydr links that visitor's sessions together across pages and devices. This lets the chatbot remember context from earlier conversations.
Developer surfaces#
There are four ways to integrate with Gydr programmatically:
| Surface | When to use it |
|---|---|
| Widget SDK | Embed the chatbot on a website. A single script tag is all you need; the JavaScript API gives you more control over opening, closing, and passing context. |
| Knowledge Base API | Create, update, and sync knowledge base content from your own systems. Use this to keep product catalogues, FAQs, or locations in sync with your database. |
| Conversation API | Build a headless chat experience or retrieve conversation transcripts. Use this when you want to drive the chatbot from your own UI rather than the embedded widget. |
| Webhooks | Receive real-time event notifications — new messages, session endings, handoff requests — delivered as HTTP POST requests to your server. |
Where to go next#
Now that you know the vocabulary, you are ready to build something:
- ›Quick Start — embed your first chatbot on a page in under five minutes
- ›Installation — all the ways to load the Widget SDK (script tag, npm, React, Vue, and more)
- ›Knowledge Base API — load and sync your content so the chatbot can answer from it