Conversational Agents (Beta)
Conversational Agents are in Beta. Every endpoint in this section works end to end, but field names and limits may still change in backwards-compatible ways. Watch the changelog.
A Conversational Agent is an AI bot that reasons over a conversation and decides for itself what to do next: search your knowledge, search the web, remember a fact, load a skill, collect structured answers, or hand the conversation to a human. Agents answer on your messaging channels, in Live Chat and by email. A Flow can also start one to complete a task and get structured results back.
All agent endpoints live under https://api.sendseven.com/api/v1/automation.
| Page | What it covers |
|---|---|
| Quickstart | Create, test and go live with an agent in six API calls |
| Agents API | Agents, skill links and knowledge sources |
| Skills API | Skills, versions, import, usage |
| Tools & turn lifecycle | What happens in one turn, tools and their limits |
| Test console & turn log | Run a turn without sending (free up to 500 test turns per day), read the audit log |
| Skill goals | Collect validated answers, save them to the contact, run completion actions |
| Agents in Flows | The Run AI Assistant node with an agent target |
| Hand-off & assignment | When the agent hands over and who gets the conversation |
| Customer context | Verified customer data for agents, and which mechanism to use when |
| Create an agent with AI | Let SendSeven draft the agent and its skills from your website |
| Billing, errors & limits | AI credits, error codes, every limit in one place |
Plan availability
Conversational Agents are available on Professional, Scale and Enterprise. On Basic and API Only, every agent and skill endpoint returns 403 with error code feature_disabled. Agent replies and tool use are billed as AI credits.
Agent, FAQ Bot or Keyword Bot?
An agent plans each turn and picks its own tools, follows reusable, versioned skills, can collect validated answers with skill goals, and can return structured results to a Flow. The FAQ Bot answers every message from your Knowledge Base; the Keyword Bot sends fixed replies. The side-by-side comparison, including plans and billing, is in the Building Bots overview.
An agent also has a bot record (its bot_id), which is how it is attached to channels and how hand-off assignment is configured. You cannot create or test an agent through the bot endpoints: creating a bot with bot_type: "agent", changing a bot's type to or from agent, or starting a bot test chat on an agent's bot returns 400.
Core concepts
Agent
The agent holds the persona, instructions, language and escalation settings, tool switches, model tier, and the skills and knowledge sources it may use. See Agents API.
Skills
A skill is a named, reusable instruction set with a stable slug, for example order-return or qualify-lead. One skill can be linked to many agents.
- Versions. Every change to a skill's content creates a new, immutable version. Agents follow the current version unless the link pins a specific version. Restoring an old version copies it into a new version, so history is never rewritten.
- Description. The description says when the skill applies. It is required, because the agent uses it to decide which skills to load.
- Mode. Each link uses the skill's
default_modeunless the link overrides it:
| Mode | When the skill is part of the turn |
|---|---|
always_on | Every turn. Use one always_on foundation skill for rules that always apply (company facts, tone, what not to do). |
model_selected | When the conversation needs it. Before each turn a fast classifier reads the descriptions and preloads up to two matching skills; the agent can load more itself with the load_skill tool. |
flow_only | Only when a Flow starts the agent with this skill. |
- Tool allowlist. A skill can limit the tools available while it is loaded (
tool_allowlist). See Tools & turn lifecycle. - Goal. A skill version can carry a structured goal. See Skill goals.
Manage skills with the Skills API.
Skill goals
A skill can define a goal: the answers the agent must collect, how each answer is validated, which contact field it is saved to, and what happens when everything is collected (assign the conversation, send a webhook, start a Flow, hand over). Validation is done by SendSeven, not by the model, so only values that pass your rules are saved. See Skill goals.
Knowledge sources
source_type | What the agent searches |
|---|---|
kb_folder | One Knowledge Base folder (one source per folder) |
kb_all | Every Knowledge Base folder that is enabled for AI search |
faq | Your FAQ: all published FAQ entries |
web_search | The live web, limited to allowed_domains when set |
An agent with no Knowledge Base, FAQ or folder sources searches your whole AI-searchable Knowledge Base. Conversation-history and ticket-summary folders are never searched by an agent. See Agents API — Knowledge sources.
Tools
| Tool | Default | What it does |
|---|---|---|
search_knowledge | on | Searches the agent's knowledge sources. |
web_search | off | Searches the web. Also needs an enabled web_search knowledge source. web_search_mode sets when: the agent decides, only when the knowledge base found nothing, or always. |
handoff | on | Hands the conversation to a human. Needs escalation to be enabled. |
set_state | on | Remembers facts for the rest of the conversation. |
load_skill | on | Loads a skill when the conversation needs it. |
read_voice_messages | off | Beta. Transcribes the voice notes a contact records and answers the text. See Voice messages. |
complete_task | — | Only when a Flow gives the agent a task. Not configurable. |
Turn tools on or off with tools_config. Limits and details are in Tools & turn lifecycle.
Voice messages (Beta)
Agents are not text-only. With read_voice_messages: true in tools_config, an agent transcribes the voice notes a contact records (a WhatsApp or Telegram voice note, a Messenger or Instagram audio clip, a recording in Live Chat) and answers the text as if the contact had typed it, in the language the contact spoke. The setting is off by default; in the app it is Understand voice messages on the agent's Tools tab.
- Only voice notes. Audio files a contact attaches, such as an MP3, are not voice notes: they are not transcribed automatically, and an audio file sent on its own gets no answer. Your team can still transcribe any audio message on demand (see Voice Message Transcription).
- Limits. Up to 5 minutes and 20 MB per voice note, up to 3 voice notes per reply. Every transcribed voice note counts toward
max_attachments_per_conversation, together with images and PDFs. - When it cannot listen. If
read_voice_messagesis off, or a voice note cannot be transcribed (too long, no speech, limit reached), the agent replies in the contact's language asking them to write their message as text. If the contact also sent text or an image, the agent answers that and asks them to write the voice part. This reply is free. - Transcript on the message. The transcript is stored on the message (
meta.transcript,meta.transcript_language,meta.transcript_status) and shown to your team under the audio player. A message is transcribed only once. See Transcript fields. - Transcription level. The model that transcribes follows the workspace's Voice message transcription level in Settings > AI (Advanced by default, or Fast), not the agent's
model_tier. Themodel_tieronly decides how the agent writes its reply. - Billing. Each transcribed voice note is part of the reply's AI work and is billed by actual usage, only when the reply was sent: typically about 0.9 to 1.6 AI credits with Advanced, or about 0.25 to 0.5 with Fast (30-second to 1-minute voice note). Longer recordings use more. Failed or skipped voice notes are free.
The transcript is customer content, never instructions to the agent. Details: Tools & turn lifecycle: Voice messages.
Model tier
model_tier is standard ("Fast", the default: quickest, typically about 1 to 2 AI credits per reply) or advanced ("Advanced": stronger reasoning for harder conversations, about 3.3 times Fast for the same work, typically about 3 to 8 AI credits per reply, with a fixed 15-second turn budget). Web search credits are the same for both. If the advanced model is unavailable for a step, that step falls back to the standard model and is charged at the Fast level. The model that answered is returned as model on the test console and the turn log.
Language
An agent has two language modes, set in language_settings:
| Mode | language_detection_strategy | response_language | The agent answers in |
|---|---|---|---|
| Auto (default) | cascade | null | The contact's language |
| Fixed | fixed | the base_language code | base_language |
Set both fields together when you switch modes. If you only change the strategy, an old response_language stays set and the agent keeps answering in that language. See Agents API — Language settings and Tools & turn lifecycle — Language.
Customer context
An agent can know who it is talking to. Contact tokens, signed identity, contact verification, context endpoints, custom fields with AI access and summaries of earlier conversations give it customer data, each value labelled as verified (a fact) or unverified (a claim). The agent personalises with both but only acts on facts. Each agent's Context tab (settings.context) decides what it may read and which contact fields it may fill in. See Customer context and Agent context sources.
Provenance and source footers
Every agent reply carries the sources it was based on in meta.provenance (max 8, kb, faq or web) and the answering agent in meta.agent_id. See Bot and agent message metadata.
Optionally, the reply also shows its sources to the contact:
- Knowledge Base sources footer: off by default. Turn it on with
source_footer_enabled.source_footer_modeisurls_only(default: only links to your website pages) orurls_and_kb(also a generic "Knowledge Base" line for FAQ and document sources). - Web search footer: always added when the agent used web search in that reply. It cannot be turned off.
Link check
Before a reply is sent, SendSeven checks every link on your own domains: domains that appear in the agent's persona, instructions or skills, in Knowledge Base documents found in this turn, or in allowed_domains. A link that does not appear in one of those sources is repaired to the closest known URL when it is a near miss (for example a mistyped domain), or removed otherwise. Links to other websites are left alone. Repairs show up as link_fixes in the test console.
Test console
POST /automation/agents/{agent_id}/test runs one turn against your real configuration. Nothing is sent to a contact and nothing is billed. It works while the agent is inactive, so you can test before you go live. See Test console & turn log.
Required scopes
| Scope | Endpoints |
|---|---|
automation:read | List and get agents, turns, knowledge sources; list and get skills, versions, usage and goal statistics |
automation:create | Create agents and skills; all agent builder endpoints |
automation:update | Update agents, replace an agent's skills, add/update/remove knowledge sources, run the test console; update skills and restore versions |
automation:publish | Publish agents, create them published, switch a paused agent on, attach it to channels (details) |
automation:delete | Delete agents; delete or archive skills |
automation:create and automation:update | Import skills |
Hand-off assignment is configured on the agent's bot record (PATCH /automation/bots/{bot_id}, automation:update), and channel rules use /automation/bots/{bot_id}/rules (creating or changing a rule on an agent's bot also needs automation:publish).
Next steps
- Quickstart — build your first agent
- Run AI Assistant node — start an agent from a Flow
- Skill-based routing — route agent hand-offs to the right team members
- AI credits — how agent usage is billed
- Knowledge Base — manage the content agents search