Skip to content
Splashify Pro
Docs
Log in (opens in a new tab)Start free trialStart free (opens in a new tab)

AI Agents

The ai-agents and ai-agent commands mirror the /ai-agents page and its per-agent detail view. From the terminal you can run the full agent lifecycle (create / update / delete), flip the default agent, and manage each agent's knowledge base.

Backed by /api/v1/app/ai-agents/*. Every call uses your stored oc_live_ token.

Quick start

bash
# 1. Create a support agent
splashify ai-agent create \
  --name "Support bot" \
  --agent-type support \
  --channel whatsapp \
  --industry retail \
  --role "Customer support agent for our online store" \
  --goal "Resolve order, shipping and return queries on the first reply" \
  --instructions "Always confirm order ID before quoting status. Escalate to a human if frustrated."

# 2. Make it the default agent
splashify ai-agent set-default <agent_id>

# 3. Upload knowledge (PDF / DOCX / MD / TXT — max 15MB)
splashify ai-agent knowledge <agent_id> upload ./returns-policy.pdf

# 4. Tune it
splashify ai-agent update <agent_id> \
  --temperature 0.3 \
  --processing-msg true \
  --processing-msg-text "Looking that up for you…"

Command tree

text
ai-agents                           list all agents
ai-agent <agent_id>                 show one
ai-agent create                     POST a new agent
ai-agent update <agent_id>          sparse PUT (only flags you pass)
ai-agent delete <agent_id>          DELETE
ai-agent set-default <agent_id>     promote to default
ai-agent unset-default <agent_id>   demote
ai-agent knowledge <agent_id>
  ├── list                          (default — list knowledge files)
  ├── upload <file>                 multipart upload
  └── delete <file_id>              remove

Channel types

Agents can run on one of two channels:

Creating an agent

bash
splashify ai-agent create \
  --name "Sales qualifier" \
  --agent-type sales \
  --channel whatsapp \
  --industry "B2B SaaS" \
  --use-case lead_qualification \
  --role "Qualify inbound leads via 3 short questions" \
  --goal "Capture company name, team size, and use-case in under 6 messages" \
  --instructions "Be concise. If unclear, ask one clarifying question, then summarise and hand off."

Updating an agent

update is a sparse PUT — only fields you pass are sent, the rest are preserved. This is intentionally different from canned/waba/attribute updates (which use the load-modify-write pattern); the agents endpoint accepts pointers for every editable field.

bash
# Change the goal
splashify ai-agent update <id> --goal "New goal here"

# Tune the LLM
splashify ai-agent update <id> \
  --ai-provider anthropic \
  --ai-model claude-sonnet-4-6 \
  --temperature 0.3

# Enable inbound-image OCR and a processing-message bubble
splashify ai-agent update <id> \
  --image-recognition true \
  --processing-msg true \
  --processing-msg-text "On it — give me a moment…"

# Pause an agent
splashify ai-agent update <id> --status paused

Default agent

Only one agent at a time can be the default — the one that takes incoming conversations when no other routing rule fires.

bash
splashify ai-agent set-default <agent_id>
splashify ai-agent unset-default <agent_id>     # clears it; nothing replaces it automatically

Knowledge base

Each agent has its own knowledge base — files the agent can cite when answering. Accepted formats: .pdf, .docx, .md, .txt. Max file size: 15MB (enforced server-side).

bash
# List files
splashify ai-agent knowledge <agent_id>
splashify ai-agent knowledge <agent_id> list

# Upload
splashify ai-agent knowledge <agent_id> upload ./returns-policy.pdf
splashify ai-agent knowledge <agent_id> upload ./faqs.md

# Delete
splashify ai-agent knowledge <agent_id> delete <file_id>

Common workflows

Bulk-import a folder of knowledge files

bash
AGENT=<agent_id>
for f in ./kb/*.{pdf,docx,md,txt}; do
  [ -f "$f" ] || continue
  splashify ai-agent knowledge "$AGENT" upload "$f"
done

Snapshot an agent's full config to JSON (for backup or cloning)

bash
splashify ai-agent <agent_id> > agent-backup.json
splashify ai-agent <agent_id> knowledge > agent-backup.kb.json

Pause every agent

bash
splashify ai-agents | \
  jq -r '.agents[] | .agent_id' | \
  xargs -I{} splashify ai-agent update {} --status paused

Find which agent is current default

bash
splashify ai-agents | \
  jq '.agents[] | select(.is_default) | {agent_id, name, channel_type, status}'

Wipe and re-upload the knowledge base

bash
AGENT=<agent_id>
splashify ai-agent knowledge "$AGENT" | jq -r '.files[].file_id' | \
  xargs -I{} splashify ai-agent knowledge "$AGENT" delete {}

for f in ./kb-v2/*; do
  splashify ai-agent knowledge "$AGENT" upload "$f"
done

Troubleshooting

HTTP 403 ig_bot_blocked on Instagram channel — plan doesn't include instagram_automation_enabled or no IG account is connected. Run splashify subscription and splashify instagram to confirm.

Knowledge upload returns 400 "unsupported format" — only .pdf, .docx, .md, .txt are accepted. The CLI validates this client-side before the round-trip, but if you bypass with splashify api, the backend returns the same 400.

temperature flag clamped — the backend clamps to [0.0, 1.0]. The CLI sends whatever you pass; values outside the range are silently clamped server-side, no error.

Agent stopped replying after set-default — there can only be one default at a time. Setting a new default automatically unsets the previous one. The previous agent isn't deleted, just demoted — splashify ai-agent update <previous_id> --status active keeps it available for explicit routing rules.

See also