Skip to main content

Agent Quickstart

Beta

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

This guide builds a support agent for an online shop in six calls. You need an API token with the automation:read, automation:create and automation:update scopes.

export S7="https://api.sendseven.com/api/v1"
export TOKEN="s7_api_a1b2c3d4e5f6789012345678abcdef00"
Prefer a head start?

Create an agent with AI drafts the agent, its skills and knowledge sources from your company name, website and goals. Then continue from step 4.

1. Create a foundation skill​

Skills hold reusable instructions. Start with one always_on skill for the rules that apply in every conversation.

curl -X POST "$S7/automation/skills" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "shop-basics",
    "title": "Shop basics",
    "description": "Company facts, tone and rules that apply to every conversation.",
    "default_mode": "always_on",
    "body": "We are Example Shop, an online store for outdoor gear. Shipping inside the EU takes 2-4 working days. Never promise discounts. Keep answers short."
  }'

Then a skill the agent loads only when it is needed:

curl -X POST "$S7/automation/skills" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "order-return",
    "title": "Order returns",
    "description": "Use when the customer wants to return or exchange an item.",
    "default_mode": "model_selected",
    "body": "Ask for the order number and the reason. Returns are free within 30 days. Link to https://www.example.com/returns for the return label."
  }'

Both return 201 with the skill, including its id and current_version. description is required: it is how the agent decides when to load a model_selected skill. See Skills API.

2. Create the agent​

Create it inactive (is_active defaults to true), link the skills and add knowledge:

curl -X POST "$S7/automation/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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. Search the knowledge base before answering factual questions.",
    "model_tier": "standard",
    "language_settings": {"base_language": "en"},
    "skills": [
      {"skill_id": "SKILL_ID_SHOP_BASICS"},
      {"skill_id": "SKILL_ID_ORDER_RETURN"}
    ],
    "knowledge_sources": [
      {"source_type": "faq"},
      {"source_type": "kb_folder", "kb_folder_id": "KB_FOLDER_ID"}
    ],
    "handoff_config": {"keywords": ["human", "agent"], "max_turns": 30}
  }'

The response (201) is the full agent. Keep two ids:

  • id — the agent id, used by every /automation/agents/{agent_id} endpoint and by Flows.
  • bot_id — the agent's bot record, used to attach it to channels and to configure hand-off assignment.

3. Test a turn​

The test console runs a real turn against your configuration. Nothing is sent and nothing is billed, and it works on an inactive agent.

curl -X POST "$S7/automation/agents/AGENT_ID/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hi, I want to return my hiking boots", "channel_type": "whatsapp"}'
{
  "replies": [{"text": "Sure! Returns are free within 30 days. What is your order number?", "provenance": [], "buttons": null}],
  "outcome": "answered",
  "model": "…",
  "router": {"skills": ["order-return"], "language": "en", "needs_kb": false, "needs_web": false, "latency_ms": 410, "model": "…"},
  "skills_loaded": [
    {"slug": "shop-basics", "version": 1, "source": "always"},
    {"slug": "order-return", "version": 1, "source": "router"}
  ],
  "tool_calls": [],
  "link_fixes": [],
  "credits": {"messages": 1, "credits_per_message": 1, "tools": 0, "waived": 0, "by_charge": {"bot_message": 1}, "billed": false, "would_bill": 1},
  "state": {},
  "turn_id": "…"
}

To continue the conversation, send the previous turns in history and the returned state back. See Test console & turn log.

4. Activate​

curl -X PATCH "$S7/automation/agents/AGENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active": true}'

5a. Attach to a channel​

Channel rules decide where the agent answers. They live on the agent's bot record:

curl -X POST "$S7/automation/bots/BOT_ID/rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel_ids": ["CHANNEL_ID"], "priority": 100, "is_active": true}'

The rule takes the same fields as for any bot (channel_ids, widget_ids, schedule, requires_no_agents_online, recipient_email_addresses, priority 0-100). See Deploy bots to channels. Rules do not fire while the agent is inactive.

5b. Or start it from a Flow​

Use the Run AI Assistant node with "target": {"type": "agent", "id": "AGENT_ID"}. The Flow can give the agent a skill, a task and an output schema, and continues on the done branch with the results in flow variables. See Agents in Flows.

6. Route hand-offs​

When the agent hands over, the conversation can be assigned automatically. Set the strategy on the agent's bot record:

curl -X PATCH "$S7/automation/bots/BOT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"escalation_routing_strategy": "least_busy_all", "escalation_fallback_minutes": 15}'

See Hand-off & assignment.

Next steps​