Skip to main content

Building Bots

SendSeven has three bot types. All of them live in the Automation area of the dashboard, are managed through the /api/v1/automation API, and answer on WhatsApp, Telegram, Messenger, Instagram, Email and your website Live Chat.

Bot typeIn one sentenceGuide
FAQ BotAnswers questions in natural language from your Knowledge Base.Build an FAQ Bot
Keyword Bot (retired for new bots)Sends a fixed reply when a message matches a keyword. No AI. Existing ones keep working; build new ones as a Flow.Build a Keyword Bot
Conversational Agent (Beta)Plans each turn, picks its own tools, follows versioned skills and can finish tasks for a Flow.Conversational Agents

The FAQ Bot was called AI Assistant in earlier versions of the app and these docs. The API value did not change (see Managed with).

A Flow is not a bot, but it is the fourth building block: a visual, multi-step journey (send, wait, branch, collect input, call an API). Flows and bots work together: see Use in Flows.

The bot types​

FAQ Bot​

An FAQ Bot answers every message from your Knowledge Base using retrieval-augmented generation (RAG): it searches the folders you connected, then writes a grounded reply in the contact's language. It hands over to a human when it cannot answer with enough confidence or when the contact asks for one. Optional research capabilities (Beta) let it read images and search the web.

Use it for support, pre-sales and FAQ: open questions such as "What's your return policy?" that your documents answer.

Keyword Bot​

A Keyword Bot matches incoming messages against keyword triggers and replies with exactly what you configured: text, media, a WhatsApp template, buttons, or a Flow start. There is no AI, so replies are instant and predictable.

Use it for opening hours, price lists, out-of-office replies, simple menus and DM-trigger campaigns. It is often combined with an FAQ Bot or an agent that takes every message no keyword matched.

Retired for new bots

New Keyword Bots can no longer be created: POST /bots with bot_type: "keyword", or a PATCH that changes another bot to keyword, returns 422 with {"detail": {"code": "keyword_bots_retired", "message": "..."}}. Build new "if the message is X, send Y" automations as a Flow with a keyword_match trigger. Existing Keyword Bots keep working, and you can still edit, switch on/off and delete them.

Conversational Agent (Beta)​

An agent decides for itself what to do next: search your knowledge, search the web, remember a fact, load a skill, collect validated answers, or hand over to a human. Its behaviour comes from instructions plus reusable, versioned skills. A Flow can start an agent with a task and get structured results back.

Use it when one conversation mixes several jobs (answer, qualify, collect data, route), when you want reusable instructions across several bots, or when a Flow needs an AI step that returns data. See Conversational Agents.

Compare the bot types​

Keyword BotFAQ BotConversational Agent (Beta)
How it answersFixed replies matched on keywords. No AI.Answers every message from your Knowledge Base.Plans each turn and picks its own tools.
InstructionsPer triggerOne persona and promptInstructions plus reusable, versioned skills
KnowledgeNoneKnowledge Base folders; optionally the web and imagesChosen folders, the whole Knowledge Base, your FAQ, the web (domain-limited)
Structured dataNoneField collection (lead and appointment templates)Skill goals save validated answers to the contact; Flow tasks return outputs
Hand-offPer trigger: hand over to a human or to another botLow confidence, repeated failed answers, or escalation keywordsThe agent decides, plus keyword, turn and fallback rules
In a FlowCan start a Flow (trigger_flow response)Run AI Assistant node, target.type: "bot"Run AI Assistant node, target.type: "agent", with task and outputs
Managed with/automation/bots + /keyword-triggers/automation/bots/automation/agents and /automation/skills
PlansProfessional and aboveProfessional and aboveProfessional and above
AI creditsNoneCharged by usage per answer + web searchCharged by usage per reply (typical credits) + web search

Which one do I need?​

Is every reply the same fixed text for a known word ("hours", "menu")?
│
├── Yes  →  Flow with a keyword trigger  (Keyword Bots are retired for new bots)
│
└── No   ──▶ Is it a fixed sequence of steps
             (collect 3 fields, wait, then book a call)?
             │
             ├── Yes  →  Flow  (it can hand open questions to a bot)
             │
             └── No   ──▶ Should the bot only answer questions
                          from your documents?
                          │
                          ├── Yes  →  FAQ Bot
                          │
                          └── No, it also has to decide, collect data,
                              follow playbooks or return results  →  Conversational Agent

A common production setup: a Flow with keyword triggers for the obvious cases, with an FAQ Bot or an agent taking everything else. Workspaces that already have a Keyword Bot can keep using it for that role.

Plan availability​

All three bot types need a plan with automation: Professional, Scale or Enterprise.

  • On Basic and API Only, creating or changing bots returns 403 with error code feature_disabled (feature automation).
  • Conversational Agents additionally need the ai_agents and ai_features features. Every agent and skill endpoint returns 403 feature_disabled on Basic and API Only.

Billing​

Every message a bot sends pays the normal message charge for its channel. AI bots also use AI credits. AI credits draw from the same monthly included pool as your messages; beyond the pool, one AI credit costs EUR 0.01. Details: AI credits.

AI credits per message the bot sendsTools (per use)
Keyword BotNone (no AI work)None
FAQ BotCharged by the AI work of each answer; a greeting or hand-off notice without AI work uses noneWeb search +3
Conversational AgentCharged by the AI work of each reply at the agent's model_tier ("standard" = Fast, "advanced" = Advanced); typical credits in the price tableWeb search or live source read +3

AI credits are counted in fractions per answer; only the monthly total is rounded. Searching the Knowledge Base and translations on Fast are free; the articles an answer reads are part of its AI work.

Free: Knowledge Base searches, translations, failed or cancelled AI runs, messages sent after a failure on our side (apology, fallback, hand-over notice), bot test chats, and the agent test console up to 500 test turns per day per billing account. Agent specifics: Agent billing & limits.

Managed with​

All endpoints are under https://api.sendseven.com/api/v1/automation and use the automation:read, automation:create, automation:update, automation:publish (putting a Conversational Agent live) and automation:delete scopes.

Bot typebot_typeEndpoints
FAQ Botassistant for new bots. Older bots can carry a legacy type (support, faq, sales, lead_qualification, appointment, router, email_support); those stay valid.POST/GET /bots, GET/PATCH/DELETE /bots/{bot_id}
Keyword Botkeyword (existing bots only; new ones return 422 keyword_bots_retired)GET/PATCH/DELETE /bots/{bot_id}, plus /bots/{bot_id}/keyword-triggers (list, create, get, update, delete, reorder, CSV upload)
Conversational Agentagent (read-only on the bot endpoints)/agents and /skills. See Agents API and Skills API.

An agent also has a bot record (its bot_id). You use it for channel rules and hand-off assignment, but you cannot create an agent, change a bot to or from agent, or start a bot test chat on it through the bot endpoints (400).

GET /templates lists the starting templates. Each entry has creatable and retired flags; the Keyword Bot template has creatable: false, retired: true.

How a bot reaches contacts​

A bot does not answer anywhere until you attach it. There are two ways, and both work the same for all three bot types (agents through their bot_id):

  • Activation rules for messaging channels and email: POST/GET /bots/{bot_id}/rules, PUT/DELETE /bots/{bot_id}/rules/{rule_id}. A rule sets the channels (channel_ids, empty = all), an optional schedule with timezone, "only when no agents are online", optional contact tag filters, and a priority. When several bots match, the lower priority number wins. See Deploy to Channels.
  • Website widget: set the bot as the widget's bot so it starts every Live Chat session. See Deploy to Widget.

The bot then answers until it hands over, the session ends, or a Flow takes over.

Use in Flows​

  • The Run AI Assistant node hands the conversation to an FAQ Bot (target.type: "bot") or an agent (target.type: "agent") until an exit branch fires (for example completed, escalated or timeout), then the Flow continues. With an agent, the node can also pass a task and inputs and read structured results from vars.<prefix>.<key>. See Agents in Flows.
  • A Keyword Bot trigger can start a Flow with the trigger_flow response type. Flows also have their own keyword triggers, and they replace Keyword Bots for new automations.
  • Moving an existing bot into a Flow: Migrating to Flows.

Hand-off to humans​

  • Keyword Bot: per trigger, "hand over to human" pauses the bot and puts the conversation in your queue; "handoff bot" passes it to another bot, for example an FAQ Bot.
  • FAQ Bot: hands over after repeated low-confidence answers or when the contact types an escalation keyword (default "human", "agent", "support"). See Prompt Engineering.
  • Conversational Agent: calls its handoff tool when it decides a human is needed, plus your keyword, turn-limit and fallback rules. See Hand-off & assignment.

For the FAQ Bot and agents, who gets the conversation after a hand-off is configured on the bot record (escalation_routing_strategy, escalation_tag_id, escalation_fallback_minutes on PATCH /bots/{bot_id}; for an agent, its bot_id): any team member, the holders of a skill tag, or notify only. See Skill-based routing. A Keyword Bot hand-over leaves the conversation unassigned in your queue.

What's next​