---
name: Darkfunnels
description: Use when connecting AI assistants (Claude, ChatGPT, Codex) to OptiMind WhatsApp sales agents to read/write playbooks, manage catalogs, review conversations, handle orders, and optimize sales workflows. Reach for this skill when agents need to audit sales performance, modify sales scripts, manage product catalogs, or automate customer interactions through WhatsApp.
metadata:
    mintlify-proj: darkfunnels
    version: "1.0"
---

# Dark Funnels (OptiMind MCP Bridge) Skill

## Product summary

Dark Funnels is an MCP (Model Context Protocol) bridge that connects your AI assistant (Claude, ChatGPT, Codex, or any MCP client) to OptiMind, a WhatsApp-based AI sales agent platform. The bridge lets assistants read and write sales playbooks (funnels), manage product catalogs, review customer conversations, handle orders, and optimize sales workflows—all under your account's authorization with no hidden configuration.

**Key files and URLs:**
- Connection URL: `https://mcp.darkfunnels.ai/mcp?features=all` (base URL: `https://mcp.darkfunnels.ai/mcp`)
- Configuration: All settings live in the connection URL parameters (`?features=`, `?read_only=`, `?pii=`, `?agent=`)
- Primary docs: https://docs.darkfunnels.ai
- Tool reference (Spanish): https://docs.darkfunnels.ai/referencia/tools

## When to use

Reach for this skill when:
- **Auditing sales performance**: "Review yesterday's conversations and tell me where I'm losing sales"
- **Editing sales scripts**: Modifying playbook chapters, fixing funnel logic, or optimizing agent responses
- **Managing product catalogs**: Uploading products, updating prices, managing variants and stock
- **Automating customer workflows**: Creating reminders, sending operator messages, simulating conversations
- **Diagnosing funnel problems**: Identifying where customers drop off and proposing fixes
- **Connecting assistants**: Setting up Claude, ChatGPT, or Codex to operate an OptiMind workspace
- **Handling orders and metrics**: Reading sales data, customer tags, and performance KPIs

## Quick reference

### Connection URL parameters

| Parameter | Purpose | Example |
|-----------|---------|---------|
| `?features=all` | Activate all tool groups (recommended for quickstarts) | `https://mcp.darkfunnels.ai/mcp?features=all` |
| `?features=manual,catalog,conversations` | Activate specific groups (replaces default, doesn't extend) | Use when you need only reads |
| `?read_only=true` | Disable all writes (overrides any other option) | For audit-only access |
| `?pii=full` | Show full customer phone numbers (default: masked) | `51•••••4321` → `51999114321` |
| `?agent=<uuid>` | Lock connection to one sales agent | Avoids "which agent?" prompts |

**Critical rule**: An explicit feature list **replaces** the default set, not extends it. `?features=orders` alone loses manual, catalog, and conversations. Always name all groups: `?features=manual,catalog,conversations,orders`.

### Default tool groups (no `?features=` parameter)

| Group | What it includes |
|-------|------------------|
| `core` | `whoami`, `list_agents`, `get_agent_settings`, `get_credit_balance` |
| `manual` | Read playbook chapters, version history |
| `catalog` | List and read products |
| `conversations` | List chats, read conversation threads, list clients (CRM) |

### Destructive operations (require explicit opt-in)

| Group | Tools | Cost |
|-------|-------|------|
| `manual_write` | Save chapters, restore versions, apply full funnel | Versioned (10 retained) |
| `catalog_write` | Create/update/delete products | Permanent |
| `agents_write` | Create new sales agent (funnel) | Consumes subscription quota |
| `manual_ai` | Generate/optimize playbook with AI | Consumes credits |
| `testing` | Simulate messages (sends real WhatsApp) | Consumes credits |
| `operations` | Send operator messages, set chat mode, create reminders | Real actions |
| `library` | Upload files, link to agents | Max 2.5 MB per file |

### Essential commands (Claude/ChatGPT)

```
# Audit sales performance
"Review my conversations from yesterday and tell me where I'm losing sales. 
Read 8 chats: the ones that died, the stalled ones, and 2 that converted. 
Give me max 3 findings with exact quotes and how many cases each affects."

# Read playbook
"Read my agent's playbook and summarize what each chapter does and how 
the funnel advances between them."

# Update product catalog
"Read the product 'Shampoo Anticaída' with get_product first, then update 
its price to 69.90 soles. Resubmit the entire row with that single change."

# Create reminder
"Program a follow-up reminder for this conversation: 'Check in about 
delivery status' at 2024-01-15T14:00:00-05:00. Cancel if the customer 
replies before then."
```

## Decision guidance

### When to use `?features=all` vs. specific groups

| Situation | Use | Reason |
|-----------|-----|--------|
| First-time setup, testing | `?features=all` | Simplest; features added later show up automatically |
| Audit-only (no writes) | `?features=manual,catalog,conversations&read_only=true` | Prevents accidental changes |
| Read-only catalog review | `?features=catalog` | Minimal surface; catalog_write not included |
| Full workflow (read + write) | `?features=manual,catalog,conversations,manual_write,catalog_write,operations` | Explicit control; avoids destructive surprises |
| Automated agent (no human present) | Not yet supported | Agent keys in development; contact support for case-by-case solutions |

### When to use `read_only=true` vs. feature list

| Scenario | Approach |
|----------|----------|
| Audit with zero risk of writes | Add `&read_only=true` to any URL |
| Need some writes but not others | Use explicit feature list (e.g., `?features=manual,catalog,conversations,operations` excludes `manual_write`) |
| Reconnecting with different permissions | Delete old connector, add new one with updated URL |

### Manual editing: `save_manual_chapters` vs. `apply_funnel`

| Task | Use | Why |
|------|-----|-----|
| Edit one or a few chapters | `save_manual_chapters` | Surgical; preserves other chapters and their attachments |
| Replace entire playbook | `apply_funnel` | Atomic; includes shared context and persona in one transaction |
| Restore to previous version | `restore_manual_version` | Creates new version; old one stays in history |

### Catalog updates: read-then-write pattern

| Step | Tool | Why |
|------|------|-----|
| 1. Get current state | `get_product` | Ensures you have the complete row |
| 2. Modify only your field | (in your assistant) | Prevents accidentally clearing other fields |
| 3. Write entire row | `upsert_products` | Upsert is not a patch; missing fields become empty |
| 4. Verify result | `get_product` or `list_products` | Confirm the change took effect |

## Workflow

### Typical task: Audit and fix a sales funnel

1. **Understand the current state**
   - Ask: "Which agent am I working with?" (if multiple agents exist)
   - Read the playbook: "Read my agent's playbook and summarize each chapter"
   - Check credit balance: "What's my credit balance and how many days of AI features do I have left?"

2. **Identify problems**
   - List recent conversations: "Show me the 10 most recent chats"
   - Read failing chats: "Read these conversation IDs and tell me where the customer stopped responding"
   - Use the rubric: Look for dead gates (bot repeats question without answering), missing prices, branches without CTAs, tool failures
   - Ask for numbers: "How many chats died at the same point? Which chapter?"

3. **Propose fixes**
   - Read the problematic chapter: "Show me the 'Qualification' chapter in full"
   - Propose changes: "Rewrite this chapter to ask one question per message instead of three at once. Show me the new version before saving."
   - Review the proposal: Read it yourself; this is the prompt your agent will follow

4. **Apply changes**
   - Save in one batch: "Approve the change. Save it and include any other pending changes we discussed in the same save"
   - Verify: "Confirm it's saved and tell me the new version number"
   - Check history: "Show me the version history and restore the previous version if needed"

5. **Test and measure**
   - Simulate: "Simulate a new chat from my test number +51 999 111 222 with the message 'hola, precio?' and show me the agent's response"
   - Wait and re-audit: Schedule a follow-up audit in 1–2 weeks to measure if the fix worked

### Typical task: Update product catalog

1. **Read the current product**
   ```
   get_product with the product ID
   ```

2. **Modify only what you need**
   - Change price, description, active status, or variants
   - Keep all other fields intact

3. **Write the complete row**
   ```
   upsert_products with the entire product object (not just the changed field)
   ```

4. **Verify the result**
   ```
   get_product again to confirm the change
   ```

### Typical task: Connect an assistant

1. **Choose your client** (Claude, ChatGPT, Codex, or other MCP client)
2. **Get the connection URL**: `https://mcp.darkfunnels.ai/mcp?features=all`
3. **Add the connector** in your client (steps vary by client; see quickstarts)
4. **Authorize** with your OptiMind dashboard account (same account, not a different one)
5. **Test**: "Go through yesterday's conversations and tell me where I'm losing sales"

## Common gotchas

- **Wrong account on reconnect**: If the assistant can't see your business or sees it empty, you authorized with a different account. Remove the connector and reconnect with the correct account.

- **Feature list replaces default**: `?features=orders` alone loses manual, catalog, and conversations. Always name all groups you need: `?features=manual,catalog,conversations,orders`.

- **Playbook advances silently fail**: Writing "avanza al capítulo 5" in prose does NOT execute. The funnel gets stuck. Use the literal line: "Llama a la herramienta advance_chapter con el capítulo 5" (or in English: "Call the advance_chapter tool with chapter 5").

- **Catalog upsert is not a patch**: Missing fields become empty. Always read with `get_product` first, modify only your field, then write the entire row.

- **Destructive operations need confirmation**: Tools marked 🔴 (save_manual_chapters, delete_product, send_operator_message, simulate_new_chat) ask for confirmation before running. This is intentional.

- **Simulation sends real WhatsApp**: `simulate_new_chat` and `simulate_inbound_message` send actual messages to the number you specify. Use only your own test number, never a customer's.

- **Manual versions burn quickly**: Each save creates a new version; only 10 are retained. Batch all changes into one save to avoid wasting slots.

- **Playbook chapters are atomic per conversation**: The agent only sees the current chapter, not others. If a rule must apply everywhere, write it in every chapter where it matters.

- **Customer phone numbers are masked by default**: `51•••••4321` is the default. Add `?pii=full` to see full numbers (your decision at connection time, not changeable mid-conversation).

- **File markers must match file names**: Use `###SEND_FILES: filename###` where `filename` is the file's name without extension. If the file is unlinked, the marker resolves to nothing and disappears silently.

- **Context field is merged, not replaced**: The `context` field contains `CONTEXTO:`, `RESPUESTAS ESPECÍFICAS:`, and `PUNTOS CLAVE:` sections. Rewriting context without preserving these sections erases the shared block.

- **Deleting a chapter doesn't renumber others**: You can end up with chapters [1, 2, 4]. Advance lines pointing to deleted chapters fail silently. Check all advance_to references before deleting.

- **New tools don't show up in old conversations**: The tool list freezes per conversation. Start a new chat to see new tools; reconnecting is only needed to change the URL.

- **No automatic agent key for headless automation**: Connecting requires a person to authorize in a browser. Cron jobs, workers, and agent SDKs can't connect yet. Contact support for case-by-case solutions.

## Verification checklist

Before submitting work:

- [ ] **Connection**: Confirm the assistant is connected to the correct OptiMind account (ask "which account are you connected to?")
- [ ] **Feature list**: If you added `?features=`, verify it includes all groups you need (manual, catalog, conversations, etc.)
- [ ] **Playbook advances**: Search for "Llama a la herramienta advance_chapter" or "Call the advance_chapter tool" in every chapter that should advance
- [ ] **Catalog changes**: After `upsert_products`, re-read with `get_product` to confirm the change took effect
- [ ] **File markers**: Before writing `###SEND_FILES:###` markers, ask the assistant to list library files and confirm the file name matches
- [ ] **Manual saves**: Confirm the save response includes `verified: true` and the new version number
- [ ] **Destructive operations**: Confirm the assistant asked for approval before running (save_manual_chapters, delete_product, send_operator_message, simulate_new_chat)
- [ ] **Simulation numbers**: Verify test messages went to your own test number, not a customer's
- [ ] **Credit balance**: Check `get_credit_balance` before running AI features (generate_manual, optimize_manual, ask_copilot, simulate_*)
- [ ] **No silent failures**: If a tool response says `truncated: true`, ask for the next page or adjust the limit
- [ ] **Audit trail**: For sensitive changes, ask the assistant to confirm the audit log recorded the action

## Resources

**Comprehensive page-by-page navigation:**
https://docs.darkfunnels.ai/llms.txt

**Critical documentation:**
- [Connection URL parameters](https://docs.darkfunnels.ai/referencia/url-de-conexion) — all `?features=` groups and rules
- [Tool reference](https://docs.darkfunnels.ai/referencia/tools) — complete API (Spanish; connector speaks Spanish)
- [Playbook guide](https://docs.darkfunnels.ai/guias/manual) — chapter anatomy, advance logic, file markers, versioning
- [Conversation audit](https://docs.darkfunnels.ai/guias/conversaciones) — how to read chats, the rubric, data protection
- [Catalog management](https://docs.darkfunnels.ai/guias/catalogo) — read-then-write pattern, variants, stock, pricing
- [Security](https://docs.darkfunnels.ai/en/security) — how data is delimited, masked, and audited; why the bridge never moves money
- [Claude.ai quickstart](https://docs.darkfunnels.ai/en/quickstarts/claude-ai) — fastest way to connect (2 minutes, free plan supported)

---

> For additional documentation and navigation, see: https://docs.darkfunnels.ai/llms.txt