Skip to main content

Agents API

Beta

Conversational Agents are in Beta and available on Professional, Scale and Enterprise. On other plans every endpoint returns 403 {"detail": {"code": "feature_disabled", "feature": "ai_agents"}}.

Base URL: https://api.sendseven.com/api/v1/automation

MethodPathScopeSuccess
GET/agentsautomation:read200 paginated list
POST/agentsautomation:create201 agent
GET/agents/{agent_id}automation:read200 agent
PATCH/agents/{agent_id}automation:update200 agent
DELETE/agents/{agent_id}automation:delete200 {success, id, message}
PUT/agents/{agent_id}/skillsautomation:update200 agent
GET / PUT / DELETE/agents/{agent_id}/draftautomation:read / automation:update200 draft — see Drafts & publishing
POST/agents/{agent_id}/publishautomation:publish200 agent — see Who can publish
POST/agents/{agent_id}/avatarautomation:update200 draft — see Avatar
GET/agents/insights/overview?days=30automation:read200 — see Insights overview
GET/agents/{agent_id}/knowledge-sourcesautomation:read200 list
POST/agents/{agent_id}/knowledge-sourcesautomation:update201 source
PATCH/agents/{agent_id}/knowledge-sources/{source_id}automation:update200 source
DELETE/agents/{agent_id}/knowledge-sources/{source_id}automation:update200 {success, id, message}
GET / POST / PATCH / PUT / DELETE/lookup-tables…automation:*see Lookup tables
POST/agents/{agent_id}/testautomation:update200 — see Test console
GET/agents/{agent_id}/turnsautomation:read200 — see Turn log
GET/agent-turns/{turn_id}automation:read200 — see One turn
GET/agents/{agent_id}/feedbackautomation:read200 — see Answer ratings & feedback
GET/agents/{agent_id}/skill-suggestionsautomation:read200 — see Skill suggestions
POST/agents/{agent_id}/skill-suggestions/generateautomation:update201 suggestion
POST/agents/{agent_id}/skill-suggestions/{suggestion_id}/approveautomation:update200 {suggestion, skill_version}
POST/agents/{agent_id}/skill-suggestions/{suggestion_id}/dismissautomation:update200 suggestion
GET/hub/stats?days=30automation:read200 — see Agents overview
POST/bots/{bot_id}/duplicateautomation:create201 bot — see Duplicate an agent
GET/hub/templatesautomation:read200 {items} — see Templates
POST/hub/templates/{key}/createautomation:create201 {agent_id, bot_id}

List agents​

GET /agents?page=1&page_size=50&search=support

ParameterNotes
pageDefault 1
page_sizeDefault 50, max 100
searchOptional, max 100 characters, matches the name

Returns {"items": [Agent, …], "pagination": {…}}.

Create an agent​

POST /agents — unknown fields are rejected with 422.

{
"name": "Shop Support",
"is_active": false,
"persona": "You are Mia, the friendly support assistant of Example Shop.",
"instructions": "Answer questions about orders, shipping and returns.",
"model_tier": "standard",
"display_name": "Mia",
"greeting_message": "Hi! I'm Mia. How can I help?",
"language_settings": {"base_language": "en", "response_language": null},
"escalation": {"enabled": true, "handoff_message": "I'm connecting you with a colleague."},
"tools_config": {"search_knowledge": true, "web_search": false, "handoff": true, "set_state": true},
"handoff_config": {"keywords": ["human"], "max_turns": 30, "max_consecutive_fallbacks": 2, "handoff_tag_ids": ["TAG_ID"], "handoff_tag_hints": {"TAG_ID": "billing questions, invoices, refunds"}},
"skills": [{"skill_id": "SKILL_ID", "mode": null, "pinned_version_id": null}],
"knowledge_sources": [{"source_type": "faq"}]
}

Fields​

FieldTypeNotes
namestringRequired on create. 1-255 characters.
is_activebooleanDefault true. Create agents inactive, test them, then activate. Switching a paused agent on needs automation:publish.
publishbooleanCreate only. Default false (since 16 November 2026, before: true): the agent is created never-published (publish_state: "draft") and does not answer contacts until you publish it. true puts it live on create and needs automation:publish (see Who can publish).
personastringWho the agent is and how it speaks. Max 20,000 characters.
instructionsstringWhat the agent does. Max 20,000 characters.
model_tierstandard | advancedDefault standard ("Fast", typically about 1 to 2 AI credits per reply). advanced ("Advanced") costs about 3.3 times as much for the same work (typically about 3 to 8 per reply) and always uses a 15-second turn budget (turn_timeout_ms is ignored). Web search credits are the same.
display_namestringName shown to contacts. Max 255.
greeting_messagestringMax 2,000. Blank clears it.
ai_disclosure_messagestringThe notice that the contact is talking to an AI. Max 2,000. It cannot be removed: blank or null uses the built-in, localized default.
ai_disclosure_include_escalationbooleanAlso tell the contact how to reach a human. Default true.
language_settingsobjectSee Language settings.
escalationobjectSee Escalation settings.
tools_configobjectSee Tools.
handoff_configobjectSee Hand-off config.
max_tool_callsintegerTool calls allowed per turn. Default 4. Values outside 1..6 are clamped, not rejected.
turn_timeout_msintegerLegacy automatic time budget per turn for model_tier: standard, used only while turn_time_limits.default is not set. Default 8000. Values outside 2000..15000 are clamped. advanced agents always get 15000.
turn_time_limitsobjectResponse time limit per turn, in seconds. See Turn time limits.
add_detected_languagesbooleanAdd languages the agent detects from the contact to the contact's languages list. Default true. See Add detected languages to the contact.
auto_language_switchbooleanSwitch the reply language and the contact's default language when the contact asks for a language or clearly writes in another one. Default true. See Automatic language switch.
greeting_enabledbooleanSend the agent's greeting. Default true. See Greeting options.
skip_greeting_on_questionbooleanSkip the greeting when the first message is already a question or request. Default true. See Greeting options.
greet_on_direct_startbooleanCreate only; read-only afterwards. true on every agent created through the API, a template, the AI builder or a duplicate (send false on create to keep the earlier behaviour). Agents created before this field existed return false. See Greeting options.
email_settingsobjectHow the agent answers emails. See Email settings.
flow_running_behaviorpause | stop | keepWhat the agent does while a flow is running in the conversation. Default pause. See While a flow is running.
source_footer_enabledbooleanShow a "Sources" footer under answers based on your knowledge. Default false.
source_footer_modeurls_only | urls_and_kbDefault urls_only (links to your website pages only). urls_and_kb also adds a generic "Knowledge Base" line for FAQ and document sources.
source_link_paramsobjectQuery parameters added to your website links in the footer, per channel. See Source link parameters.
settingsobjectFree-form settings, max 16 KB, max 6 levels deep.
skillsarrayCreate only. Up to 50 skill links.
knowledge_sourcesarrayCreate only. Up to 20 knowledge sources.

PATCH /agents/{agent_id} accepts the same fields except skills and knowledge_sources, all optional. Use PUT /agents/{agent_id}/skills and the knowledge source endpoints for those.

Language settings​

FieldNotes
base_languageMax 10 characters. The agent's main language. Response default en.
response_languagenull or auto = answer in the contact's language. A language code = always answer in that language.
language_detection_strategycascade (default behaviour) or fixed (always answer in base_language).
auto_translate_messagesboolean

PATCH updates only the language fields you send; omitted fields keep their value.

Auto vs fixed. These are the two language modes the app and the agent builder use:

Modelanguage_detection_strategyresponse_languageThe agent answers in
AutocascadenullThe contact's language
Fixedfixedthe base_language codebase_language

To switch an agent from fixed to auto, send both fields. If you only change the strategy, the old response_language stays set and the agent keeps answering in that language:

PATCH /agents/{agent_id}
{"language_settings": {"language_detection_strategy": "cascade", "response_language": null}}

To switch to fixed, send {"language_detection_strategy": "fixed", "response_language": "<base_language>"}.

Add detected languages to the contact​

add_detected_languages (boolean, default true, also for existing agents) lets the agent remember the languages a contact writes in. When the agent detects the contact's language for the first time in a conversation, or switches because the contact writes in a different language, it appends that code to the contact's languages list. Example: a contact with preferred language de writes in Turkish and the agent switches to tr; the contact's languages becomes de,tr.

  • The contact's preferred language never changes, and neither does the language the agent answers in.
  • Only languages detected from the contact count. A fallback to base_language or language_detection_strategy: "fixed" never adds a code.
  • A code the contact already has (as language or in languages) is not added again. Each added code updates the contact and fires the contact.updated webhook.

Send it as a top-level add_detected_languages field or inside settings.add_detected_languages (the top-level field wins). On PATCH, omitted or null keeps the current value. In the draft document it is saved with the other agent settings and goes live when you publish. Responses always return a boolean.

Automatic language switch​

auto_language_switch (boolean, default true, also for existing agents) lets the agent change language when the contact wants it:

  • Explicit request. A message such as "English please", "auf Deutsch bitte" or "Türkçe konuşabilir misiniz?" switches the reply language from that reply on and sets it as the contact's default language. A message that only mentions a language ("I speak English poorly, but...") does not count.
  • Clear writing. When the contact keeps writing in another language, the agent switches and sets the new default language. A language that was only inferred from the contact's phone number switches after one clear message.
  • A default language set by a person, an import or the API is kept unless the contact explicitly asks for another language.
  • Each change updates the contact (the previous default stays in languages), fires the contact.updated webhook and adds an internal note to the conversation. Test-console turns never change the contact.

With false, the agent still follows the contact's language in its replies but never changes the contact's default language. Agents with response_language set to a fixed language never switch.

Greeting options​

FieldDefaultEffect
greeting_enabledtrueWith false the agent sends no greeting and answers the contact's first message directly.
skip_greeting_on_questiontrueWhen the first message is a question or request (not only "Hi"), the agent skips the greeting and answers it.

The greeting carries the AI disclosure. It is sent when a flow starts the agent, when a live chat widget auto-starts it, or on Telegram /start. When skip_greeting_on_question skips it, the disclosure opens the agent's first chat reply once, in the language of that reply. Automatically sent emails carry the disclosure in the sign-off when they name the agent (see the table below for new agents). After a handoff between agents only the first agent sends it.

greet_on_direct_start changes these things:

greet_on_direct_start: true (new agents)false (agents created earlier)
Agent answers a channel directly through its activation rules (no flow)Greeting and disclosure are sent first, exactly like a flow start (skip_greeting_on_question applies). Not on email and not for Assist drafts.Nothing is sent before the answer.
greeting_enabled: false, or greeting_message emptyNo greeting and no disclosure, on every start path.No greeting; the disclosure opens the first reply. An empty greeting_message uses the built-in default greeting.
ai_disclosure_message emptyNo disclosure; the greeting is still sent.The built-in default disclosure is used.
Automatically sent email (email_settings.reply_mode: "auto")Only ai_disclosure_message is used. Names the agent: the sign-off carries it. Does not name the agent: it is appended once, to the first automatically sent email of the agent session. Empty ai_disclosure_message: no disclosure in any email.Names the agent: sign-off with ai_disclosure_message, or the built-in "virtual AI assistant" text when empty. Does not name the agent: nothing is added.

On create, greeting_message and ai_disclosure_message are filled with the built-in default texts in the agent's base_language (English when no built-in text exists for it) when you send no non-empty value. The disclosure default keeps the {name} placeholder. Blank values are stored as null. greet_on_direct_start itself is never changed by PATCH, settings or a draft publish: a value sent there is ignored.

The greeting itself is written in the language of the contact's first message when that message is long enough to identify the language.

Send greeting_enabled, skip_greeting_on_question and auto_language_switch as top-level fields or inside settings (the top-level field wins). On PATCH, omitted or null keeps the current value; any non-boolean inside settings returns 422. In the draft document they are saved with the other agent settings and go live when you publish. Responses always return booleans.

Escalation settings​

Same names and meaning as on the FAQ Bot:

FieldNotes
enabledWhether the agent may hand over to a human. With false, the handoff tool is not offered and the deterministic triggers do not fire.
offers_escalationboolean
handoff_messageSent to the contact on hand-over. Max 2,000.
escalation_keywordsUsed when handoff_config.keywords is not set.
offline_escalation_behaviorLive chat: what happens when nobody is online.
offline_message, outside_hours_messageMax 2,000 each.
is_escalation_schedule_enabled, escalation_timezone, escalation_scheduleThe agent's own hand-over schedule (used in custom mode).
escalation_schedule_mode"workspace" (follow the workspace business hours) or "custom" (own schedule). Always set in responses; see Team availability.

Routing a hand-over to a team member is configured on the agent's bot record. See Hand-off & assignment.

Tools config​

KeyDefaultNotes
search_knowledgetrue
web_searchfalseAlso needs an enabled web_search knowledge source. Set it explicitly.
web_search_modemodel when web_search is on, else offWhen the agent searches the web: off, model (the agent decides, using the web_search tool), kb_fallback (every search_knowledge call that finds nothing also searches the web with the same query) or always (the first search_knowledge call of each reply also searches the web). Setting a mode also sets web_search (off → false, anything else → true); setting web_search to false sets the mode to off. Agents created before this setting existed keep model. GET always returns the effective mode. See Web search modes.
live_modemodelWhen the agent reads its live sources (live_source knowledge sources with scope: "agent"): off, model (the agent decides, using the read_live_source tool), kb_fallback (read when the Knowledge Base finds nothing) or always (read on every reply). Send null to go back to the default. GET always returns the effective mode.
web_cache_ttl_minutesnot set10-60. How long identical web searches of this agent are reused. Send null to remove it.
handofftrueOnly offered while escalation is enabled.
set_statetrue
load_skilltrue
read_imagesfalseBeta. Read images the contact sends. The agent opens a file only when the conversation needs it; reading it is part of the reply's AI work (typically about 0.5 AI credits per image on Fast, about 0.8 on Advanced). Also sets the bot record's vision_enabled.
read_documentsfalseBeta. Read PDF documents the contact sends, charged like images (part of the reply's AI work, typically about 0.8 AI credits per PDF on Fast, about 1.4 on Advanced).
read_voice_messagesfalseBeta. Transcribe the voice notes the contact sends and answer the text as if it had been typed. Audio files that are not voice notes are not transcribed. Charged like images (part of the reply's AI work). When off, the agent replies asking the contact to write their message instead. Up to 3 voice notes per reply, each up to 5 minutes and 20 MB. The transcription model follows the workspace Voice message transcription level, not model_tier. See Voice messages.
max_images_per_message31-3. Further images in the same message are skipped.
max_attachments_per_conversation101-50. Images, PDFs and voice notes read in one conversation; after that, files are skipped.

Unknown keys are rejected. complete_task is not configurable: it exists only when a Flow gives the agent a task. Details in Tools & turn lifecycle.

On PATCH, tools_config is merged into the stored settings: send only the keys you want to change. Responses always contain every key with its effective value. Turn image reading on or off with read_images: it also updates the bot record's vision_enabled. An agent created before read_images existed reports its bot's vision_enabled until you set read_images. Limits and behaviour: Images and PDFs.

Hand-off config​

FieldNotes
keywordsUp to 50 words (max 100 characters each, de-duplicated case-insensitively). A contact message containing one hands over immediately, before any AI call. When not set, the escalation keywords are used.
max_turns1..200. Hands over once the conversation goes past this many contact turns.
max_consecutive_fallbacks1..20, default 2. Hands over after this many turns in a row in which the agent could not answer.
handoff_tag_idsUp to 20 tag ids from your workspace. The agent may pick one of them when it hands over, and the tag is added to the conversation. Unknown tags: 422 {"code": "invalid_handoff_tags", "message": "Unknown handoff tag(s)", "tag_ids": […]}.
handoff_tag_hintsOptional object {tag_id: "when to use"}, shown to the agent next to each tag. Text is trimmed, empty hints are dropped, each hint is at most 200 characters (longer: 422), at most 20 entries. Hints for tag ids not in handoff_tag_ids are dropped on save. Default {}.
handoff_messageMax 2,000. Message sent on hand-over.

handoff_config may be at most 8 KB serialized.

Turn time limits​

turn_time_limits sets how long one turn may take before the agent answers with what it has, per channel group:

KeyNotes
defaultEvery channel. null means the legacy automatic budget (turn_timeout_ms, 15 seconds for advanced).
live_chatLive Chat override. null means the same as default.
emailEmail override. null means the same as default.
  • Allowed values are 30 and 60 seconds (also listed in the response as turn_time_limit_options). 60 seconds is the maximum: a higher value returns 422. A limit above 60 seconds saved earlier is returned and applied as 60, and stored as 60 the next time the agent is saved.
  • New agents start with {"default": 30}. Agents created before this setting existed keep the automatic budget until you set default.
  • Overrides apply only while default is set. When it is set, the limit is the whole turn budget for both model tiers and turn_timeout_ms is ignored.
  • Send it as a top-level turn_time_limits field or inside settings.turn_time_limits (the top-level field wins). Both are partial: omitted keys keep their value and null clears a key.
  • Only the keys default, live_chat and email are accepted. Another key or value returns 422 with code invalid_turn_time_limit.
  • The response always contains all three keys.

While a flow is running​

flow_running_behavior decides what the agent does in a conversation where a flow run is active:

ValueBehaviour
pause (default)The agent stays silent while the run is active. It answers again from the next incoming message after the run completes, fails, is canceled or times out. A run that waits past its timeout no longer counts as active.
stopWhen a flow run starts in the conversation, the agent is turned off for that conversation, the same as when a person takes over. It answers again only after a person turns it back on, or when a flow step hands the conversation to the agent.
keepThe agent keeps answering while the run is active.
  • Whether the agent may answer the incoming message that started a flow run is decided by the flow's agent_reply_to_trigger setting, not by this one. A run that lets the agent answer that message does not pause the agent for it. A flow step that hands the conversation to the agent is the flow's own reply and is not blocked.
  • A flow can override this value with its own agent_while_running setting.
  • Omitted on create means pause; omitted on PATCH keeps the current value. Any other value returns 422. The response always contains a concrete value.

Email settings​

email_settings controls how the agent answers emails:

KeyNotes
reply_modedraft (default): every reply is saved as a draft for your team. auto: a reply whose confidence reaches confidence_threshold is sent, anything below becomes a draft.
confidence_thresholdInteger 0 to 100. Default 80.
triage_skill_idA skill of this workspace that decides which emails get a reply at all, see Email triage skills. null (default) uses the built-in triage and clears a set skill.
  • Send it as a top-level email_settings field or inside settings.email_settings (the top-level field wins). Both are partial: omitted keys keep their value.
  • A wrong type, a value out of range or an unknown key returns 422 with code email_settings.invalid. A triage_skill_id that is not a skill of this workspace returns 422 email_settings.invalid_skill.
  • Even with reply_mode: "auto", a reply is saved as a draft when it is not backed by your knowledge, skills or verified contact data, when the sender could not be verified, or when a check could not run.
  • Contact-form emails: when a website contact form sends the email and names the customer in Reply-To, the agent treats that address as the sender and always saves its reply as a draft, also with reply_mode: "auto".

Add tracking parameters to links to your website pages in the sources footer. Keys are channel types, or default:

{
"source_link_params": {
"default": {"utm_source": "sendseven", "utm_medium": "{channel_type}"},
"live_chat": {"utm_source": "chat", "utm_content": "{widget_id}"}
}
}

Placeholders: {bot_id}, {bot_name} (as a URL slug), {channel_type}, {channel_id}, {tenant_id}, {widget_id} (Live Chat only). A parameter whose placeholder cannot be filled for a message is left out.

Response​

{
"id": "…",
"bot_id": "…",
"tenant_id": "…",
"name": "Shop Support",
"is_active": false,
"persona": "…",
"display_name": "Mia",
"avatar_url": null,
"greeting_message": "…",
"ai_disclosure_message": null,
"ai_disclosure_include_escalation": true,
"instructions": "…",
"model_tier": "standard",
"language_settings": {"response_language": null, "base_language": "en", "auto_translate_messages": false, "language_detection_strategy": null},
"escalation": {"enabled": true, "offers_escalation": true, "handoff_message": "…", "escalation_keywords": null, "offline_escalation_behavior": "leave_message", "offline_message": null, "outside_hours_message": null, "is_escalation_schedule_enabled": false, "escalation_timezone": "UTC", "escalation_schedule": null, "escalation_schedule_mode": "workspace"},
"source_footer_enabled": false,
"source_footer_mode": "urls_only",
"source_link_params": null,
"tools_config": {"search_knowledge": true, "web_search": false, "handoff": true, "set_state": true, "load_skill": true, "read_images": false, "read_documents": false, "read_voice_messages": false, "max_images_per_message": 3, "max_attachments_per_conversation": 10},
"handoff_config": {"keywords": ["human"], "max_turns": 30, "max_consecutive_fallbacks": null, "handoff_tag_ids": [], "handoff_message": null},
"max_tool_calls": 4,
"turn_timeout_ms": 8000,
"turn_time_limits": {"default": 30, "live_chat": null, "email": 60},
"turn_time_limit_options": [30, 60],
"add_detected_languages": true,
"auto_language_switch": true,
"greeting_enabled": true,
"skip_greeting_on_question": true,
"greet_on_direct_start": true,
"email_settings": {"reply_mode": "draft", "confidence_threshold": 80, "triage_skill_id": null},
"flow_running_behavior": "pause",
"settings": null,
"skills": [
{"skill_id": "…", "slug": "order-return", "title": "Order returns", "mode": null, "effective_mode": "model_selected", "pinned_version_id": null, "current_version": 3, "pinned_version": null, "is_archived": false, "sort_order": 0}
],
"knowledge_sources": [
{"id": "…", "source_type": "faq", "kb_folder_id": null, "kb_folder_name": null, "allowed_domains": null, "is_enabled": true, "config": null, "sort_order": 0, "created_at": "2026-10-05T09:00:00Z", "updated_at": "2026-10-05T09:00:00Z"}
],
"publish_state": "published",
"has_unpublished_changes": false,
"draft_updated_at": null,
"published_at": "2026-10-05T09:00:00Z",
"created_at": "2026-10-05T09:00:00Z",
"updated_at": "2026-10-05T09:00:00Z"
}

publish_state, has_unpublished_changes, draft_updated_at and published_at are explained in Drafts & publishing. The fields above always show the live configuration.

Delete an agent​

DELETE /agents/{agent_id} deletes the agent with its bot record, channel rules, sessions, skill links and knowledge sources. Skills themselves are kept.

While a published or paused Flow uses the agent, the delete is refused:

{
"detail": {
"code": "agent_in_use",
"message": "This agent is used by published or paused flows. Remove it from these flows first.",
"flows": [{"id": "…", "name": "Returns", "status": "published", "node_ids": ["node_7"]}]
}
}

Duplicate an agent​

POST /bots/{bot_id}/duplicate (automation:create) copies a Conversational Agent inside the same workspace and returns the new bot (201, same shape as GET /bots/{bot_id}).

{"name": "Support (EN)"}

name is optional. Without it the copy is called <name> (Kopie) in German workspaces and <name> (copy) otherwise.

CopiedNot copied
Persona, instructions, greeting, language, escalation and tool settingsChannel rules (the copy is not connected to any channel)
Skill links incl. mode and pinned versions (the skills are shared, not cloned)Conversations, sessions, replies, ratings, feedback, skill suggestions
Knowledge sources: Knowledge Base folders, FAQ, web search domains, live sourcesUsage counters and history

The copy is paused (is_active: false) and placed last in the bot order. Only Conversational Agents can be duplicated: other bot types return 422 {"detail": {"code": "duplicate_classic_not_supported"}}. A bot from another workspace returns 404.

Templates​

GET /hub/templates (automation:read) lists the ready-made agent templates in a fixed order:

{"items": [{"key": "product_faq", "has_goal": false, "suggested_channels": ["whatsapp", "live_chat", "email"], "skills": ["answer-product-questions"]}]}

Keys: product_faq, customer_support, lead_qualification, appointment_booking, email_reply, feedback_nps. has_goal is true when a template skill collects data with a goal. Titles and descriptions are not returned; show your own copy per key.

POST /hub/templates/{key}/create (automation:create) creates a paused agent with persona, greeting, hand-off message, skills and knowledge sources (Knowledge Base + FAQ) from the template, written in your workspace language (German or English; other languages get English). Returns 201 {"agent_id": "…", "bot_id": "…"}. No AI credits are used. Unknown key: 404 template_not_found. Duplicate and template create use the same plan gate as POST /agents.

Agents overview​

GET /hub/stats?days=30 (automation:read) returns KPIs and one row per bot of the workspace (Conversational Agents and classic bots, paused ones included), in the same order as PUT /bots/reorder. days is 7, 30 (default) or 90 calendar days in your workspace timezone, today included; any other value returns 422.

{
"range_days": 30, "period_start": "2026-09-06T22:00:00Z", "period_end": "2026-10-06T21:59:59Z",
"series_dates": ["2026-09-07", "…", "2026-10-06"], "min_sample": 20, "truncated": false,
"totals": {"conversations": 808, "conversations_prev": 721, "conversations_delta_pct": 12.07,
"resolved": 513, "resolved_pct": 63.5, "handoffs": 295, "handoff_pct": 36.5,
"insufficient_data": false, "credits": 1412, "credits_eur": 14.12},
"agents": [{
"bot_id": "BOT_ID", "agent_id": "AGENT_ID", "name": "Support Agent", "bot_type": "agent", "kind": "agent",
"subtitle": {"type": "goal", "label": "Book a demo"}, "status": "live", "has_unpublished_changes": false,
"priority": 3, "avatar_url": null,
"channels": [{"channel_id": "CHANNEL_ID", "channel_type": "whatsapp", "name": "WA Support"}],
"skills_count": 5, "conversations": 120, "conversations_prev": 98, "resolved": 98, "resolved_pct": 81.7,
"handoffs": 22, "handoff_pct": 18.3, "insufficient_data": false, "credits": 310,
"sparkline": [0, 3, 5], "updated_at": "2026-10-04T10:12:00Z", "updated_by_name": null
}]
}

Definitions (shared with GET /analytics, GET /bots/{bot_id}/analytics and agent analytics, so the numbers always match):

  • Conversation: a conversation the bot replied in during the period, counted once per bot, dated by its first reply. Test-console replies are not counted.
  • Handoff: a conversation in which the bot handed over to your team. Resolved = conversations − handoffs. Both percentages are always between 0 and 100.
  • resolved_pct / handoff_pct per bot are null (and insufficient_data: true) below min_sample (20) conversations. In totals they are null only without conversations; a conversation several bots replied in counts once there.
  • conversations_prev is the same-length window before; conversations_delta_pct is null when it is 0.
  • credits are the AI credits Conversational Agents used (classic bots show 0); credits_eur uses your plan's AI credit price.
  • status: paused = switched off; not_connected = switched on, but no active channel rule (or published Flow) can route a message to it; otherwise live.
  • subtitle.type: goal (label = title of the first skill with a goal), template (label = template key) or none.

PUT /agents/{agent_id}/skills replaces all of the agent's skill links. Send an empty list to unlink every skill.

{
"skills": [
{"skill_id": "SKILL_ID_BASICS", "mode": "always_on"},
{"skill_id": "SKILL_ID_RETURNS", "pinned_version_id": "VERSION_ID", "sort_order": 1}
]
}
FieldNotes
skill_idRequired. A skill in your workspace.
modealways_on, model_selected, flow_only or null (use the skill's default_mode).
pinned_version_idnull = follow the skill's current version. Otherwise a version of this skill; the agent keeps using it when the skill changes.
sort_order0..10000
sourcesOptional per-skill source override (see below). Omit it to keep the stored override; send null to remove it.

sources changes the agent's sources while this skill is loaded:

{"skill_id": "SKILL_ID_PRICES", "sources": {"web_search_mode": "off", "live_source_ids": ["LIVE_SOURCE_ID"], "live_mode": "always", "kb_folder_ids": ["KB_FOLDER_ID"], "kb_mode": "add"}}
KeyNotes
web_search_modeoff, model, kb_fallback, always or null (use the agent's mode).
live_source_idsUp to 5 ids of this agent's live_source knowledge sources. Any other id returns 422 {"code": "invalid_skill_sources"}.
live_modemodel, kb_fallback, always or null (use the agent's live_mode).
kb_folder_idsUp to 10 Knowledge Base folder ids searched while this skill is loaded, subfolders included. Any folder of your workspace works (also one the agent has no source for), except the system folders for conversation history and ticket summaries. An unknown id returns 422 {"code": "invalid_skill_sources"}.
kb_modeadd (default, also for null): the agent's own Knowledge Base sources plus these folders. only: only these folders while the skill is loaded. only needs at least one folder (422 otherwise); without folders kb_mode is ignored.

Knowledge Base scope when several skills are loaded. One reply can load several skills, so SendSeven searches the union of what they allow:

  • The folders of every loaded skill that has kb_folder_ids are searched (add and only alike).
  • The agent's own Knowledge Base sources (its kb_all, kb_folder and faq sources, or the whole Knowledge Base when it has none) are searched too, unless every loaded skill with a Knowledge Base override is only. A single loaded skill with add, or with no Knowledge Base override at all, brings them back.
  • Skills with mode always_on that have no Knowledge Base override do not count: they are loaded on every reply, so they would otherwise cancel only everywhere. An always_on skill with kb_mode: "only" narrows every reply unless another loaded skill says add.
  • Conversation-history and ticket-summary folders are never searched, also not through a skill.

This is relevance scoping, not access control. The AI picks model_selected skills from the conversation, so a customer can steer which skill loads. Keep sensitive content behind a skill that only a Flow loads (flow_only) or behind identity verification.

Overrides are stored in the agent's settings.skill_sources (keyed by skill id) and can also be written there with PATCH /agents/{agent_id}, validated the same way. A PATCH whose settings leave out skill_sources keeps the stored overrides; "settings": null clears everything. Overrides of skills that are no longer linked are dropped, and deleting a live source removes its id from every override. A deleted Knowledge Base folder disappears from every override on read; when a skill loses all its folders, its Knowledge Base override is removed (kb_folder_ids: [], kb_mode: null), so only never searches nothing. Responses show each link's override in skills[].sources (null = none) with all five keys.

Max 50 links. Returns 422 for a duplicate skill_id, an unknown skill_id, an archived skill, or a pinned_version_id that does not belong to the skill. The response is the full agent; each link shows effective_mode, current_version and pinned_version.

Knowledge sources​

source_typeExtra fieldsSearches
kb_folderkb_folder_id (required)One Knowledge Base folder
kb_all—Every folder that is enabled for AI search
faq—All published FAQ entries
web_searchallowed_domains (optional, max 50)The web, limited to these domains when set
live_sourceconfig (required, see below)One web page, read live when the agent answers
lookup_tableconfig (required, see below)One lookup table: exact matches on its search columns
curl -X POST "https://api.sendseven.com/api/v1/automation/agents/AGENT_ID/knowledge-sources" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"source_type": "web_search", "allowed_domains": ["https://www.example.com/help", "docs.example.com"]}'
FieldNotes
source_typeCreate only, cannot be changed.
kb_folder_idOnly for kb_folder.
allowed_domainsOnly for web_search. Entries are normalised to bare host names: https://Www.Example.com/path becomes www.example.com, *.example.com becomes example.com. IP addresses are rejected.
is_enabledDefault true. A disabled source is ignored.
configMax 4 KB. Free-form, except for live_source and lookup_table (see below).
sort_order0..10000

Live sources​

A live_source is one public page whose current content the agent reads while answering — for example opening hours, prices or stock levels that change too often for the Knowledge Base.

{
"source_type": "live_source",
"config": {
"url": "https://www.example.com/opening-hours",
"label": "Opening hours",
"description": "Current opening hours of all stores",
"ttl_minutes": 15
}
}
config keyDefaultNotes
url—Required. Must start with http:// or https:// and point to a public address (private networks are rejected). Max 2048 characters.
label—Required. 1-80 characters, unique per agent (case-insensitive).
description""Max 500 characters. Tells the agent when to read this source.
matchexactexact or prefix.
ttl_minutes155-1440. How long a fetched page is reused.
fetcherautoauto, own or linkup_render.
scopeagentagent (available on every reply, see tools_config.live_mode) or skills (only while a skill whose sources.live_source_ids lists it is loaded).

allowed_domains and kb_folder_id must be absent or null. At most 10 live sources per agent. On PATCH, config is merged into the stored config and validated again.

Lookup-table sources​

A lookup_table source gives the agent one of your lookup tables. The agent then finds the matching rows in one step (for example the branch responsible for a postcode or a town) instead of searching the Knowledge Base several times.

{
"source_type": "lookup_table",
"config": {
"table_id": "LOOKUP_TABLE_ID",
"label": "Branch by postcode",
"description": "Use when the customer gives a postcode or town and asks which branch is responsible"
}
}
config keyDefaultNotes
table_id—Required. A lookup table of this workspace.
labelthe table nameMax 80 characters. Only stored when you send it, so a renamed table shows its new name.
description—Max 500 characters. Tells the agent when to use the table.

allowed_domains and kb_folder_id must be absent or null. At most 5 lookup tables per agent, each table once. On PATCH, config is merged into the stored config (send null for label or description to clear it) and checked again. Responses add a read-only table object for these sources: {id, name, description, row_count, key_columns, version}, or null when the table no longer exists. The table's content is not part of the agent's draft: replacing a table's file is live for every agent at once.

  • When the agent has no kb_folder, kb_all or faq source, it searches your whole AI-searchable Knowledge Base.
  • Conversation-history and ticket-summary folders are never searched.
  • search_knowledge searches up to 8 sources per call, FAQ first.

GET …/knowledge-sources returns {"items": [...], "pagination": {...}} with all sources (max 20, no paging parameters).

Knowledge source errors​

StatusDetail
422"kb_folder_id does not exist"
422"This folder cannot be used as an agent knowledge source" (conversation-history and ticket-summary folders)
422{"code": "use_faq_source", "message": "…"} — the managed FAQ folder cannot be added as a folder. Add a faq source instead.
422"At most 20 knowledge sources per agent"
422kb_folder_id or allowed_domains on the wrong source_type
422{"code": "live_source_limit", "message": "…"} — at most 10 live sources per agent
422{"code": "live_source_label_taken", "message": "…"} — another live source of the agent has this label
422{"code": "invalid_live_source_url", "error_code": "…", "message": "…"} — the URL cannot be used (for example a private address or a host that does not exist)
422{"code": "invalid_live_source", "message": "…"} — invalid config on PATCH
422{"code": "lookup_table_not_found", "message": "…"} — config.table_id is not a lookup table of this workspace
422{"code": "lookup_table_already_attached", "message": "…"} — the agent already uses this table
422{"code": "lookup_table_source_limit", "message": "…"} — at most 5 lookup tables per agent
422{"code": "invalid_lookup_table_source", "message": "…"} — invalid config on PATCH
404"Knowledge source not found"

Lookup tables​

A lookup table is a table you upload once (CSV or XLSX, or a table document from your Knowledge Base) and that agents search by exact value: postcode to branch, product number to price, town to district. Lookup tables belong to the workspace; attach one to an agent with a lookup_table source. They need Conversational Agents and the Knowledge Base on your plan (Professional, Scale, Enterprise); otherwise every endpoint returns 403 {"code": "feature_disabled"}.

MethodPathScopeSuccess
GET/lookup-tablesautomation:read200 {items, pagination}
POST/lookup-tables/inspectautomation:update200 sheets of an upload, nothing stored (multipart)
POST/lookup-tablesautomation:update201 table with preview (multipart upload)
POST/lookup-tables/from-documentautomation:update and knowledge_base:read201 table with preview
GET/lookup-tables/{table_id}automation:read200 table with preview
GET/lookup-tables/{table_id}/rows?page=1&page_size=20automation:read200 {items, pagination}
POST/lookup-tables/{table_id}/lookupautomation:read200 lookup result
PATCH/lookup-tables/{table_id}automation:update200 table with preview
PUT/lookup-tables/{table_id}/fileautomation:update200 table with preview (new version)
POST/lookup-tables/{table_id}/refreshautomation:update and knowledge_base:read200 table with preview (new version)
DELETE/lookup-tables/{table_id}automation:delete200 {success, id, message}

A table created from a Knowledge Base document holds Knowledge Base content: its rows and lookup also need knowledge_base:read (403 without it), and its detail returns preview_rows: [] without that scope.

Upload a table​

curl -X POST "https://api.sendseven.com/api/v1/automation/lookup-tables" \
-H "Authorization: Bearer $TOKEN" \
-F "[email protected]" \
-F "name=Branch by postcode" \
-F 'key_columns=["Postcode", "Town"]'
Form fieldNotes
fileRequired. .csv or .xlsx, at most 5 MB. CSV: UTF-8 or Windows-1252, separated by , ; tab or |. XLSX: the first sheet unless sheet is set; formulas are not calculated (the last saved value is used). The first non-empty row is the header.
nameRequired. 1-120 characters, unique in the workspace (case-insensitive).
descriptionMax 500 characters.
sheetXLSX sheet name.
key_columnsJSON list of 1-5 column names to search by. Leave it out and SendSeven picks suggested columns.
return_columnsJSON list of the columns the agent gets back. Empty or left out = all columns.

Limits: 20 lookup tables per workspace, 20,000 rows and 50 columns per table, 1,000 characters per cell.

Inspect a file (several sheets)​

To import several sheets of one workbook, inspect the file first, then create one table per sheet with POST /lookup-tables and sheet=<name>. POST /lookup-tables/inspect (multipart, only file; same 5 MB limit and file checks as the upload) stores nothing:

curl -X POST "https://api.sendseven.com/api/v1/automation/lookup-tables/inspect" \
-H "Authorization: Bearer $TOKEN" \
-F "[email protected]"
{
"filename": "pricing.xlsx",
"file_format": "xlsx",
"sheets": [
{
"name": "Branches", "index": 0, "row_count": 912, "column_count": 4,
"columns": ["Postcode", "Town", "District", "Branch"],
"preview_rows": [["86830", "Schwabmünchen", "Augsburg", "Augsburg"]],
"warnings": [], "error": null
},
{
"name": "Raw export", "index": 2, "row_count": 0, "column_count": 0, "columns": [],
"preview_rows": [], "warnings": [],
"error": {"code": "too_many_columns", "message": "…", "detail": {"max_columns": 50, "columns": 51}}
}
],
"skipped_empty_sheets": ["Notes"],
"tables_remaining": 17
}
  • sheets: one entry per sheet with content, in workbook order (index is the 0-based sheet position). A CSV file has exactly one entry, named after the file. preview_rows holds up to 5 rows in columns order.
  • error: null when the sheet can become a table. Otherwise the code that POST /lookup-tables with this sheet would return (for example too_many_rows, too_many_columns, no_header, empty_table); counts and preview then show what was read before the problem. One bad sheet never fails the whole request.
  • At most 20 sheets with content are read. Later sheets are listed with error.code too_many_sheets and no counts.
  • skipped_empty_sheets: sheets without a single filled cell.
  • tables_remaining: how many more tables the workspace can create (20 per workspace). Each sheet you import counts as one table.
  • Problems with the whole file (format, size, unreadable workbook) return the usual 422 errors below; 503 parser_busy when too many files are being processed.

POST /lookup-tables/from-document takes JSON {"kb_document_id", "name", "description"?, "key_columns"?, "return_columns"?}. The Knowledge Base document must be an uploaded CSV or XLSX file, or contain exactly one Markdown table. POST /lookup-tables/{table_id}/refresh reads that document again (only for tables created this way).

Table object​

{
"id": "LOOKUP_TABLE_ID",
"name": "Branch by postcode",
"description": null,
"origin": "upload",
"kb_document_id": null,
"original_filename": "branches.csv",
"file_format": "csv",
"sheet_name": null,
"columns": ["Postcode", "Town", "District", "Branch"],
"key_columns": ["Postcode", "Town"],
"return_columns": [],
"settings": {"prefix": true, "fuzzy": true},
"row_count": 912,
"size_bytes": 41230,
"version": 3,
"agents": [{"id": "AGENT_ID", "name": "Advice Agent"}],
"created_at": "2026-10-22T09:00:00Z",
"updated_at": "2026-10-22T09:30:00Z",
"preview_rows": [{"row_index": 0, "values": {"Postcode": "86830", "Town": "Schwabmünchen", "District": "Augsburg", "Branch": "Augsburg"}}],
"warnings": [],
"suggested_key_columns": ["Postcode", "Town"]
}
  • origin: upload or kb_document. file_format: csv, xlsx or md.
  • return_columns: empty = all columns. version goes up with every file replace or refresh.
  • agents: agents whose live configuration or saved draft uses the table.
  • preview_rows (first 20 rows), warnings and suggested_key_columns are only in single-table responses. warnings and suggested_key_columns are filled right after an upload, replace or refresh (for example a warning when a numeric column may have lost leading zeros), and empty on GET.
  • The list endpoint returns the same object without the three preview fields.

Change settings​

PATCH /lookup-tables/{table_id} with any of name, description (null clears it), key_columns (1-5 columns, not null), return_columns (null or [] = all columns) and settings:

settings keyDefaultNotes
prefixtrueA search also matches values that start with the query (at least 3 characters).
fuzzytrueWhen nothing else matches, close spellings (at least 5 characters) are offered, and the agent asks the customer to confirm.

Replace the file​

PUT /lookup-tables/{table_id}/file (multipart: file, optional sheet, key_columns, return_columns) loads a new version. The switch is atomic and applies to every agent right away; a conversation never sees a mix of old and new rows. The current search and return columns are kept when they all still exist in the new file; otherwise send new ones or you get 422 lookup_table_columns_missing with missing.

Try a lookup​

POST /lookup-tables/{table_id}/lookup with {"query": "Buxheim", "column": "Town"} (column optional) runs the same search the agent runs and costs nothing:

{
"status": "ok",
"match": "exact",
"total_matches": 2,
"truncated": false,
"rows": [
{"row_index": 14, "values": {"Postcode": "87740", "Town": "Buxheim", "Branch": "Memmingen"}, "matched_column": "Town"},
{"row_index": 15, "values": {"Postcode": "85114", "Town": "Buxheim", "Branch": "Ingolstadt"}, "matched_column": "Town"}
],
"latency_ms": 4.2,
"version": 3
}

status: ok, no_match, invalid_query or not_found. match shows which step found the rows: exact (the whole value), term (every word or number of the query, best matches first), prefix or fuzzy (confirm with the customer). Every matching row is returned, up to 20 (truncated is true when there are more), so an ambiguous value such as a town that exists twice shows all candidates.

Delete a table​

DELETE /lookup-tables/{table_id} deletes the table and all its rows. While an agent uses it (live or in a saved draft) the response is 409 with the agents to change first:

{"detail": {"code": "lookup_table_in_use", "message": "…", "agents": [{"id": "AGENT_ID", "name": "Advice Agent"}]}}

Lookup table errors​

Errors use {"detail": {"code", "message", …}}. File contents are never echoed back.

StatuscodeWhen
404lookup_table_not_foundNo such table in this workspace
404document_not_foundThe Knowledge Base document does not exist
409lookup_table_in_useDelete while agents use the table (agents)
422unsupported_formatNot a .csv or .xlsx file
422file_too_largeOver 5 MB (max_bytes)
422too_many_rows / too_many_columnsOver 20,000 rows or 50 columns
422no_header / empty_tableNo header row, or no data rows
422invalid_encoding / invalid_csv / invalid_xlsxThe file cannot be read
422sheet_not_foundsheet is not in the workbook (sheet, sheets)
422too_many_sheetsOnly in an inspect sheet error: the workbook has more than 20 sheets with content
422document_not_table / markdown_no_tableThe document is not a table
422lookup_table_name_takenAnother table has this name
422lookup_table_limit20 tables per workspace reached
422invalid_key_columns / invalid_return_columnsUnknown columns, more than 5 search columns, or not a JSON list
422lookup_table_columns_missingThe new file lacks configured columns (missing)
422lookup_table_not_kb_documentrefresh on an uploaded table
422invalid_field / invalid_configInvalid name, description or settings (field)
429rate_limit_exceededToo many files sent from this workspace (see below). Wait retry_after seconds (also in the Retry-After header)
503parser_busyToo many files are being processed right now (inspect, create, replace, from-document, refresh). Retry in a moment

File uploads are limited per workspace: POST /lookup-tables/inspect 10 per minute and 60 per hour; POST /lookup-tables and PUT /lookup-tables/{table_id}/file together 30 per minute and 200 per hour. Over a limit the response is 429 with {"detail": {"code": "rate_limit_exceeded", "error": "rate_limit_exceeded", "message", "retry_after"}} and a Retry-After header. When you import several sheets of one workbook, create the tables one after another; the 20-tables-per-workspace cap stays well inside the create limit.

Analytics​

GET /agents/{agent_id}/analytics?days=30 (automation:read). days is 7, 30 (default) or 90 calendar days in your workspace timezone, today included. Test-console replies are not counted. At most 20,000 replies are counted (truncated: true beyond).

{
"agent_id": "AGENT_ID", "days": 30, "from": "2026-09-06T22:00:00Z", "to": "2026-10-06T10:00:00Z",
"timezone": "Europe/Berlin", "truncated": false,
"totals": {"turns": 120, "conversations": 64, "answered": 101, "handoffs": 12, "fallbacks": 4, "errors": 3,
"kb_searches": 140, "kb_zero_hit_turns": 18, "kb_search_turns": 110, "web_searches": 25, "web_turns": 21,
"web_cache_hits": 6, "live_reads": 30, "live_turns": 28, "enforced_lookups": 9,
"grounding_checked": 80, "grounding_rewrites": 5, "grounding_handoffs": 1, "credits_billed": 260},
"rates": {"web_fallback_rate": 0.175, "kb_zero_hit_rate": 0.1636, "handoff_rate": 0.1, "grounding_rewrite_rate": 0.075},
"credits_per_conversation": 4.06,
"daily": [{"date": "2026-09-07", "turns": 3, "handoffs": 0, "web_searches": 1, "live_reads": 1,
"kb_zero_hit_turns": 0, "grounding_rewrites": 0, "credits_billed": 7}]
}
  • answered counts answered replies and completed Flow tasks.
  • web_fallback_rate = web_turns / turns; kb_zero_hit_rate = kb_zero_hit_turns / kb_search_turns; handoff_rate = handoffs / turns; grounding_rewrite_rate = (grounding_rewrites + grounding_handoffs) / grounding_checked. A rate is null when its denominator is 0; credits_per_conversation is null without conversations.
  • grounding_* count the answer check (replies whose facts were checked against the sources). Replies sent before the check existed are not in grounding_checked.
  • daily has one entry per day, days without replies included.

Knowledge-gap suggestions​

Questions the agent answered from a web search because your Knowledge Base had nothing are turned into draft FAQ entries for you to review. Drafts are never published automatically; review them in the FAQ list.

POST /agents/{agent_id}/kb-gap-suggestions (automation:update and knowledge_base:create, because it writes FAQ drafts; missing either one returns 403), body {"days": 30} (optional, 1-90, default 30):

{"created": 3, "skipped_existing": 2, "skipped_volatile": 1, "candidates": 9, "draft_ids": ["FAQ_ID_1", "FAQ_ID_2", "FAQ_ID_3"]}

skipped_existing = already covered by your FAQ; skipped_volatile = answered from live sources (changing data, never drafted). One run per agent at a time: a second run returns 409 {"code": "gap_run_in_progress"}. Starting runs is rate-limited per workspace (429, 3 per minute and 20 per hour). 503 {"code": "kb_gap_unavailable"} when the feature is temporarily unavailable.

GET /agents/{agent_id}/kb-gap-suggestions?page=1&page_size=20 (automation:read, page_size max 100) lists this agent's drafts that are not archived, newest first:

{
"items": [{"id": "FAQ_ID_1", "question": "…", "answer": "…", "status": "draft", "created_at": "2026-10-06T08:00:00",
"review_notes": "…", "source_conversation_count": 3}],
"pagination": {"total": 1, "page": 1, "page_size": 20}
}

Common errors​

StatusWhen
403{"code": "feature_disabled", "feature": "ai_agents"} (or ai_features; lookup tables also knowledge_base) — the plan does not include Conversational Agents. A missing scope returns 403 "Insufficient scopes".
404"Agent not found"
409agent_in_use on delete
422Validation errors: unknown fields, lengths, enums, JSON size limits, handoff tags, skill links, knowledge sources

See Billing, errors & limits for the full list.