\r \r

BBC MCP Tool v2.0 — Safe-by-Default WhatsApp Bot Builder\r

\r

CORE PHILOSOPHY\r

\r v2.0 = v1 + Safety. Same tools, same BBC API, but with mandatory patterns that prevent\r the silent failures, accidental deletions, and unvalidated deploys that plagued v1.\r \r Three pillars:\r

1. VERIFY — After every mutating operation, call the corresponding list_* to confirm\r
2. GATE — Before every destructive operation, show impact and require explicit "yes"\r
3. RECOVER — When something fails, diagnose why and propose a fix, never just stop\r \r ---\r \r

TOOL REFERENCE (Quick)\r

\r | Tool | Purpose | Mutating? |\r |------|---------|-----------|\r | builderbot_list_projects | List all projects | No |\r | builderbot_create_project | Create project | Yes |\r | builderbot_list_flows | List flows in project | No |\r | builderbot_create_flow | Create flow with keywords | Yes |\r | builderbot_update_flow | Update flow config | Yes |\r | builderbot_delete_flow | Delete flow + all answers | Yes (DESTRUCTIVE) |\r | builderbot_list_answers | List answers in flow | No |\r | builderbot_create_answer | Add answer to flow | Yes |\r | builderbot_update_answer | Update answer content | Yes |\r | builderbot_delete_answer | Delete single answer | Yes (DESTRUCTIVE) |\r | builderbot_validate_bot | Health check before deploy | No |\r | builderbot_deploy | Deploy/status/QR/reboot/delete | Yes (some actions) |\r \r ---\r \r

MANDATORY PATTERNS\r

\r

Pattern 1: VERIFY after every mutation\r

\r After ANY create/update/delete, call the corresponding list_* tool to confirm:\r \r

create_flow(projectId, ...) → list_flows(projectId) → search for the new flow\r
create_answer(...)          → list_answers(projectId, flowId) → search for new answer\r
update_answer(...)          → list_answers(projectId, flowId) → confirm content changed\r
delete_flow(...)            → list_flows(projectId) → confirm flow is gone\r
```\r
\r
If verification fails: STOP, report the discrepancy, diagnose, and propose recovery.\r
\r
### Pattern 2: GATE before destructive actions\r
\r
Before `delete_flow`, `delete_answer`, or `deploy(action='delete')`:\r
\r
1. Show what will be affected (flow name, answer count, references)\r
2. Show a clear warning: "⚠️ This cannot be undone"\r
3. Wait for explicit user confirmation\r
4. After execution, VERIFY the deletion\r
5. Run `validate_bot` to check for broken references\r
\r
### Pattern 3: RECOVER on failure\r
\r
When any operation fails or verification shows a discrepancy:\r
\r
1. **Diagnose**: Check limits (flow count), conflicts (duplicate keywords), permissions\r
2. **Report**: Tell user exactly what went wrong\r
3. **Propose**: Offer concrete fix (delete unused flow, rename keyword, retry)\r
4. **Execute**: Fix with user approval, then VERIFY\r
\r
---\r
\r
## FLOW CREATION RULES\r
\r
### create_flow parameters\r
\r
```\r
projectId:        UUID (from list_projects)\r
name:             "Human Readable Name" (Title Case, user's language)\r
label:            "snake_case_slug" (lowercase, no spaces)\r
keywords:         ["keyword1", "keyword2"] or ["EVENTS.WELCOME"]\r
listenKeywords:   false (ALWAYS false unless EVENTS.VOICE_NOTE)\r
transcribeAudio:  true only for EVENTS.VOICE_NOTE\r
interpretImage:   true only for EVENTS.MEDIA\r
analyzeDocument:  true only for EVENTS.DOCUMENT\r
```\r
\r
### CRITICAL RULES\r
\r
- `listenKeywords` MUST be `false` for ALL flows EXCEPT `EVENTS.VOICE_NOTE`\r
- A new flow has 0 answers — the bot will NOT respond until you add answers\r
- Always add answers IMMEDIATELY after creating a flow\r
- Text keywords must be UNIQUE across all flows\r
- System events (EVENTS.*) must not be mixed with text keywords\r
- Each EVENTS.* can appear in only ONE flow\r
\r
### System Events Reference\r
\r
| Event | Use case | Required flags |\r
|-------|----------|----------------|\r
| `EVENTS.WELCOME` | Catch-all / fallback | listenKeywords: false |\r
| `EVENTS.VOICE_NOTE` | Voice message handler | listenKeywords: true, transcribeAudio: true |\r
| `EVENTS.MEDIA` | Image handler | interpretImage: true |\r
| `EVENTS.DOCUMENT` | Document handler | analyzeDocument: true |\r
| `EVENTS.LOCATION` | Location shared | — |\r
| `EVENTS.ACTION` | Button/list response | — |\r
\r
---\r
\r
## ANSWER TYPES REFERENCE\r
\r
### add_text — Simple text message\r
```\r
type: "add_text"\r
message: "Your text here"  ← MAX 160 chars for WhatsApp\r
```\r
\r
### add_chatpdf — AI-powered assistant (Pattern 2)\r
```\r
type: "add_chatpdf"\r
message: ""  ← MUST be empty string\r
```\r
**CRITICAL**: NEVER mix `add_chatpdf` with `add_text` in the same flow.\r
Both fire on every message → broken double-response loop.\r
A flow with `add_chatpdf` must contain ONLY the `add_chatpdf` answer.\r
\r
After creating, configure via `update_answer` with `assistant` field:\r
```\r
assistant: {\r
  instructions: "You are a helpful assistant for [business]...",\r
  model: "gpt-5.4-nano"  (optional)\r
}\r
```\r
\r
### add_image / add_video / add_doc / add_voice_note — Media\r
```\r
type: "add_image"\r
message: ""\r
options: { media: { url: "https://public-url.com/image.jpg" }, gotoFlow: {} }\r
```\r
\r
### add_http — HTTP webhook/API call\r
```\r
type: "add_http"\r
message: ""\r
plugins: {\r
  http: {\r
    url: "https://api.example.com/endpoint",\r
    method: "GET" | "POST",\r
    headers: { "Content-Type": "application/json" },  // optional\r
    body: { key: "value" },  // optional, for POST\r
    rules: []  // REQUIRED — always include, even if empty\r
  }\r
}\r
```\r
**CRITICAL**: `plugins.http.rules` is REQUIRED. Omitting it causes backend rejection.\r
\r
### add_mute — Mute contact (human handoff)\r
```\r
type: "add_mute"\r
plugins: { mute: { status: true, gapTime: 60 } }\r
options: { gotoFlow: { flowId: "farewell-flow-uuid" } }\r
```\r
Mutes the INDIVIDUAL contact, not the whole bot. `gapTime` = minutes until auto-unmute.\r
\r
### add_intent — AI semantic routing\r
```\r
type: "add_intent"\r
plugins: {\r
  intent: {\r
    rules: [{\r
      conditionRule: "The user wants to talk to a human",\r
      conditionFlowId: "\x3Ctarget-flow-uuid>",\r
      condition: "",\r
      conditionValue: ""\r
    }]\r
  }\r
}\r
```\r
\r
### Capture rule\r
`options.capture = true` → bot waits for user reply, passes it to NEXT answer.\r
**NEVER set capture=true on the LAST answer** of a flow — value is silently lost.\r
\r
### Redirect\r
`options.gotoFlow = { flowId: "\x3Ctarget-flow-uuid>" }` → redirect after this answer.\r
\r
---\r
\r
## DECISION TREE: Which Pattern to Use\r
\r
```\r
User request → What type of business?\r
├── Needs appointments/citas/availability → Pattern 2 (AI) ★ RECOMMENDED\r
├── Needs Q&A about products/services    → Pattern 2 (AI)\r
├── Needs order tracking/status          → Pattern 2 (AI) + HTTP\r
├── Simple info (hours, location, menu)  → Pattern 1 (keyword-based) OK\r
├── Lead generation / qualification      → Pattern 2 (AI) + capture\r
└── Human handoff / escalation           → Pattern 2 (AI) + mute\r
```\r
\r
**DEFAULT**: Pattern 2 (AI-powered with `add_chatpdf`) for 80% of real cases.\r
Only use pure keyword → text flows for very simple, static information.\r
\r
---\r
\r
## PATTERN TEMPLATES BY VERTICAL\r
\r
### Salon / Beauty / Services\r
- WELCOME: `add_chatpdf` with instructions about services, prices, availability\r
- AI instructions must include: services list, hours, booking guidance, escalation trigger\r
- Escalation flow: `add_mute` + human handoff\r
- Knowledge base: scrape website with `assistant.scrapeUrl`\r
\r
### Restaurant / Food\r
- WELCOME: `add_chatpdf` with menu, hours, delivery info\r
- Order flow: capture address + items via AI\r
- Location flow: `add_text` with Google Maps link\r
\r
### E-commerce / Store\r
- WELCOME: `add_chatpdf` with catalog, pricing, shipping\r
- Order status: `add_http` to check order API\r
- Support escalation: `add_mute`\r
\r
### Content Creator / Digital Products\r
- WELCOME: `add_chatpdf` with product catalog, pricing\r
- Purchase flow: redirect to payment link\r
- Support: AI handles FAQ, escalates complex issues\r
\r
### Forum / Event\r
- WELCOME: `add_chatpdf` with event details, schedule, registration\r
- Registration: capture data + `add_http` to registration API\r
\r
---\r
\r
## COMPLETE WORKFLOW: Building a Bot\r
\r
### Step 1: Get or Create Project\r
\r
```\r
list_projects()\r
├── Project exists → use its projectId\r
└── Need new → create_project(name) → list_projects() → VERIFY\r
```\r
\r
### Step 2: Plan Flows\r
\r
Before creating anything, plan all flows and share the plan with user:\r
```\r
📋 Bot Plan: [Business Name]\r
├── welcome (EVENTS.WELCOME) — AI assistant with business context\r
├── escalation (keyword: "agente", "humano") — Human handoff\r
├── [additional flows based on business needs]\r
└── Total: N flows\r
```\r
\r
### Step 3: Create Flows (one at a time)\r
\r
For EACH flow:\r
```\r
1. create_flow(projectId, name, label, keywords, ...)\r
2. list_flows(projectId) → VERIFY flow exists, get flow_id\r
3. create_answer(projectId, flowId, type, message, ...)\r
4. list_answers(projectId, flowId) → VERIFY answer exists\r
5. [If add_chatpdf] update_answer(answerId, assistant: { instructions: "..." })\r
6. list_answers(projectId, flowId) → VERIFY instructions set\r
```\r
\r
**NEVER create all flows first then add answers. Create flow → add answers → verify → next flow.**\r
\r
### Step 4: Validate\r
\r
```\r
validate_bot(projectId)\r
├── criticalCount = 0 → Ready to deploy\r
└── criticalCount > 0 → Fix issues first\r
    ├── Dead ends → add answers to empty flows\r
    ├── Long messages → shorten to ≤160 chars\r
    ├── Dangling capture → remove capture from last answer\r
    └── Missing WELCOME → create welcome flow\r
```\r
\r
### Step 5: Deploy (with GATE)\r
\r
```\r
1. validate_bot(projectId) → MUST pass (criticalCount = 0)\r
2. Show deployment summary to user:\r
   ┌─────────────────────────────┐\r
   │ 📤 DEPLOY SUMMARY          │\r
   │ Project: [name]            │\r
   │ Flows: N                    │\r
   │ Answers: M                  │\r
   │ Validation: ✅ PASS        │\r
   │ Confirm? [yes/no]          │\r
   └─────────────────────────────┘\r
3. Wait for user confirmation\r
4. deploy(projectId, action: "create")\r
5. deploy(projectId, action: "status") → check status\r
6. If READY_TO_SCAN → deploy(projectId, action: "qr") → show QR\r
```\r
\r
---\r
\r
## ERROR HANDLING FRAMEWORK\r
\r
### Common Failures & Recovery\r
\r
| Error | Diagnosis | Recovery |\r
|-------|-----------|----------|\r
| Flow created but not in list | Silent failure / API lag | Retry create, verify again |\r
| "Limit reached" | 50/50 flows used | List flows, find unused, offer to delete |\r
| Duplicate keyword | Keyword conflict | list_flows to find conflict, rename |\r
| Answer > 160 chars | WhatsApp truncation | Shorten message, verify |\r
| Deploy fails | Validation issues | Run validate_bot, fix all criticals |\r
| add_chatpdf + add_text in same flow | Double-response bug | Delete the add_text answer |\r
| capture=true on last answer | Dangling capture | Remove capture or add follow-up answer |\r
\r
### Batch Operations: Sequential with Verification\r
\r
When creating multiple flows, ALWAYS do them sequentially:\r
```\r
FOR EACH flow in plan:\r
  1. create_flow → VERIFY\r
  2. create_answer(s) → VERIFY each\r
  3. [configure AI if needed] → VERIFY\r
  THEN next flow\r
```\r
\r
NEVER batch-create all flows then batch-add answers. This hides partial failures.\r
\r
---\r
\r
## FINAL REPORT FORMAT\r
\r
After completing bot creation, always provide:\r
\r
```\r
📊 BOT REPORT: [Project Name]\r
━━━━━━━━━━━━━━━━━━━━━━━━━━━━\r
Project ID: [uuid]\r
\r
✅ Flows Created:\r
  1. [flow_name] (id: [uuid]) — [N] answers — [type summary]\r
  2. ...\r
\r
⚠️ Issues Fixed:\r
  • [description of any issues encountered and resolved]\r
\r
🔍 Validation: [PASS/FAIL]\r
  • Criticals: 0\r
  • Warnings: [N]\r
\r
📤 Deploy Status: [DEPLOYED / NOT YET / READY_TO_SCAN]\r
\r
🔗 Tool Call Trace:\r
  [list of all tool calls made in order]\r
```\r
\r
---\r
\r
## ANTI-PATTERNS (Never Do These)\r
\r
1. ❌ Creating a flow without immediately adding answers\r
2. ❌ Reporting success without verification (`list_*`)\r
3. ❌ Deleting without showing impact and getting confirmation\r
4. ❌ Deploying without running `validate_bot` first\r
5. ❌ Mixing `add_chatpdf` and `add_text` in the same flow\r
6. ❌ Setting `listenKeywords: true` on non-VOICE_NOTE flows\r
7. ❌ Setting `capture: true` on the last answer of a flow\r
8. ❌ Batch-creating all flows before adding answers\r
9. ❌ Ignoring validation warnings about message length (>160 chars)\r
10. ❌ Creating `add_http` answers without `plugins.http.rules: []`\r
\r
---\r
\r
## REFERENCES\r
\r
For vertical-specific templates and advanced patterns, read:\r
- `references/verticals.md` — Detailed bot templates per business type\r
- `references/advanced-patterns.md` — HTTP integrations, multi-flow routing, knowledge base setup