astra-insight-mcp 0.2.0

package/README.md

@@ -0,0 +1,69 @@
+# @wati/astra-mcp
+
+AI agent management for the WATI/Astra platform via [Model Context Protocol](https://modelcontextprotocol.io).
+
+Create, test, optimize, and diagnose WhatsApp AI agents — directly from your IDE.
+
+## Quick Start
+
+```bash
+npx -y @wati/astra-mcp@latest
+```
+
+Or install globally:
+
+```bash
+npm install -g @wati/astra-mcp
+```
+
+## IDE Configuration
+
+### Cursor
+
+Settings → Tools and MCP → New MCP server:
+
+```json
+{
+  "mcpServers": {
+    "astra": {
+      "command": "npx",
+      "args": ["-y", "@wati/astra-mcp@latest"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "astra": {
+      "command": "npx",
+      "args": ["-y", "@wati/astra-mcp@latest"]
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ASTRA_API_KEY` | Your Astra platform API key |
+| `ASTRA_GATEWAY_URL` | Custom gateway URL (optional) |
+
+## Supported Platforms
+
+| OS | Architecture |
+|----|-------------|
+| macOS | Apple Silicon (arm64) |
+| macOS | Intel (x64) |
+| Linux | arm64 |
+| Linux | x64 |
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * Thin wrapper that locates the bundled platform binary and runs it.
+ * Defaults to "stdio" mode when no subcommand is given.
+ */
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const PLATFORM_MAP = { darwin: "darwin", linux: "linux" };
+const ARCH_MAP = { arm64: "arm64", x64: "x64" };
+
+const plat = PLATFORM_MAP[process.platform];
+const arch = ARCH_MAP[process.arch];
+
+if (!plat || !arch) {
+  process.stderr.write(
+    `[astra-mcp] Unsupported platform: ${process.platform}/${process.arch}\n` +
+    "  Supported: darwin-arm64, darwin-x64, linux-arm64, linux-x64\n"
+  );
+  process.exit(126);
+}
+
+const BIN_PATH = path.join(__dirname, "..", "platform", `${plat}-${arch}`, "astra");
+
+if (!fs.existsSync(BIN_PATH)) {
+  process.stderr.write(
+    `[astra-mcp] Binary not found at ${BIN_PATH}\n` +
+    "  Try reinstalling: npm install -g @wati/astra-mcp\n"
+  );
+  process.exit(127);
+}
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  args.push("stdio");
+}
+
+try {
+  execFileSync(BIN_PATH, args, { stdio: "inherit" });
+} catch (err) {
+  process.exit(err.status || 1);
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "astra-insight-mcp",
+  "version": "0.2.0",
+  "description": "Astra Insight MCP — AI agent management for the WATI/Astra platform",
+  "bin": {
+    "astra-mcp": "./bin/cli.js"
+  },
+  "keywords": ["mcp", "astra", "wati", "ai-agent", "whatsapp"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "platform/",
+    "skills/",
+    "README.md"
+  ]
+}

package/skills/agent-creation.md

@@ -0,0 +1,55 @@
+# Agent Creation Workflow
+
+## Critical Workflow Order
+
+**IMPORTANT**: `knowledge_base_id` can ONLY be set at agent creation time. The `update_agent` endpoint does NOT support changing it — the backend silently ignores the field. Therefore, always create the KB BEFORE creating the agent.
+
+The correct sequence for creating a fully functional agent:
+
+1. **`fetch_brandkit(identifier=<domain>)`** — Pre-fetch brand data (no agent_id needed yet).
+2. **`create_knowledge_base(name=<name>)`** — Create an empty KB, get the `dataset_id` UUID.
+3. **`import_knowledge_from_website(dataset_id=<uuid>, url=<site>)`** — Start async content crawl into the KB.
+4. **`create_agent(name=..., knowledge_base_id=<uuid>, ...)`** — Create agent WITH the KB attached. This is the ONLY time you can set `knowledge_base_id`.
+5. **`fetch_brandkit(identifier=<domain>, agent_id=<new_id>)`** — Re-fetch with agent_id to attach brandkit.
+6. **`update_brandkit(...)`** — Customize persona, appearance_config, conversation starters, welcome message.
+7. **`update_agent_instruction(agent_id, instructions=...)`** — This creates the **draft runtime config** (required before publishing).
+8. **`publish_agent(agent_id)`** — Publishes the draft config to make it live.
+9. **Test and verify** — Test only after publishing.
+
+## Critical Gotchas
+
+### Draft Config is Required Before Publishing
+`publish_agent` will fail with "No draft configuration found" unless you call `update_agent_instruction` first. Simply calling `create_agent` with instructions does NOT create a draft config — it sets the agent-level instructions but the runtime config system is separate.
+
+### system_rules via update_agent Don't Propagate to Runtime Config
+Calling `update_agent(system_rules=...)` sets rules on the agent object, but the published runtime config may show empty `system_rules`. **Workaround**: Embed guardrails directly in the instructions passed to `update_agent_instruction`.
+
+### Brandkit Attachment — Use fetch_brandkit, Not create_brandkit
+`fetch_brandkit(identifier=<domain>, agent_id=<id>)` is the reliable one-step method. `create_brandkit` requires precise struct formats (`minimized_button_label` as object, `agent_id` in body) and is error-prone.
+
+### Annotations as Immediate Safety Net
+Create annotations for critical guardrail responses BEFORE the knowledge base is ready. Annotations work without a KB and guarantee exact answers for:
+- Fee-blocking responses (high priority)
+- Competitor comparison deflections
+- Unavailable product/service responses
+- Campus/location redirect links
+- Accreditation/ranking verified data
+
+### appearance_config Structure
+The appearance_config has two parallel sections: `widget` (for web widget) and `ai_bar` (for AI bar). Both need the same structure:
+```json
+{
+  "widget": {
+    "name": "Agent Name",
+    "welcome_message": {"message": "...", "popup_mode": true},
+    "conversation_starter": {"messages": ["Q1", "Q2", "Q3"], "popup_mode": true},
+    "brand_logo": {"url": "..."},
+    "color_theme": {"primary_color": "#hex"},
+    "display_form_immediately": false
+  },
+  "ai_bar": { ... same structure ... }
+}
+```
+
+## Typical Cost for Full Agent Creation
+A complete agent creation workflow (brandkit + create + KB + annotations + publish + test attempts) costs approximately $2.50-3.50 with Claude Sonnet, spanning ~25 iterations.

package/skills/astra-create-agent.md

@@ -0,0 +1,70 @@
+# Create a New Astra Agent
+
+You are guiding the user through creating a fully functional Astra AI agent. Follow this workflow step by step, confirming with the user at each stage.
+
+## Step 1 — Gather Requirements
+
+Ask the user for:
+- **Agent name** (required)
+- **Purpose** — what does the agent do? (e.g., customer support, sales, FAQ)
+- **Channel** — whatsapp, web_widget, or voice? (default: whatsapp)
+- **Website/domain** — for auto-fetching brand kit and knowledge base content
+- **Any specific instructions or rules** the agent should follow
+
+If the user already provided some of these, skip those questions.
+
+## Step 2 — Set Up Knowledge Base (if website provided)
+
+If the user provided a website/domain:
+1. Call `create_knowledge_base(name="<agent_name> KB")`
+2. Call `import_knowledge_from_website(dataset_id=<kb_id>, url=<website>)`
+3. Tell the user: "Knowledge base is importing in the background. This takes 1-3 minutes."
+
+Save the `dataset_id` — you MUST pass it when creating the agent (it cannot be added later).
+
+## Step 3 — Create the Agent
+
+Call `create_agent` with:
+- `name` — from step 1
+- `type` — "conversational" (general purpose) or "faq" (Q&A focused)
+- `channel_type` — from step 1
+- `communication_mode` — "text" (default), "voice", or "both"
+- `knowledge_base_id` — from step 2 (if created)
+- `instructions` — write a good initial instruction based on the user's purpose description. Include:
+  - Role definition ("You are a customer support agent for ...")
+  - Tone and style guidelines
+  - Key behaviors (be helpful, stay on topic, escalate when unsure)
+  - Any specific rules the user mentioned
+
+**CRITICAL**: `knowledge_base_id` can ONLY be set at creation time. It cannot be changed later.
+
+## Step 4 — Set Up Brand Kit (if website provided)
+
+1. Call `fetch_brandkit(identifier=<domain>, agent_id=<agent_id>)` to auto-detect branding
+2. Show the user what was detected (colors, logo, name)
+3. Ask if they want to customize anything
+
+## Step 5 — Create Draft & Publish
+
+1. Call `update_agent_instruction(agent_id=<id>, instructions=<instructions>)` — this creates the required draft config
+2. Call `publish_agent(agent_id=<id>)` — makes the agent live
+
+**IMPORTANT**: You MUST call `update_agent_instruction` before `publish_agent`, otherwise publishing will fail with "No draft configuration found".
+
+## Step 6 — Test
+
+Call `send_test_message(agent_id=<id>, message="Hi, what can you help me with?")` to verify the agent responds correctly.
+
+Show the response to the user and ask if they want to adjust anything.
+
+## Summary
+
+After completion, show a summary:
+```
+✅ Agent Created
+   Name:     <name>
+   ID:       <agent_id>
+   Channel:  <channel>
+   KB:       <attached/none>
+   Status:   Published & Live
+```

package/skills/astra-diagnose.md

@@ -0,0 +1,56 @@
+# Diagnose Agent Issues
+
+You are helping the user diagnose why an Astra agent isn't working correctly. Follow a systematic approach to identify the root cause.
+
+## Step 1 — Identify Agent & Symptom
+
+Ask:
+- "Which agent has the issue?" (name or ID)
+- "What's going wrong?" — e.g., wrong answers, not responding, ignoring KB, hallucinating
+
+Call `get_agent(agent_id)` to get current config.
+
+## Step 2 — Quick Health Check
+
+Run these checks in parallel:
+
+1. **Agent status**: Is it published? Call `get_runtime_config(agent_id)` — if no draft/published config exists, the agent can't function.
+2. **Knowledge base**: Does it have a KB? Call `list_documents(dataset_id)` if KB exists — are documents there?
+3. **Recent conversations**: Call `list_conversations(agent_id, limit=5)` to see if the agent is actually receiving messages.
+4. **Test message**: Call `send_test_message(agent_id, message=<reproduce the problem>)` to see the actual response.
+
+## Step 3 — Diagnose by Symptom
+
+### "Agent gives wrong answers"
+1. Call `retrieve_knowledge(agent_id, query=<the question>)` — is the correct info in the KB?
+2. Check instruction for conflicting or missing guidance
+3. Check annotations — is there an annotation overriding the correct answer?
+
+### "Agent doesn't use knowledge base"
+1. Verify KB is attached: check `knowledge_base_id` in agent config
+2. Verify KB has content: `list_documents(dataset_id)`
+3. Test retrieval: `retrieve_knowledge(agent_id, query=<question>)` — if empty results, the content isn't indexed properly
+
+### "Agent hallucinates / makes things up"
+1. Check instruction — does it say "only answer from knowledge base" or similar grounding rules?
+2. Add annotations for critical facts that must be exact
+3. Consider adding to instruction: "If you don't know the answer, say so. Never make up information."
+
+### "Agent not responding at all"
+1. Check if agent is published
+2. Check if agent is enabled: `get_agent` → `enabled` field
+3. Check channel configuration — is the trigger type correct?
+
+## Step 4 — Fix
+
+Based on diagnosis, suggest specific fixes:
+- Instruction changes → use `/astra-optimize-instruction`
+- KB content gaps → use `/astra-setup-knowledge`
+- Missing annotations → offer to create them
+- Config issues → fix directly via `update_agent` or `publish_agent`
+
+## Step 5 — Verify Fix
+
+After applying changes:
+1. Call `send_test_message(agent_id, message=<original problem message>)` to verify
+2. Show before/after comparison

package/skills/astra-optimize-instruction.md

@@ -0,0 +1,62 @@
+# Optimize Agent Instruction
+
+You are guiding the user through an instruction optimization cycle: analyze current performance → identify weaknesses → generate improved instruction → test → compare.
+
+## Step 1 — Identify the Agent
+
+Ask: "Which agent's instruction do you want to optimize?"
+
+Call `list_agents` if needed, then `get_agent(agent_id=<id>)` to fetch current instruction and configuration.
+
+Show the user:
+- Agent name and ID
+- Current instruction (first 200 chars + "...")
+- Whether it has a knowledge base attached
+
+## Step 2 — Assess Current Performance
+
+Check if there are existing test results:
+1. Call `get_agent_test_overview(agent_id=<id>)`
+2. If there are recent runs, show the latest pass rate
+
+If no test data exists, suggest: "No test data yet. Want me to run a test first? Use `/astra-test-agent`"
+
+## Step 3 — Analyze Failures
+
+If a recent test run exists:
+1. Call `analyze_failures(run_id=<latest_run_id>)` to get failure analysis
+2. Show the improvement suggestions grouped by priority (high → medium → low)
+3. Ask the user if they want to address all suggestions or focus on specific ones
+
+## Step 4 — Generate Improved Instruction
+
+Call `generate_instruction` with:
+- `instruction` — the current agent instruction
+- `analysis_json` — from step 3 (if available)
+- `improvement_suggestions` — the selected suggestions
+- `agent_description` — brief description of what the agent does
+
+Show the proposed new instruction to the user. Highlight what changed and why.
+
+Ask: "Want to apply this instruction, edit it first, or try a different approach?"
+
+## Step 5 — Apply & Test
+
+Once approved:
+1. Call `update_agent_instruction(agent_id, instructions=<new_instruction>)` to update draft
+2. Call `publish_agent(agent_id)` to make it live
+3. Call `create_test_run(generator_id=<suite_id>, user_id="test-user")` to re-run the same test suite
+4. Compare old vs new pass rates
+
+Show comparison:
+```
+📊 Instruction Optimization Results
+   Before:  72% pass rate (18/25)
+   After:   88% pass rate (22/25)
+   Delta:   +16% improvement
+```
+
+## Step 6 — Iterate or Done
+
+If improvement is satisfactory, congratulate and summarize.
+If not, ask: "Want to run another optimization cycle focusing on the remaining failures?"

package/skills/astra-quick-start.md

@@ -0,0 +1,31 @@
+# Astra Quick Start
+
+Welcome to Astra Insight MCP! Here's what you can do. Type any of these commands to get started:
+
+## Common Tasks
+
+| Command | What it does |
+|---------|-------------|
+| `/astra-create-agent` | Create a new AI agent from scratch (guided workflow) |
+| `/astra-test-agent` | Run tests on an agent and see pass/fail results |
+| `/astra-optimize-instruction` | Improve an agent's instruction based on test failures |
+| `/astra-setup-knowledge` | Create and populate a knowledge base |
+| `/astra-diagnose` | Debug why an agent isn't working correctly |
+
+## Quick Actions (just ask in natural language)
+
+- "List all my agents" → calls `list_agents`
+- "Send a test message to agent X" → calls `send_test_message`
+- "Show conversations for agent X" → calls `list_conversations`
+- "What's the analytics for agent X?" → calls `get_analytics`
+
+## Reference Guides
+
+| Command | Content |
+|---------|---------|
+| `/agent-creation` | Detailed agent creation reference (API gotchas, field requirements) |
+| `/knowledge-management` | KB import workflows, annotation patterns |
+| `/instruction-optimization` | How the test → analyze → improve cycle works |
+| `/voice-agent` | Voice agent configuration reference |
+| `/integration-auth-flow` | How to set up Composio integrations (Slack, HubSpot, etc.) |
+| `/debugging-tips` | Common API errors and workarounds |

package/skills/astra-setup-knowledge.md

@@ -0,0 +1,58 @@
+# Set Up Knowledge Base
+
+You are guiding the user through creating and populating a knowledge base for an Astra agent.
+
+## Step 1 — Identify Target
+
+Ask:
+- "Which agent needs a knowledge base?" (or "Are you creating a KB for a new agent?")
+- "What content source do you have?" — Website URL, document files, or manual FAQ entries?
+
+If the agent already exists, call `get_agent(agent_id)` to check if it already has a KB attached.
+
+**WARNING**: If the agent already exists WITHOUT a KB, you CANNOT attach one later via API. The user would need to create a new agent with the KB. Inform them of this limitation upfront.
+
+## Step 2 — Create Knowledge Base
+
+Call `create_knowledge_base(name="<descriptive name>")`.
+
+Save the `dataset_id` — this is needed for all subsequent operations.
+
+## Step 3 — Import Content
+
+Based on the user's content source:
+
+### Website
+1. Call `import_knowledge_from_website(dataset_id=<id>, url=<website_url>)`
+2. This crawls the site asynchronously. Tell the user it takes 1-5 minutes depending on site size.
+3. Poll `get_import_status(import_id=<id>)` to check progress.
+
+### URL (single page)
+1. Call `import_knowledge_from_url(dataset_id=<id>, url=<page_url>)`
+2. Faster than website crawl — usually completes in under a minute.
+
+### Manual FAQ / Annotations
+For critical Q&A pairs that need exact answers:
+1. Call `create_annotation(agent_id=<id>, question=<q>, answer=<a>)` for each pair
+2. Annotations take priority over KB content — use for pricing, policies, compliance answers
+
+## Step 4 — Verify
+
+1. Call `list_documents(dataset_id=<id>)` to see what was imported
+2. Call `retrieve_knowledge(agent_id=<id>, query="<test question>")` to test retrieval
+3. Show results to the user
+
+## Step 5 — Connect to Agent
+
+If creating a new agent, remind: "Use `/astra-create-agent` and I'll include this KB automatically."
+
+If KB is already attached, the agent will start using it after publishing.
+
+Show summary:
+```
+✅ Knowledge Base Ready
+   Name:      <name>
+   ID:        <dataset_id>
+   Documents: <count>
+   Status:    Ready for use
+```

package/skills/astra-test-agent.md

@@ -0,0 +1,47 @@
+# Test an Astra Agent
+
+You are guiding the user through a full test cycle for an Astra agent. This includes generating test cases, running them, and analyzing results.
+
+## Step 1 — Identify the Agent
+
+Ask: "Which agent do you want to test?"
+
+If the user gives a name, call `list_agents` and find the matching agent. Show the agent's name, ID, and current status.
+
+If the user gives an ID, call `get_agent(agent_id=<id>)` directly.
+
+## Step 2 — Choose Test Strategy
+
+Ask the user:
+> How would you like to test?
+> 1. **Quick test** — Send a few messages manually
+> 2. **Full test pipeline** — Auto-generate test cases, run them all, and get a score
+> 3. **Re-run existing tests** — Run tests from a previous test suite
+
+### Option 1: Quick Test
+Ask what messages to send, then call `send_test_message(agent_id, message)` for each. Show responses inline.
+
+### Option 2: Full Pipeline
+1. Call `start_test_pipeline(agent_id=<id>, user_id="test-user")`
+2. Poll `get_pipeline_job(job_id=<id>)` every 10 seconds until status is "completed"
+3. Show results: pass rate, failures, and improvement suggestions
+
+### Option 3: Re-run Existing
+1. Call `get_agent_latest_test_suite(agent_id=<id>)` to find the latest suite
+2. Call `create_test_run(generator_id=<suite_id>, user_id="test-user")` to re-run
+3. Poll `get_test_run(run_id=<id>)` until complete
+4. Show results
+
+## Step 3 — Review Results
+
+For any test run, show:
+- **Pass rate**: X/Y tests passed (Z%)
+- **Failures**: List each failed test with the expected vs actual response
+- **Suggestions**: If analysis is available, show improvement recommendations
+
+## Step 4 — Next Steps
+
+Based on results, suggest:
+- If pass rate > 90%: "Agent is performing well! Consider publishing if not already live."
+- If pass rate 70-90%: "Some improvements needed. Want me to optimize the instruction? Use `/astra-optimize-instruction`"
+- If pass rate < 70%: "Significant issues found. Let's review the failures and rewrite the instruction."

package/skills/debugging-tips.md

@@ -0,0 +1,62 @@
+# Debugging & Troubleshooting
+
+## Common API Errors
+
+### 400 "Invalid request body"
+- `minimized_button_label` must be `{"enabled": true, "label": "..."}`, not a string
+- `create_brandkit` requires `agent_id` in the JSON body (auto-handled by client)
+- **Chat endpoints** (`/chat`, `/chat-test`, `/chat-preview`) return this when:
+  - Agent has no published runtime config → publish first via `update_agent_instruction` + `publish_agent`
+  - Backend service rejects the request format → this is a known backend issue, not a client bug
+
+### 400 "No draft configuration found"
+- `publish_agent` fails because no draft exists
+- **Fix**: Call `update_agent_instruction(agent_id, instructions=...)` first — this creates the draft config
+- `create_agent` with instructions does NOT create a draft runtime config
+
+### 422 Validation Error
+- `get_import_status` requires `url` query parameter matching the original import URL
+- `create_knowledge_document` requires a real dataset UUID, NOT `new`
+
+### 500 Internal Server Error
+- **`import_knowledge_from_url`** — "Failed to import document: Expecting value: line 1 column 1 (char 0)":
+  - **Root cause**: RAG service's `upload_webpage_to_knowledge_base()` in `dify_console_op.py` calls Dify's `/datasets/{id}/documents` API but does NOT check `response.status_code` before calling `response.json()`. When Dify returns a non-200 response (HTML error), JSON parsing fails.
+  - **Underlying Dify failure**: Usually because the tenant has no `jinareader` API credentials configured. Dify needs valid provider credentials (jinareader/firecrawl/watercrawl) in its `api_key_auth` system.
+- **`get_import_status`** — "Error fetching crawl status: HTTP 500":
+  - **Root cause**: RAG's `check_crawl_status()` (line 778) hardcodes `provider=jinareader` in the Dify status URL. Dify's `WebsiteService` then calls `_get_credentials_and_config(tenant_id, "jinareader")` which raises "Invalid provider" if no credentials exist for that tenant+provider combo.
+  - The actual Dify error is `{"code": "crawl_failed", "message": "Invalid provider", "status": 500}`.
+- Google Sheets, Docs, and authenticated URLs always fail on import.
+
+### 409 Conflict
+- `create_brandkit` fails if a brandkit already exists — use `update_brandkit` instead
+- Or use `fetch_brandkit(identifier=..., agent_id=...)` which handles create-or-update automatically
+
+## Known Backend Issues (Not Client Bugs)
+
+1. **`send_test_message` (chat-preview) returns 400** — was caused by using `message` field instead of `user_query`. The API service's `ExecuteRequest` requires `user_query` (binding:"required"). Fixed in client.
+2. **`import_knowledge_from_url` returns 500** — RAG service doesn't check Dify response status before JSON parse; Dify fails because tenant lacks jinareader API credentials
+3. **`get_import_status` returns 500** — RAG hardcodes `provider=jinareader` in Dify status URL; Dify rejects if tenant has no jinareader credentials configured
+4. **`system_rules` via `update_agent` may not propagate** to published runtime config — embed guardrails in instructions instead
+5. **`process_crawl_results_realtime` batch uploads fail** with "Expecting value" — same root cause as #2, Dify document upload returns non-JSON when credentials are missing
+
+## Debugging Strategy
+
+1. **Enable debug mode** (`--debug`) to see curl commands and API responses
+2. **Check HTTP status codes**: 2xx = success, 4xx = client error (fix payload), 5xx = server/backend error
+3. **For 400 errors**: Compare payload against OpenAPI spec in `astra-gateway/docs/openapi.yaml`
+4. **For 500 errors**: Usually backend issues — try alternative approaches rather than retrying
+5. **For chat errors**: Don't waste iterations retrying — verify agent is published (`get_runtime_config(status=active)`) first
+
+## Efficiency Tips
+
+- **Don't retry failing endpoints** — If `import_knowledge_from_url` fails once with 500, it will fail again. Switch to `import_knowledge_from_website` or manual documents.
+- **Don't poll import status aggressively** — Status endpoint is unreliable. Start the crawl, do other work, check back later.
+- **Use annotations early** — Don't wait for KB to be ready. Create annotations for guardrail responses immediately while import runs in background.
+- **Batch annotation creation** — Create multiple annotations in sequence for different guardrail categories (fees, competitors, availability, redirects, facts).
+
+## Performance Tips
+
+- `list_agents` returns lightweight summaries (no instructions) — use `get_agent` for full details
+- Truncate long content before sending to LLM (auto-handled at 8000 chars)
+- Prompt caching is enabled automatically for Claude models — static content (system prompt + tools) cached for 5 minutes, ~90% savings on repeat calls
+- Full agent creation workflow costs ~$2.50-3.50 with Claude Sonnet over ~25 iterations

package/skills/instruction-optimization.md

@@ -0,0 +1,49 @@
+# Instruction Optimization Workflow
+
+## Analysis Phase
+
+1. **Get current config** — `get_agent` + `get_runtime_config(status=active)` to see what's live.
+2. **Review conversations** — `get_analytics` first for overview, then `list_conversations` to find problematic ones. Read actual messages with `get_conversation_messages`.
+3. **Check knowledge gaps** — `retrieve_knowledge` with common user queries to see what the agent retrieves. If results are poor, the KB needs enrichment.
+
+## Improvement Phase
+
+1. **Instructions should be structured** — Use markdown headers: Role & Identity, Core Flow, Guardrails, Communication Style.
+2. **Embed guardrails directly in instructions** — `system_rules` set via `update_agent` may NOT propagate to the published runtime config. Always include critical guardrails (NEVER/ALWAYS rules) directly in the instruction text passed to `update_agent_instruction`.
+3. **Use annotations for FAQ overrides** — `create_annotation` with exact Q&A pairs takes priority over KB retrieval. Use for critical questions that must have exact answers. Annotations work even without a KB attached.
+4. **Keep instructions under 4000 tokens** — Very long instructions degrade LLM performance. Be concise and use bullet points.
+
+## Publishing Flow
+
+The correct publishing flow is:
+1. `update_agent_instruction(agent_id, instructions=...)` — creates/updates the **draft runtime config**
+2. `publish_agent(agent_id)` — publishes the draft to make it live
+3. Verify: `get_runtime_config(agent_id, status=active)` — confirm instructions are correct
+
+**Critical**: `publish_agent` requires a draft config. If you only used `create_agent` or `update_agent`, there is no draft config — you MUST call `update_agent_instruction` first.
+
+## Testing Phase
+
+1. **Publish before testing** — `send_test_message` (chat-preview) requires a published runtime config. An unpublished agent returns 400 errors.
+2. **chat-preview endpoint may return 400** — This is a known backend issue. If test messages fail, verify the agent is published and has an active runtime config (`get_runtime_config(status=active)`).
+3. **For systematic testing** — Use the testing pipeline: `create_test_suite` → `add_test_case` (multiple) → `create_test_run` → `get_test_run` → `create_run_analysis`.
+4. **Use `generate_instruction`** — After analyzing test failures with `analyze_failures`, use `generate_instruction` to get AI-suggested improvements.
+
+## Annotation Patterns for Guardrails
+
+Annotations are the most reliable way to enforce guardrail responses. Create them for:
+
+| Guardrail | Example Questions | Fixed Response |
+|-----------|------------------|----------------|
+| Fee blocking | "What's the fee?", "How much does it cost?" | "For fee information, please contact..." |
+| Competitor deflection | "Is X better than Y?", "X vs Y" | "I can help with information about [brand]..." |
+| Unavailable items | "Do you offer [thing]?" | "Sorry, [thing] is not available." |
+| Location redirects | "Tell me about [other branch]" | "For [branch], please visit: [URL]" |
+| Verified facts | "What's [brand]'s ranking?" | Exact verified answer with source links |
+
+## Common Instruction Patterns
+
+- **Lead capture agent**: Step-by-step flow (greet → collect name → phone → email → interest → answer → qualify). Collect one field at a time. If user asks a question first, answer it, then return to collection.
+- **Support agent**: Prioritize KB retrieval, with clear escalation rules and human handoff triggers.
+- **Sales agent**: Include objection handling, CTA patterns, and qualification criteria.
+- **Multi-location agent**: Define primary location, redirect rules for other locations with specific URLs.

package/skills/integration-auth-flow.md

@@ -0,0 +1,98 @@
+# Integration Auth Flow
+
+## Overview
+
+Connect a third-party platform (e.g. HubSpot, Slack, Salesforce, Google Sheets) to an Astra agent via OAuth. This is a 3-step sequential flow — each step depends on the previous one.
+
+## Flow
+
+```
+create_integration_auth(platform)
+        │
+        ▼
+  {connection_id, redirect_url}  ← user must visit redirect_url to authorize
+        │
+        ▼
+wait_integration_auth(connection_id)
+        │
+        ▼
+  {success, account_name}       ← if success=false → abort, auth failed
+        │
+        ▼
+create_connection(platform, connection_id, connection_name=account_name)
+        │
+        ▼
+  Connection mapping created     ← done, connection_id is ready for use
+```
+
+## Step-by-Step
+
+### Step 1: Initiate OAuth — `create_integration_auth`
+
+```
+create_integration_auth(platform="hubspot")
+→ { connection_id: "conn_xxx", redirect_url: "https://..." }
+```
+
+- Present the `redirect_url` to the user and ask them to complete authorization.
+- For **WATI** platform: provide `bearer_token` and `api_endpoint` instead of OAuth (no redirect needed).
+- Hold on to `connection_id` — it's needed in all subsequent steps.
+
+### Step 2: Wait for Auth — `wait_integration_auth`
+
+```
+wait_integration_auth(connection_id="conn_xxx", timeout=120, platform="hubspot")
+→ { success: true, account_name: "My HubSpot Account" }
+```
+
+- Blocks until the user completes OAuth or the timeout expires.
+- Default timeout is 120 seconds.
+- **If `success=false`**: Auth failed or timed out. Stop here — do not proceed to Step 3.
+- **If `success=true`**: Save `account_name` for Step 3.
+
+**Important field mapping**: The response field is `account_name`. In Step 3, pass this value as `connection_name`.
+
+### Step 3: Create Connection Mapping — `create_connection`
+
+```
+create_connection(platform="hubspot", connection_id="conn_xxx", connection_name="My HubSpot Account")
+→ { id: 1, platform: "hubspot", connection_id: "conn_xxx", ... }
+```
+
+- **`connection_name`** = the `account_name` from Step 2's response. This is a required field.
+- `tenant_id` is resolved automatically from the API key.
+- Calls `POST /connections` (gateway forwards to `POST /mapping/v2/connections`).
+- After this, the `connection_id` can be used with `create_integration` to set up actions.
+
+## After Auth: Creating Integration Actions
+
+Once the connection is established, create and register actions:
+
+1. **`list_integration_templates`** — Find the `at_id` for the desired action (e.g. `HUBSPOT_CREATE_CONTACT`).
+2. **`create_integration`** — Create an action with `at_id`, `action_name`, `status="active"`, and the `connection_id` from above.
+3. **`register_agent_integrations`** — Register the action to a specific agent so it can use it at runtime.
+
+## Error Handling
+
+| Step | Failure | Action |
+|------|---------|--------|
+| 1 | API error | Check platform name is valid; retry |
+| 2 | `success=false` | User didn't complete auth in time; restart from Step 1 |
+| 2 | Timeout | Increase timeout or ask user to retry auth faster |
+| 3 | 422 | Missing required fields; check connection_id and account_name |
+| 3 | 500 | Server-side issue; retry once, then escalate |
+
+## WATI Special Case
+
+WATI uses API key auth instead of OAuth. The flow is shorter:
+
+```
+create_integration_auth(platform="wati", bearer_token="tok_xxx", api_endpoint="https://api.wati.io")
+→ { connection_id: "conn_xxx" }
+```
+
+Then skip Step 2 (no OAuth needed) and go directly to Step 3:
+
+```
+create_connection(platform="wati", connection_id="conn_xxx", connection_name="WATI Account")
+```

package/skills/knowledge-management.md

@@ -0,0 +1,55 @@
+# Knowledge Base Management
+
+## Correct Workflow
+
+**CRITICAL**: `knowledge_base_id` can ONLY be set at agent creation time. `update_agent` silently ignores this field. Always create the KB BEFORE the agent.
+
+1. **`create_knowledge_base(name=...)`** — Creates an empty KB, returns a `dataset_id` UUID.
+2. **Import content** using the real `dataset_id`:
+   - `import_knowledge_from_website(dataset_id=<uuid>, url=...)` — BFS crawl (recommended)
+   - `import_knowledge_from_url(dataset_id=<uuid>, title=..., urls=[...])` — specific pages
+3. **`create_agent(name=..., knowledge_base_id=<uuid>)`** — Create the agent WITH the KB. This is the only time KB can be linked.
+
+**CRITICAL**: Do NOT use `dataset_id=new` — it's not a valid UUID and will cause 500 errors.
+
+**NOTE**: The backend expects the create request wrapped as `{"kb_data": {...}}`. The gateway client handles this automatically.
+
+## Import Strategies
+
+### Website Crawl — RECOMMENDED (Most Reliable)
+```
+create_knowledge_base(name="Company KB") → dataset_id
+import_knowledge_from_website(dataset_id=<uuid>, url="https://docs.example.com", max_pages=50)
+```
+- BFS crawl from the root URL
+- Returns immediately with a `job_id`; crawling happens async in background
+- Best for structured sites with internal links
+
+### URL Import — MAY FAIL (Root Cause Known)
+```
+import_knowledge_from_url(dataset_id=<uuid>, title="FAQ Pages", urls=["https://example.com/faq"])
+```
+- May return 500 with "Failed to import document: Expecting value: line 1 column 1 (char 0)"
+- **Root cause**: The RAG service calls Dify's `/datasets/{id}/documents` API but does NOT check `response.status_code` before calling `.json()`. When Dify returns a non-JSON error, parsing fails.
+- **Underlying Dify failure**: Usually because the tenant lacks `jinareader` API credentials.
+- Does NOT work with: Google Sheets, Google Docs, pages behind auth, SPAs
+
+### There Is NO Text Document Creation Endpoint
+The `POST /knowledge-bases/{id}/documents` endpoint is Dify's internal document upload API requiring `{tenant_id, urls, job_id, size}`. It is NOT for creating text documents from raw content. If you need to add curated text content, use annotations (`create_annotation`) instead.
+
+## Import Status Checking
+
+`get_import_status` may return 500 for BFS crawl jobs:
+- **Root cause**: RAG's `check_crawl_status()` hardcodes `provider=jinareader` in the Dify status URL. Dify rejects it if the tenant has no jinareader credentials.
+- **Workaround**: Don't poll status. Start the crawl, do other work, verify later by listing documents.
+
+## Fallback: Use Annotations
+
+When imports fail or for critical Q&A pairs:
+- `create_annotation(agent_id, title, questions=[...], answer="...")` — works immediately, no KB needed
+- Annotations take priority over KB retrieval for matching questions
+- Best for: fee guardrails, competitor deflections, exact verified facts, location redirects
+
+## Google Sheets / Docs Data
+
+Google Sheets and Docs URLs **cannot be imported** via any endpoint (auth required, dynamic content). Ask the user to export as text, then use annotations to add the content.

package/skills/voice-agent.md

@@ -0,0 +1,250 @@
+# Voice Agent Management
+
+## Creating a Voice Agent
+
+Voice agents MUST be linked to a text agent. There is only one creation method:
+
+1. Check existence first: **`get_voice_agent_by_text_agent(text_agent_id)`** — avoid duplicates.
+2. **`quick_create_voice_agent(text_agent_id, template_id)`** — Creates a voice agent pre-configured from a template, linked to the text agent. Automatically resolves `tenant_id` from the text agent.
+3. **`update_voice_agent(voice_agent_id, instruction=...)`** — Customize the instruction to match your use case.
+4. **`publish_voice_agent(voice_agent_id)`** — Push draft config live.
+
+There is NO other creation method. Do NOT use `create_agent` or any text-agent tool to create voice agents.
+
+## Configuring and Optimizing Instructions
+
+Voice agent instructions follow the same principles as text agent instructions. Use `update_voice_agent(voice_agent_id, instruction=...)` to set them.
+
+**Structure instructions with markdown headers**: Role & Identity, Core Flow, Guardrails, Communication Style — just like text agents.
+
+**Key differences from text agents**:
+- Voice agents need concise responses — users are listening, not reading.
+- Include explicit turn-taking guidance (e.g., "Ask one question at a time, wait for the answer").
+- Add pronunciation hints for brand names or technical terms if the TTS mispronounces them.
+- Specify escalation triggers (e.g., "If the user says 'speak to a human', transfer immediately").
+
+**Publishing flow** (same as text agents):
+1. `update_voice_agent(voice_agent_id, instruction=...)` — creates/updates draft config
+2. `publish_voice_agent(voice_agent_id)` — makes it live
+3. Verify by calling `get_voice_agent(voice_agent_id)` — confirm `published_agent_config` has the new instruction
+
+## Customizing the Voice (Voice Clone)
+
+To use a custom voice instead of the default:
+1. **`upload_user_voice(audio_url=<url>)`** — Uploads the user's audio. Tell user: "Audio uploaded successfully." Do NOT mention storage details.
+2. **`submit_voice_clone(tenant_id, voice_name, gcs_url)`** — Starts the cloning process. Tell user: "Voice cloning started, please wait."
+3. **`get_minimax_voice(id)`** — Poll until status=`completed`. The tool auto-confirms when ready. Do NOT tell user about internal statuses.
+4. When completed, share the `demo_audio` URL so the user can listen.
+5. **CRITICAL — MUST NOT SKIP**: Take `agent_config_voice_id` from the `get_minimax_voice` response and call:
+   **`update_voice_agent(voice_agent_id, agent_config={"voice_id": "<agent_config_voice_id>"})`**
+   Without this step the cloned voice will NOT take effect on the agent.
+6. **`publish_voice_agent(voice_agent_id)`** — Push the new voice live.
+
+### User-facing communication
+
+| Internal step | What to tell user |
+|---------------|-------------------|
+| upload_user_voice | "Audio uploaded successfully" |
+| submit_voice_clone | "Voice cloning started, this may take a moment" |
+| get_minimax_voice (polling) | "Still processing..." or "Almost ready..." |
+| status=completed | "Your voice clone is ready! Here's a preview: {demo_audio}" |
+| update_voice_agent + publish | "Your custom voice has been applied to the agent" |
+
+**NEVER expose to user**: GCS URLs, internal status names (pending/processing/tentative), voice_id, clone_model, minimax IDs.
+
+### Internal notes (for tool logic, not user-facing)
+
+- Clone lifecycle: `pending` → `processing` → `tentative` → `completed` (or `failed`)
+- `tentative` means clone finished but awaiting confirmation — `get_minimax_voice` auto-confirms it to `completed`
+- `failed` — retry with `submit_voice_clone(id=<existing_id>, ...)`
+- Always use `upload_user_voice` first — external URLs (e.g. from Wati) require auth and cannot be passed to `submit_voice_clone` directly
+
+To browse existing voices: `search_voice_library(keyword=...)` or `search_collected_voices(tenant_id=...)`.
+
+**NOTE**: If `submit_voice_clone` returns 503, Minimax clone is not configured for this deployment.
+
+## ASR (Speech-to-Text) for Voice Messages
+
+When a user sends a voice message (audio) instead of text, the webhook automatically:
+1. Downloads the audio file (with Wati token authentication)
+2. Uploads to ASR for transcription
+3. Passes the transcribed text + original audio URL to the agent
+
+The agent receives voice messages in this format:
+```
+[Voice message | audio_url: <url> | format: audio.opus]
+<transcribed text>
+```
+
+If the user's intent involves using their audio for voice cloning, use the `audio_url` with `upload_user_voice`. Otherwise, just process the transcribed text normally.
+
+## Starting Calls
+
+### Inbound Calls (WhatsApp)
+- **`new_voice_call(call_id, sdp)`** — Accept an incoming WhatsApp call. Requires tenant validation and usage gating. Call is processed asynchronously.
+- Uses the **published** agent config.
+
+### Web Calls (Browser)
+- **`web_new_voice_call(agent_id, call_id, sdp)`** — Start a browser-based call via WebRTC.
+- Use **`get_webrtc_config()`** first to get ICE servers (STUN/TURN) for frontend setup.
+- Uses the **published** agent config.
+
+### Test Calls (Development)
+- **`test_new_voice_call(agent_id, call_id, sdp)`** — Same as web call but skips tenant validation.
+- Uses the **draft** agent config — best for iterating on config before publishing.
+
+### Outbound Calls (WhatsApp)
+- **`initiate_outbound_call(waid)`** — Call a WhatsApp user by their WAID.
+- Uses the **draft** agent config (test mode). Requires a valid WhatsApp user ID.
+- Optional: set `voice_language`, `accent`, `agent_id`, `channel_phone_number`.
+
+### Ending Calls
+- **`terminate_voice_call(call_id)`** — End a production call.
+- **`test_terminate_voice_call(call_id)`** — End a test call (skips Wati API).
+
+## Critical Gotchas
+
+### Only Use quick_create_voice_agent
+`quick_create_voice_agent(text_agent_id, template_id)` is the only creation method. It handles tenant setup internally. Always call `get_voice_agent_by_text_agent(text_agent_id)` before creation to avoid duplicates.
+
+### voice_id Must Reference a Completed Clone
+`agent_config.voice_id` must reference a voice with `status=completed`. The `get_minimax_voice` tool auto-confirms tentative clones, so just poll until completed. Setting an incomplete or invalid voice_id will cause failures.
+
+### Never Expose Internal Details to Users
+Do NOT show users: voice_id, GCS URLs, clone_model, minimax config, internal status names. Only share: upload success, cloning progress, preview audio link, and final confirmation.
+
+### Draft Config Required Before Publishing
+`publish_voice_agent` will fail if `agent_config` is empty. Always call `update_voice_agent` to set the draft config before publishing.
+
+### Test Calls Use Draft Config, Production Calls Use Published Config
+`test_new_voice_call` and `initiate_outbound_call` use draft config — changes are reflected immediately. `new_voice_call` and `web_new_voice_call` use published config — must call `publish_voice_agent` first.
+
+### Text Agent Linkage
+Use `get_voice_agent_by_text_agent(text_agent_id)` to find the voice counterpart of a text agent. This is the primary lookup when working across text and voice systems.
+
+## agent_config Fields Reference
+
+```json
+{
+  "tone": "professional, helpful, and concise",
+  "speed": 1,
+  "voice": "VoiceDisplayName",
+  "persona": "Professional Voice Assistant",
+  "language": "en",
+  "services": ["lead_qualification", "meeting_booking", "q_and_a"],
+  "voice_id": "minimax-voice-uuid",
+  "expertise": ["customer_service", "sales", "scheduling"],
+  "default_accent": "us",
+  "model_provider": "minimax",
+  "max_call_duration": 600,
+  "prompt_config": {
+    "greeting_template": "Hello! How can I help you today?",
+    "realtime_template": "## Role & Objective\n...",
+    "system_instructions": "You are a helpful assistant...",
+    "auto_language_switching": true
+  },
+  "outbound_prompt_config": {
+    "greeting_template": "Hello! This is {{.CompanyName}}...",
+    "realtime_template": "## Role & Objective\n...",
+    "system_instructions": "..."
+  },
+  "minimax_config": {
+    "model": "speech-02-turbo",
+    "speed": 1,
+    "format": "pcm",
+    "volume": 1,
+    "bitrate": 128000,
+    "channels": 1,
+    "voice_id": "astra-voice-xxx",
+    "sample_rate": 32000
+  },
+  "rag_config": {
+    "enabled": true,
+    "token": "...",
+    "base_url": "...",
+    "timeout": 30,
+    "max_retries": 3
+  },
+  "silence_config": {},
+  "integrated_actions": [],
+  "outbound_integrated_actions": []
+}
+```
+
+### Top-level fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `voice` | string | Display name of the selected voice |
+| `voice_id` | string | Minimax voice record's `id` (NOT its `voice_id` field). Must reference a clone with `status=completed` |
+| `speed` | number | Speech speed multiplier (default 1) |
+| `tone` | string | Tone descriptor (e.g. "professional, helpful") |
+| `persona` | string | Agent persona label |
+| `language` | string | Primary language code. Default: `en`. See supported values below. Do NOT use "multilingual" — for multi-language support, set `auto_language_switching: true` in `prompt_config` instead |
+| `default_accent` | string | Accent variant (e.g. `us`, `uk`, `in`) |
+| `model_provider` | string | LLM backend: `openai`, `gemini`, or `minimax` |
+| `services` | []string | Enabled service types |
+| `expertise` | []string | Domain expertise tags |
+| `max_call_duration` | int | Hard limit in seconds; call auto-terminates after this |
+
+### prompt_config / outbound_prompt_config
+
+Separate configurations for inbound vs outbound calls. Both share the same structure:
+
+| Field | Description |
+|-------|-------------|
+| `realtime_template` | System prompt / instruction for voice calls (equivalent to text agent's instruction) |
+| `greeting_template` | Opening message when the call starts. Supports `{{.CompanyName}}` etc. |
+| `system_instructions` | Additional system-level instructions appended to the prompt |
+| `auto_language_switching` | If true, agent auto-detects and switches to the caller's language. Set this when user wants "multilingual" support |
+
+### Language Configuration
+
+**`language` field** must be one of the supported language codes (default: `en`):
+
+`en`, `zh`, `yue`, `es`, `fr`, `de`, `ja`, `ko`, `pt`, `it`, `ru`, `ar`, `hi`, `th`, `vi`, `id`, `ms`, `nl`, `pl`, `tr`, `sv`, `no`, `da`, `fi`, `el`, `he`, `uk`, `cs`, `ro`, `hu`, `bg`, `fa`, `sk`, `hr`, `tl`, `sl`, `ca`, `nn`, `ta`, `af`
+
+**Rules:**
+- Default to `en` unless the user specifies a different primary language
+- **Never** set `language` to `"multilingual"` — it is not a valid value
+- When the user says "multilingual" or "multi-language", set `language` to their primary language (or `en` by default) AND set `prompt_config.auto_language_switching: true`
+- Example: user says "I want multilingual support, mainly Chinese" → `language: "zh"`, `auto_language_switching: true`
+- Example: user says "support multiple languages" → `language: "en"`, `auto_language_switching: true`
+
+### minimax_config
+
+Low-level TTS engine parameters (only relevant when `model_provider=minimax`):
+
+| Field | Description |
+|-------|-------------|
+| `model` | TTS model (e.g. `speech-02-turbo`) |
+| `voice_id` | Internal Minimax voice ID (auto-derived from top-level `voice_id`) |
+| `speed`, `volume` | Playback tuning |
+| `format`, `bitrate`, `channels`, `sample_rate` | Audio encoding parameters |
+
+### rag_config
+
+Controls knowledge-base retrieval for the voice agent:
+
+| Field | Description |
+|-------|-------------|
+| `enabled` | Whether RAG is active |
+| `token`, `base_url` | Credentials and endpoint for the knowledge service |
+| `timeout`, `max_retries` | Request tuning |
+
+### Other fields
+
+- `silence_config` — Silence detection thresholds (affects when the agent speaks during pauses)
+- `integrated_actions` / `outbound_integrated_actions` — Action definitions triggered during inbound/outbound calls
+
+### Updating agent_config
+
+`update_voice_agent` performs a safe GET → merge → PUT for all `agent_config` changes. Examples:
+
+- **Bind a cloned voice**: `update_voice_agent(voice_agent_id, agent_config={voice_id: "uuid", voice: "MyVoice"})`
+- **Change language**: `update_voice_agent(voice_agent_id, agent_config={language: "zh", default_accent: "cn"})`
+- **Update instruction**: `update_voice_agent(voice_agent_id, instruction="new prompt text")`
+- **Update greeting**: `update_voice_agent(voice_agent_id, greeting="Hello! ...")`
+- **Combo**: `update_voice_agent(voice_agent_id, instruction="...", agent_config={language: "en", tone: "friendly"})`
+
+The `instruction` and `greeting` shortcut params map to `prompt_config.realtime_template` and `prompt_config.greeting_template` respectively. The `agent_config` param merges at the top level. All three can be combined in a single call.

package/skills/wati-api.md

@@ -0,0 +1,240 @@
+# WATI API Reference
+
+WATI API for WhatsApp business messaging. Base URL depends on the tenant's `api_endpoint` (e.g. `https://live-mt-server.wati.io`).
+
+Full docs: https://docs.wati.io/reference/introduction
+
+## Authentication
+
+All requests require `Authorization: Bearer <token>` header. The bearer token is obtained when creating a WATI connection via `create_integration_auth(platform="wati", bearer_token=..., api_endpoint=...)`.
+
+## Contacts
+
+### List Contacts
+
+```
+GET /api/ext/v3/contacts?page_number=1&page_size=20
+```
+
+Response:
+```json
+{
+  "contact_list": [
+    {
+      "id": "507f1f77bcf86cd799439011",
+      "wa_id": "1234567890",
+      "name": "John Doe",
+      "phone": "+1234567890",
+      "contact_status": "active",
+      "source": "manual",
+      "opted_in": true,
+      "allow_broadcast": true,
+      "teams": ["Team A"],
+      "custom_params": [{"name": "city", "value": "New York"}],
+      "channel_type": "whatsapp"
+    }
+  ],
+  "page_number": 1,
+  "page_size": 20
+}
+```
+
+### Add Contact
+
+```
+POST /api/ext/v3/contacts
+Content-Type: application/json
+
+{
+  "whatsapp_number": "1234567890",
+  "name": "John Doe",
+  "custom_params": [
+    {"name": "age", "value": "30"},
+    {"name": "city", "value": "New York"}
+  ]
+}
+```
+
+Required fields: `whatsapp_number`, `name`.
+
+### Update Contacts (Batch)
+
+```
+PUT /api/ext/v3/contacts
+Content-Type: application/json
+
+{
+  "contacts": [
+    {
+      "target": "507f1f77bcf86cd799439011",
+      "customParams": [{"name": "city", "value": "London"}]
+    }
+  ]
+}
+```
+
+`target` can be: ContactId, PhoneNumber, or `Channel:PhoneNumber` format.
+
+### Get Contact Detail
+
+```
+GET /api/ext/v3/contacts/{contact_id}
+```
+
+## Conversations
+
+### Get Messages
+
+```
+GET /api/ext/v3/conversations/{target}/messages?page_number=1&page_size=20
+```
+
+`target` can be:
+- **ConversationId** — unique conversation ID
+- **PhoneNumber** — e.g. `14155552671`
+- **Channel:PhoneNumber** — e.g. `MyChannel:14155552671`
+
+Response:
+```json
+{
+  "message_list": [
+    {
+      "id": "507f1f77bcf86cd799439011",
+      "text": "Hello!",
+      "type": "text",
+      "timestamp": "2026-01-06T02:50:13Z",
+      "owner": true,
+      "status": "delivered",
+      "operator_name": "John Doe",
+      "conversation_id": "685bd235e6119686e693a093",
+      "event_type": "message"
+    }
+  ],
+  "page_number": 1,
+  "page_size": 20
+}
+```
+
+### Send Text Message
+
+```
+POST /api/ext/v3/conversations/{target}/messages/text
+Content-Type: application/json
+
+{
+  "text": "Hello, how can I help you?"
+}
+```
+
+### Send File Message (via URL)
+
+```
+POST /api/ext/v3/conversations/{target}/messages/file/url
+Content-Type: application/json
+
+{
+  "url": "https://example.com/document.pdf",
+  "caption": "Here is your document"
+}
+```
+
+### Send Interactive Message
+
+```
+POST /api/ext/v3/conversations/{target}/messages/interactive
+```
+
+### Assign Operator
+
+```
+PUT /api/ext/v3/conversations/{target}/assign
+Content-Type: application/json
+
+{
+  "assigned_id": "<operator_id>"
+}
+```
+
+### Update Conversation Status
+
+```
+PUT /api/ext/v3/conversations/{target}/status
+Content-Type: application/json
+
+{
+  "status": "resolved"
+}
+```
+
+## Template Messages (V1)
+
+### Send Template Message
+
+```
+POST /api/v1/sendTemplateMessage?whatsappNumber=85264318721
+Content-Type: application/json
+
+{
+  "template_name": "new_chat_v1",
+  "broadcast_name": "my_broadcast",
+  "channel_number": "85264318721",
+  "parameters": [
+    {"name": "name", "value": "Matthew"}
+  ]
+}
+```
+
+Required fields: `template_name`, `broadcast_name`, `channel_number`, `parameters`.
+
+### Get Templates
+
+```
+GET /api/v1/getMessageTemplates
+```
+
+## Campaigns (V3)
+
+```
+GET /api/ext/v3/campaigns?page_number=1&page_size=20
+GET /api/ext/v3/campaigns/{campaign_id}
+GET /api/ext/v3/campaigns/{campaign_id}/recipients
+GET /api/ext/v3/campaigns/{campaign_id}/overview
+```
+
+## Chatbots (V3, Pro Plan)
+
+```
+GET /api/ext/v3/chatbots
+POST /api/ext/v3/chatbots/start
+```
+
+## Error Handling
+
+| Code | Meaning |
+|------|---------|
+| 400 | Invalid request — check required fields |
+| 401 | Unauthorized — invalid or expired bearer token |
+| 403 | Forbidden — insufficient permissions |
+| 429 | Rate limit exceeded |
+| 500 | Server error — retry |
+
+Error response format:
+```json
+{"code": 400, "message": "Description", "timestamp": "2026-01-01T00:00:00Z"}
+```
+
+## Astra ↔ WATI Mapping
+
+| Astra Tool | WATI Equivalent |
+|------------|-----------------|
+| `get_contacts_and_leads` | `GET /api/ext/v3/contacts` |
+| `get_contact` | `GET /api/ext/v3/contacts/{id}` |
+| `list_conversations` | N/A (Astra gateway conversations) |
+| `get_conversation_messages` | `GET /api/ext/v3/conversations/{target}/messages` |
+
+WATI-specific operations not available through Astra gateway:
+- `POST /api/ext/v3/contacts` — add contact directly
+- `PUT /api/ext/v3/contacts` — batch update contacts
+- `POST /api/ext/v3/conversations/{target}/messages/text` — send message
+- `POST /api/v1/sendTemplateMessage` — send template message
+- `GET /api/ext/v3/campaigns` — campaign management