A plugin over an internal stock & orders system
This is the most complete use case and it maps directly onto the public boilerplate, talqui-oss/talqui-plugin-example — you can read every element referenced here as real, runnable code. It is the ideal starting point for understanding how the pieces of a plugin come together in a live conversation.
Contextualization
Imagine an ice-cream shop that sells and takes orders over WhatsApp, Instagram, and a web chat — all funneled into Talqui. The shop already runs an internal system that owns two things the business cares about during a conversation:
- Stock — which flavors exist, whether they are available, and how much is in each batch.
- Orders — placing a new order for a customer and confirming it.
Today, when a customer asks "do you still have pistachio?" or "I'll take two scoops of vanilla", the operator has to leave the conversation, open the internal system in another tab, look up the answer or type the order, and come back. That context-switching is slow, error-prone, and scales badly across dozens of simultaneous chats. It is exactly the pain the plugin model was built to remove.
Objective
Bring the shop's stock and orders into the conversation so that:
- the human operator can browse flavors, see live stock, and place an order without leaving Talqui; and
- the virtual agent can answer stock questions and even place orders autonomously, using the same underlying capabilities.
Both consumers must act on the same source of truth (the shop's internal system) and behave consistently, so a flavor that is out of stock is out of stock whether a human or the agent is handling the chat.
Participating elements
This plugin ships two of the three elements — a backend and a widget. It needs no settings page, because there is nothing tenant-specific to configure for the demo; a real shop that wanted per-tenant credentials would simply add one.
| Element | Role in this use case | Where in the repo |
|---|---|---|
Backend (apps/api) |
Bridges Talqui to the shop's internal system. Exposes the capabilities twice: as MCP tools for the virtual agent and as REST routes for the widget, both delegating to the same use cases. | apps/api |
Widget (apps/widget) |
The operator-facing panel in the conversation sidebar: a Flavors tab (catalog + stock), a Stock tab, and an order form opened as a popup. | apps/widget |
The backend's surface, in concrete terms:
| Capability | MCP tool (agent) | REST route (widget) |
|---|---|---|
| List / search flavors | ✓ | POST /v1/flavors/search |
| Read one flavor | ✓ | POST /v1/flavors/read |
| List stock | ✓ (StockList) |
POST /v1/stock/list |
| Create an order | ✓ (OrderCreate) |
POST /v1/orders/create |
The dynamics of use
There are two runtime flows, and the whole point of the plugin is that they feel like one product.
Flow A — the human operator, in the widget
When the operator opens (or switches to) a conversation, Talqui renders the widget in the sidebar and the widget runs its boot dialogue to discover which conversation it is attached to (see Widget). It then calls the backend's REST routes to render live data, and can open an order form as a popup over the conversation.
The operator never left Talqui: they read stock and placed an order inside the conversation window.
Flow B — the virtual agent, via MCP tools
The exact same capabilities are available to the virtual AI agent during automated attendance. Because the backend registered StockList, OrderCreate, and the flavor tools over MCP, the agent can discover and call them mid-conversation — no human required.
Why this is a unified experience
The two flows are two doors into the same room. Whether the customer is served by automation or by a human who takes over, the plugin reads and writes the same internal system through the same use cases, and the operator sees the result in the conversation they are already looking at. That is the core promise of plugins: operators (and the agent) work inside Talqui, with external context and actions at hand, without constantly switching tabs.
Take-aways
- A plugin can serve both the agent and the operator from one backend by exposing capabilities as MCP tools and REST routes over the same use cases.
- The widget turns the backend's reads/writes into an in-conversation experience; popups handle actions that need a form.
- No settings page was needed here — proof that you include only the elements a use case calls for (see Architecture).