Skip to main content

Conversational Agents (Beta)

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.

PageWhat it covers
QuickstartCreate, test and go live with an agent in six API calls
Agents APIAgents, skill links and knowledge sources
Skills APISkills, versions, import, usage
Tools & turn lifecycleWhat happens in one turn, tools and their limits
Test console & turn logRun a turn without sending (free up to 500 test turns per day), read the audit log
Skill goalsCollect validated answers, save them to the contact, run completion actions
Agents in FlowsThe Run AI Assistant node with an agent target
Hand-off & assignmentWhen the agent hands over and who gets the conversation
Customer contextVerified customer data for agents, and which mechanism to use when
Create an agent with AILet SendSeven draft the agent and its skills from your website
Billing, errors & limitsAI 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_mode unless the link overrides it:
ModeWhen the skill is part of the turn
always_onEvery turn. Use one always_on foundation skill for rules that always apply (company facts, tone, what not to do).
model_selectedWhen 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_onlyOnly 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_typeWhat the agent searches
kb_folderOne Knowledge Base folder (one source per folder)
kb_allEvery Knowledge Base folder that is enabled for AI search
faqYour FAQ: all published FAQ entries
web_searchThe 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​

ToolDefaultWhat it does
search_knowledgeonSearches the agent's knowledge sources.
web_searchoffSearches 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.
handoffonHands the conversation to a human. Needs escalation to be enabled.
set_stateonRemembers facts for the rest of the conversation.
load_skillonLoads a skill when the conversation needs it.
read_voice_messagesoffBeta. 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_messages is 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. The model_tier only 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:

Modelanguage_detection_strategyresponse_languageThe agent answers in
Auto (default)cascadenullThe contact's language
Fixedfixedthe base_language codebase_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_mode is urls_only (default: only links to your website pages) or urls_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.

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​

ScopeEndpoints
automation:readList and get agents, turns, knowledge sources; list and get skills, versions, usage and goal statistics
automation:createCreate agents and skills; all agent builder endpoints
automation:updateUpdate agents, replace an agent's skills, add/update/remove knowledge sources, run the test console; update skills and restore versions
automation:publishPublish agents, create them published, switch a paused agent on, attach it to channels (details)
automation:deleteDelete agents; delete or archive skills
automation:create and automation:updateImport 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​