suvvy-mcp

Suvvy MCP

Overview

Suvvy is a platform for creating LLM-powered chatbots (Bots) that connect to messaging channels and communicate with clients. Each bot has a system prompt, a knowledge base, channel integrations, and optional custom tools (actions).

Requirement: All Suvvy management is done through the Suvvy MCP server. If it is not configured in your environment, refer to the documentation: https://docs.suvvy.ai

Throughout this skill, "see MCP" or "available via MCP" means: consult the relevant MCP tool schema directly — tool descriptions and argument definitions are the authoritative source for full parameter details.

Using references: Whenever any feature is mentioned — even in passing — immediately load the relevant references/ file before continuing. When in doubt, load it. Do not rely on the summary in the main file alone.

Plan First, Build Second

Before creating or significantly modifying a bot, always plan first — never make API calls without a confirmed plan.

When the user asks to build or configure a bot, do not start executing immediately. Instead:

Draft a complete plan using the template below
Present the plan to the user — explain the reasoning behind each architectural choice
Get explicit approval — wait for the user to confirm or adjust the plan
Only then execute — follow the approved plan step by step

This applies to building a new bot, adding a major feature, restructuring the knowledge base, or any change that involves multiple interconnected decisions.

Plan template:

**Bot plan:**
- **Role:** [what the bot does and for what company]
- **Knowledge Base:** [FAQ Documents / Vector Knowledge Base / Vector Documents / Tables — list what will be created]
- **Custom Tools:** [actions/webhooks needed — list with purpose]
- **Bot Settings:** [key settings to configure]
- **Dialogue Flow:** [step-by-step interaction logic]
- **Channels:** [where the bot will operate — note: configured manually in dashboard]

Communicating with Users

The target audience is non-technical users. They do not know how the platform works internally — and they don't need to. Your job is to speak in terms of outcomes, not mechanics.

What to never expose (unless the user explicitly asks)

Function and parameter names — the user should never see these:

❌ "I will call create_faq_document with the parameter title_for_search…"
❌ "I will update llm_settings.temperature_mode to stability"
❌ "I will install history_type: last_messages"

Internal object IDs — keep them behind the scenes:

❌ "Bot ID: a1b2c3d4-..."
❌ "your bot's instance_id — xyz"

How to communicate instead

Describe what will happen, not what API call you're making:

Instead of this	Say this
"I will call `create_instance` to create a bot"	"Creating a bot"
"I will install `history_type: last_messages`"	"I will configure the bot so that it remembers only the last N messages"
"I will update `llm_settings.temperature_mode: stability`"	"I will make the bot's responses stable and predictable"
"I will create `faq_document` с `title_for_search`"	"I will add a document about… to the knowledge base"
"I will add a step of type `webhook` в Custom Tool"	"I will configure a call to your API when…"

When IDs are still needed

Provide IDs only if:

The user explicitly asks ("what is my bot's ID?")
The ID is needed for manual configuration in another system

In all other cases, keep the technical mechanics behind the scenes.

Model names — only from the current list

Never refer to models by internal codes (llm_code) and do not use names from memory — they may be outdated. Before mentioning a model to the user:

Call get_llm_listto get the current list of available models.
Use the human-readable name from the response, not the internal code.

❌ "Choose a model: claude-sonnet-4-6 or gpt-4o" ✅ "Choose a model: Claude Sonnet or GPT-4o"

Prices and balance — only in currency, not in tokens

Never show the user amounts in tokens. Always convert to currency:

Call get_balance_token_ratesto get the token rate for each model.
Convert tokens into money.
Show the user only the final amount in currency (for example, "~3.2 ₽ per dialog").

❌ "The cost of the dialog is 1,200 tokens" ✅ "The cost of the dialog is about 1.8 ₽"

Terminology

Concept	Primary Term	Code / MCP Term	Russian	Aliases / Abbreviations
Main entity	Bot	`instance`	Bot, Agent	Agent
Knowledge base	Knowledge Base	—	Knowledge base	KB
Knowledge base entry (direct)	FAQ Document	`faq_document`	Direct question	Direct Question, DQ
Knowledge base entry (Q&A pairs, semantic)	Vector Knowledge Base	`vector_knowledge_base`	Vector knowledge base	VKB
Knowledge base entry (file/unstructured, semantic)	Vector Document	`vector_document`	Vector document	Document search
Knowledge base entry (structured)	Table	`table`	Table	—
Callable action	Custom Tool	`custom_tool`	Custom action, Action, Workflow	Action, Workflow, CD
Communication surface	Channel	`channel`	Channel	—
Pre-built connector	Integration	`integration`	Integration	—
Client chat session	Dialog	`dialog`	Dialog	Dialogue
Sub-agent bot	Subordinate Bot	—	Subordinate bot	Slave bot
Multi-agent architecture	Multi-agent System	—	Multi-agent system	—
Scheduled outbound message	Follow-Up	—	Follow-up, Delayed message	Ping, Scheduled Message
Instruction template engine	Templates	`use_liquid`	Templates in the instruction	—
Dialog-scoped named field	Custom Variable	`custom_variable`	User variable, Dialog field	Dialog field
Bot-defined dialog memory	Memory	—	Memory	Dynamic Variables
KB analytics label	Knowledge Tag	`knowledge_tag`	Tag	Tag
File attached to FAQ Document for delivery	File to Send	`file_to_send`	File to send	—
Image attached to FAQ Document for visual search	Image	`image`	Image	—

In MCP tool names and API parameters, always use the code/MCP term (e.g., instance_id, faq_document).

Core Concepts

Bots (Instances)

A bot is the central entity on the platform. Always create bots without a template — start from a blank configuration and build up from scratch.

Each bot has:

A system prompt (also called Instruction) — defines behavior, tone, and dialogue logic
A knowledge base — FAQ Documents, Vector Knowledge Base(s), Vector Documents, and/or Tables
Channels — where clients interact (messengers, chat widgets, etc.)
Integrations — pre-built connectors available on the platform; when attached to a bot, they add tools that let the bot interact with external applications (CRMs, booking systems, etc.)
Custom Tools — optional callable actions

Key Bot Settings

Most bot settings are updated via update_instance_mcp. The bot's model and LLM parameters (llm_code, llm_settings.*, structured_answer, max_answer_tokens) are updated separately via update_instance_llm / set_default_instance_llm. Setting groups: LLM & Generation, Dialogue History, Image Handling, Message Filtering, Employee Interception, Response Formatting, RAG / Vector Search, Cost & Performance, Channels & Integrations, Organization & Multi-profile. A few settings groups (Working Hours schedule, Security & Compliance, Notifications & Alerts, anti-spam limits, message-split rules) exist only in the full instance schema and are not exposed via MCP — dashboard-only.

Load references/bot-settings.md when configuring bot settings via update_instance_mcp — it lists exactly which fields are and aren't available through MCP.

Functions

Every bot has a unified list of callable functions. The bot can call any function from this list in accordance with its instruction. Functions come from four sources:

Knowledge base — get_file_text (FAQ Documents), a per-knowledge-base named function (Vector Knowledge Base), a per-search-function named function (Vector Documents), and per-table functions (Tables)
Custom Tools — manually configured actions
Channels — some channel integrations expose their own functions
Integrations — pre-built connectors add their own functions (CRM, booking, etc.)

Use get_instance_functions to retrieve the complete list of all callable functions currently available to a specific bot — useful when writing or auditing the instruction to ensure all referenced functions actually exist.

Knowledge Base

Suvvy supports four knowledge base types that can run simultaneously on the same bot: FAQ Documents, Vector Knowledge Base, Vector Documents, and Tables.

FAQ-level option — Keywords (force forced retrieval): patterns that, when matched in the client's message, require the bot to call the FAQ-search (get_file_text) function before responding. Configured via get_file_text_function_settings.force_choice_pattern_list — dashboard-only, not available via MCP (see references/bot-settings.md).

Load references/kb-faq-documents.md when creating or editing FAQ Documents. Load references/kb-vector-knowledge-base.md when working with Vector Knowledge Base (semantic Q&A pairs). Load references/kb-vector-document.md when importing or configuring Vector Documents (semantic file search). Load references/kb-tables.md when working with Tables or SQL queries. Load references/kb-tags.md when configuring Knowledge Tags for analytics.

Custom Tools

Custom Tools extend a bot's capabilities with arbitrary logic. Each consists of one or more sequential Steps that can pass data to each other via variables. Step types include webhooks, bot calls, table queries, CRM actions, payment links, image generation, and more.

Load references/custom-tools.md when creating or configuring Custom Tools.

Integrations

Integrations are pre-built connectors that can be attached to a bot. Unlike Custom Tools (manually configured), Integrations are ready-made — once connected, they add tools that let the bot interact with external applications (CRMs, booking platforms).

Examples of what integration tools enable: schedule a client appointment, look up a client record, create or update a CRM entry.

When writing a bot's system prompt, treat integration tools the same as custom tools: define an explicit trigger condition for each call.

Dialogs

A Dialog is the chat session between a bot and a client. When a client writes to a connected channel, a dialog is created. Client messages arrive in the dialog, the bot responds (calling functions as needed), and its replies are sent back through the channel.

The active bot in a dialog can be switched mid-conversation via a Custom Tool step. The new bot takes over and does not need to have that channel connected.

Pause / Resume bot — use pause_or_resume_instance_in_dialogue_by_id to manually pause or resume the bot in a specific live dialogue.

Answer as employee — use answer_in_dialogue_as_an_employee to send a message into a live dialogue as an employee. The end client sees it as a normal message.

Clear dialogue context — use clear_dialogue_context_by_id to reset the context of a specific dialogue (applies to real dialogues, not just the test chat).

Search dialogues — use search_dialogues_by_message_filter to find real dialogues by message text and other filters.

Reading dialogue data — get_dialogue_list lists all real dialogues for a bot; get_dialogue_by_id retrieves a specific dialogue; get_dialogue_messages_by_dialogue_id fetches the full message history.

Dialogue ratings — when a bot uses the request_dialogue_rate Custom Tool step, it generates a rating link. Use get_dialogue_rate_list to fetch all ratings, or get_dialogue_rate_list_by_dialogue_id for a specific dialogue.

Active Follow-Ups in a dialogue — use get_active_reminder_list_by_dialogue_id and get_scheduled_messages_for_dialogue_by_dialogue_id to inspect pending Follow-Ups. Use cancel_reminders_in_dialogue to cancel them.

Subordinate Bots

A Subordinate Bot is a bot invoked from a Custom Tool step and runs within a single function call. The flow:

The active bot triggers a Custom Tool
A step in that tool calls the Subordinate Bot, passing it relevant information
The Subordinate Bot processes the request — calling its own functions, integrations, etc.
Its response is returned to the calling bot as the function result

Subordinate Bots are configured exactly like regular bots but have no channel attached. Their instruction should be written as a technical/internal agent prompt. Useful for delegating specialized tasks and keeping each bot focused on a narrow responsibility.

Follow-Ups

Follow-Ups are messages scheduled to be sent to a client at a future time. Three types: Follow-Ups (from Custom Tool steps or FAQ Document retrieval — Vector Knowledge Base / Vector Document entries don't support retrieval-triggered follow-ups), Dynamic Follow-ups (timed relative to a client-specific event date), and Scheduled Event Groups (bot-level, triggered by dialogue inactivity).

Load references/follow-ups.md when setting up any type of follow-up or scheduled message.

Custom Variables (Dialog Fields)

Custom Variables are named fields that persist for the entire duration of a dialog.

Set by the bot directly or by a Custom Tool step
Survive bot switches, multiple turns, Custom Tool calls
Useful for storing client data collected during conversation (e.g., phone number, chosen product, lead stage)
The predefined list of variable names is configured in advance; the bot assigns values to those names
Typed: each variable has a type — string, integer, number, boolean
show_to_bot: whether this variable is included in the bot's context (default: true). Set to false to hide internal variables from the LLM.
is_writeable_by_bot: whether the bot can set this variable directly (default: true). Set to false to make it read-only for the bot.

Memory (Dynamic Variables)

Memory works the same as Custom Variables but without a predefined list of field names. The bot sets key-value pairs freely — it decides both the key name and the value. Like Custom Variables, memory entries persist for the entire dialog.

Must be explicitly enabled in bot settings (memory.is_enabled = true); disabled by default — set_memory steps will not work until this is turned on
Use when the set of fields cannot be known in advance or varies per conversation
Optional: clear_with_context — clears memory entries when the dialogue context is reset

Standard Functions

Built-in callable functions: Stop dialogue, Ignore message, Set dialogue tag, Call manager. Enabled via update_instance_mcp. Add explicit trigger conditions in the instruction so the bot knows when to call each one.

Load references/standard-functions.md when enabling Standard Functions or configuring reminder/schedule settings.

Common Bot Archetypes

Suvvy bots are used in many roles — the platform imposes no restrictions on use case. Common examples:

Archetype	What the bot does
Support agent	Answers product questions, resolves issues, escalates to a human
Admin / Receptionist	Books appointments, checks availability, manages schedules

Any role that involves text-based client interaction is a valid use case.

Voice Agent

Suvvy supports a Voice Agent mode for phone call interactions (STT → LLM → TTS). Check current per-minute pricing with the user's account manager or the dashboard — don't quote a fixed number from memory.

Load references/voice-agent.md when configuring Voice Agent mode.

Broadcasts

Broadcasts send outbound messages to existing dialogue participants based on filters. They operate through channels already connected to the bot.

Audience filters: last message time window, Custom Variable values, specific channel, dialogue tags.

Send parameters: scheduled date/time, random delay range between sends (to avoid spam detection), message content (manual text or LLM-generated).

Preview: before confirming, the platform shows the count of matching dialogues.

Broadcasts are not configurable via MCP. Set them up in the Suvvy dashboard (Broadcasts tab).

User Switching

Integrators (users with an integrator subscription) can connect other users via a referral link. By default, the agent works under the integrator's profile, but the user can ask the agent to switch and work under one of the users they have connected.

How to switch:

The user names the email or company name of the desired account.
The agent calls get_user_list, passing the email or company name as a filter. Pages are numbered from zero: the first page is page: 0.
The agent finds the desired user in the response and remembers their _id.
In all subsequent MCP requests, the agent passes this _id in the optional parameter active_user_id.
If, when calling any tool with active_user_id an error is returned AUTH_PARTNER_ACCESS_FORBIDDEN — the integrator needs to manually log into the Suvvy dashboard and switch to this user's account by entering their password. After that, you can return to the agent and continue working on behalf of this user.

While active_user_id is passed, all actions are performed on behalf of the specified user. To return to the integrator's profile, stop passing this parameter.

Writing Bot System Prompts

Load references/writing-prompts.md when writing or reviewing a bot's system prompt, instruction variables, Templates (Templates in the instruction), or FAQ Document content.

Feature Selection Guide

Use this section during planning to choose the right tool for the job.

Knowledge Base: which type to use?

Situation	Use
Specific, predictable user intent with a clear answer	FAQ Document
Short structured answer, branching logic, or CRM event on retrieval	FAQ Document
Many short Q&A-shaped facts, too many/varied for fixed FAQ titles	Vector Knowledge Base
Large unstructured content — manuals, policy docs, articles	Vector Document
Content too large or varied to split into discrete intents	Vector Document
Structured reference data — price lists, catalogs, schedules	Table
Bot needs to query specific rows by value	Table
Bot hallucinates on a topic it must not answer, despite a restriction	FAQ Document (decoy / substitute direct question)

When in doubt: if you can write a clear 2–4 word title that captures the intent, it's an FAQ Document. If it's a large number of loosely related Q&A pairs, it's a Vector Knowledge Base. If it's unstructured file content, it's a Vector Document.

Custom Tools vs Integrations

Situation	Use
External API call, webhook, or custom multi-step workflow	Custom Tool
Payment, image generation, keyboard, CRM write operation	Custom Tool (via dedicated step type)
Platform has a native pre-built connector (amoCRM, Bitrix, booking)	Integration
Need to write to CRM on a simple trigger without custom logic	Integration

Custom Variables vs Memory

Situation	Use
Known fields in advance (client name, phone, chosen product)	Custom Variables
Field names are dynamic or vary per conversation	Memory (must be enabled in bot settings)

When to use auto-trigger (trigger_settings)

Use auto-trigger when the tool should fire without the bot deciding — e.g., log every new dialogue to CRM (new_dialogue), or run a check after every bot response (new_instance_response). If the bot should decide when to call the tool based on conversation context, use a normal (non-triggered) Custom Tool.

When to use Templates in the instruction (Templates in the instruction)

Use Templates when a single bot serves multiple channels or contexts that need different instruction content — different product codes per marketplace, different tone per channel, different rules based on time or client data. For a single-channel bot with no context-dependent variation, plain instruction variables ({variable}) are sufficient.

When to use Subordinate Bots / Multi-agent System

If the user mentions a "multi-agent system" (multi-agent system), they mean an architecture built from Subordinate Bots and/or bot switching — there is no separate concept on the platform.

Subordinate Bot (bot_call step) — the active bot calls another bot as a sub-agent within a single function call, gets its response, and continues the conversation. The client never sees the switch.
Bot switching (change_active_bot step) — the active bot hands the dialogue over to a different bot entirely. Pass null as instance_id to return to the original bot.

Use a Subordinate Bot when a task is complex enough to benefit from a dedicated specialist prompt. Use bot switching when the entire conversation flow should transfer to a different bot.

Bot Setup Workflow

Getting Started

A good starting point is to create the bot (create_instance, always without a template), write a first version of the system prompt, and create the initial FAQ Documents for the most common intents. That's enough to run the first test. From there, the process is iterative — add Custom Tools, Custom Variables, Memory, adjust bot settings, and keep testing.

Copying a bot — use create_instance with from_instance (an existing bot's ID) to create a full copy including instruction, knowledge base, and settings.

Auto-generation (dashboard only): the platform can generate a draft instruction and/or FAQ Documents from a text description or website URL. Use for the initial draft, then always review and edit the result before testing.

Test-Iterate Loop

Every change to the bot must be followed by a test. Core cycle:

Change something → Test → Identify issues → Fix → Reset test chat → Repeat

Test session checklist:

Get current test dialogue: get_latest_test_dialogue_for_instance_by_instance_id → save dialogue_id
Reset for clean session: get_new_test_dialogue_for_instance_by_instance_id
Send client messages one at a time: send_message_to_test_dialogue_by_id
Read responses, check for issues
If issues found — fix config, reset from step 2, repeat
Run each scenario multiple times — LLM responses are non-deterministic; a single passing run doesn't mean the bot is reliable

Always reset the test chat before starting a new scenario — stale context produces misleading results.

How to Write Test Messages

Messages in the test chat are sent from the client's perspective (message_sender: "customer"). Act as a real client in a real scenario, sending messages one at a time exactly as a user would.

Example test sequence:

→ "Привет"
→ "Хочу узнать стоимость ваших услуг"
→ "А есть скидки для новых клиентов?"
→ "Хорошо, хочу записаться на консультацию"

Tips:

Follow the intended dialogue scenario from start to finish, not just test one phrase in isolation
Vary phrasing between runs — the bot must handle natural, imperfect language
Use fake_channel to simulate a specific channel type (e.g., telegram_bot, whatsapp, amocrm) when channel-specific behaviour matters
To test employee interception: send a message as message_sender: "employee" and verify the bot freezes
Mark message as debug — use mark_message_as_debug_in_test_dialogue to "disable" a specific message in the test chat context. Useful when iterating on a long test session without resetting the entire chat.
Manual SQL query — use user_query_table to manually run SQL queries against a Table directly, useful for verifying expected rows before wiring into a Custom Tool.

Check response style, not just correctness. A technically correct answer delivered in a cold or awkward way is still a problem.

Diagnosing Issues

Load references/diagnosing-issues.md when the bot behaves unexpectedly or a test fails.

Analytics

The Analytics tab in the dashboard tracks bot performance over configurable time periods:

Metric	Description
Dialogue count	Total conversations in the period
Message breakdown	Total received / bot-handled / employee-handled
Average dialogue cost	Cost in rubles/credits
Automation rate	% of messages handled by bot without human
Tag distribution	Which Knowledge Tags appeared and how often
Function call counts	How often each function was called

Two views: Dialogs (aggregate summary) and Dialog logs (per-message detail for each dialogue).

Analytics are read-only and not accessible via MCP. Monitor via the Suvvy dashboard.

Reviewing Existing System Prompts

When auditing a bot's prompt:

Check all instructions are non-contradictory and non-duplicated
Verify each section contains only appropriate content (no FAQ data in dialogue logic, no instructions in restrictions)
Confirm every function call has a trigger condition and uses correct format
Move factual/reference data found in the prompt to FAQ Documents
Ensure dialogue steps are sequential, one action per step, and logically linked

Reducing Dialogue Costs

Load references/reducing-costs.md when optimizing bot costs or the user asks about dialogue pricing.

Uploading Files

The MCP server cannot upload files directly. Load references/uploading-files.md when any operation requires a file upload (importing Vector Documents, Vector Knowledge Base xlsx, FAQ Documents, Tables, Files to Send, Images, or test chat attachments).

Gotchas

Mistake	Fix
Factual data (prices, addresses) in system prompt	Move to FAQ Documents
Function call without trigger condition	Add "If client asks/does X..." prefix
Using Vector Knowledge Base / Vector Document for short structured answers	Use FAQ Documents instead
Multiple intents in one FAQ Document	One file = one intent
Generic FAQ Document titles	Use specific intent-based titles (2–4 words)
Calling a Vector Knowledge Base / Vector Document search function for a known specific file	Use `get_file_text` with the exact FAQ Document title instead
Using `set_memory` steps without enabling memory in bot settings	Enable `memory.is_enabled: true` via `update_instance_mcp` first
`title` and `title_for_search` mismatch — bot sees wrong description	Set `title_for_search` to an intent-based phrase the bot will recognize
Creating bot from a platform template	Always create without a template — pass no arguments to `create_instance` or use `template_code: "default"`
Expecting `test_llm_code` model to affect live dialogues	`test_llm_code` only applies in the test chat
Hitting `parallel_tool_call_limit` (field default: 1) with a scenario needing several tool calls per turn	Raise it via `update_instance_llm`, or simplify the scenario / delegate sub-tasks to Subordinate Bots
Contradictory instructions → bot calls the same function twice	Audit instruction for conflicting conditions; ensure each trigger is unique
Token overflow (context exceeds model limit)	Reduce `message_history_settings` window, shorten instruction, split large FAQ Documents
Pagination starting at 1	All paginated methods use 0-based page numbering — the first page is `page: 0`, not `page: 1`