Agent Readiness

Beta

Conversational Agents are in Beta and available on Professional, Scale and Enterprise.

GET /agents/{agent_id}/readiness answers one question: can this agent go live, and what should happen next? It combines everything you would otherwise read from several endpoints, and ends with a short, ordered next_steps list. It is built for setup assistants and LLM clients (for example the SendSeven MCP server), but any integration can use it.

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

Method	Path	Scope	Success
`GET`	`/agents/{agent_id}/readiness`	`automation:read`	`200` readiness

The call is read-only and never uses AI credits. Another workspace's agent returns 404.

Response

{
  "agent_id": "…",
  "bot_id": "…",
  "name": "Shop Support",
  "ready": true,
  "live": false,
  "plan": {
    "allowed": true, "ai_agents": true, "ai_features": true, "ai_enabled": true,
    "missing_features": [], "message": null, "upgrade_url": null
  },
  "publish": {
    "publish_state": "draft",
    "has_unpublished_changes": false,
    "revision": 3,
    "published_at": null,
    "draft_updated_at": null,
    "changes": [],
    "blockers": [],
    "can_publish": true
  },
  "knowledge": {
    "sources": [
      {"id": "…", "source_type": "kb_folder", "is_enabled": true, "kb_folder_id": "…", "kb_folder_name": "Help Center",
       "indexing_status": "processing", "documents": {"total": 12, "ready": 9, "processing": 3, "failed": 0}}
    ],
    "has_knowledge": true,
    "documents": {"total": 12, "ready": 9, "processing": 3, "failed": 0}
  },
  "skills": {
    "count": 3,
    "foundation_present": true,
    "foundation_skill_id": "…",
    "items": [
      {"skill_id": "…", "title": "Shop basics", "mode": "always_on", "is_foundation": true,
       "missing": false, "has_goal": false, "goal_valid": null}
    ]
  },
  "capabilities": {
    "search_knowledge": true, "web_search_mode": "kb_fallback", "live_mode": "off",
    "read_images": true, "read_documents": false, "read_voice_messages": false,
    "max_images_per_message": 3, "max_attachments_per_conversation": 10
  },
  "routing": {
    "is_active": true,
    "status": "draft",
    "connected": true,
    "activation_rules": [{"id": "…", "channel_types": ["whatsapp"], "is_active": true, "…": "…"}],
    "all_channels": false,
    "channels": [{"channel_id": "…", "channel_type": "whatsapp", "name": "Shop WhatsApp"}],
    "widgets": [],
    "flows": [{"id": "…", "name": "Order help", "status": "published", "node_ids": ["n4"]}],
    "flow_targeted": true
  },
  "next_steps": [
    {"code": "wait_for_indexing", "message": "Some documents are still being indexed. …", "endpoint": null},
    {"code": "test_agent", "message": "Try the configuration in the test console before publishing.", "endpoint": "POST /api/v1/automation/agents/…/test"},
    {"code": "publish", "message": "Publish the agent so contacts get this configuration. …", "endpoint": "POST /api/v1/automation/agents/…/publish"}
  ]
}

Field	Notes
`ready`	`true` when nothing blocks the agent from going live: the plan includes agents, AI is switched on for the workspace and there are no publish blockers. Steps like publishing or connecting a channel may still be needed; see `next_steps`.
`live`	`true` when the agent answers contacts right now (published, active and reachable).
`plan`	`ai_enabled` is the workspace's own AI switch (Settings > AI). When it is off the agent cannot answer, `ready` is `false` and the first step is `enable_ai`.
`publish`	`blockers` are exactly the checks of `POST /agents/{agent_id}/publish`, run on the draft when one exists, otherwise on the live configuration. Each blocker has `code`, `section`, `field` and a readable `message`.
`knowledge.sources[].indexing_status`	`ready`, `processing` (documents still being indexed), `partially_failed`, `failed`, `empty` (no documents yet), `folder_missing` (the folder was deleted), `unknown` (could not be checked) or `not_applicable` (web search, live sources, lookup tables). Folder sources include their subfolders.
`skills`	The foundation skill is the first `always_on` skill (or the only skill). `missing` = deleted or archived. `goal_valid` is `null` for skills without a goal.
`routing.status`	Same as the agents list: `draft` (never published), `paused`, `not_connected` or `live`.
`routing.activation_rules` / `channels`	The channel rules of the configuration (the draft when one exists) and the active channels they name. `all_channels` is `true` when a rule has no channel filter.
`routing.widgets` / `flows`	Active widgets that start this agent, and flows (not archived) whose Run AI Agent node targets it. `flow_targeted` is `true` when one of those flows is published.

Knowledge, skills, capabilities and channel rules describe the configuration that goes live on the next publish: the draft when one exists, otherwise the live configuration.

Next steps

next_steps is ordered: do the first one first. Each step has a stable code, a message you can show or pass to an LLM, and an endpoint when one API call does the step.

Code	Meaning
`enable_ai`	AI is switched off for the workspace.
`fix_<blocker code>`	A publish blocker, for example `fix_skill_missing` or `fix_name_missing`.
`add_skill` / `add_foundation_skill`	The agent has no skills, or no always-on skill.
`add_knowledge`	No knowledge source and no web search.
`fix_missing_folder`, `add_documents`, `wait_for_indexing`, `retry_failed_documents`	Knowledge Base sources that are not usable yet.
`test_agent`, `publish`	The agent was never published or has unpublished changes. Publishing with an API key or app needs the `automation:publish` scope.
`activate`	The agent is paused. Switching it on with an API key or app needs the `automation:publish` scope.
`connect_channel`	No channel rule, widget or published flow reaches the agent.
`monitor`	Nothing left to do: the agent is live.

Plan without Conversational Agents

When the plan does not include Conversational Agents, the call returns 403 like every other agent endpoint, with extra help in the body:

{
  "detail": {
    "code": "feature_disabled",
    "feature": "ai_agents",
    "missing_features": ["ai_agents", "ai_features"],
    "message": "Conversational Agents are not included in this workspace's plan. They are available on Professional, Scale and Enterprise. Upgrade the plan to use this agent.",
    "upgrade_url": "/settings/billing",
    "next_steps": [{"code": "upgrade_plan", "message": "…", "endpoint": null}]
  }
}

If the plan cannot be checked, the call also returns this 403 (it never assumes access).

Response​

Next steps​

Plan without Conversational Agents​

Response

Next steps

Plan without Conversational Agents