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

CORE PHILOSOPHY#

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

Three pillars:

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

---

TOOL REFERENCE (Quick)#

ToolPurposeMutating?builderbot_list_projectsList all projectsNobuilderbot_create_projectCreate projectYesbuilderbot_list_flowsList flows in projectNobuilderbot_create_flowCreate flow with keywordsYesbuilderbot_update_flowUpdate flow configYesbuilderbot_delete_flowDelete flow + all answersYes (DESTRUCTIVE)builderbot_list_answersList answers in flowNobuilderbot_create_answerAdd answer to flowYesbuilderbot_update_answerUpdate answer contentYesbuilderbot_delete_answerDelete single answerYes (DESTRUCTIVE)builderbot_validate_botHealth check before deployNobuilderbot_deployDeploy/status/QR/reboot/deleteYes (some actions)

---

MANDATORY PATTERNS#

Pattern 1: VERIFY after every mutation#

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

text

create_flow(projectId, ...) → list_flows(projectId) → search for the new flow
create_answer(...)          → list_answers(projectId, flowId) → search for new answer
update_answer(...)          → list_answers(projectId, flowId) → confirm content changed
delete_flow(...)            → list_flows(projectId) → confirm flow is gone

If verification fails: STOP, report the discrepancy, diagnose, and propose recovery.

Pattern 2: GATE before destructive actions#

Before delete_flow, delete_answer, or deploy(action='delete'):

1. Show what will be affected (flow name, answer count, references)
2. Show a clear warning: "⚠️ This cannot be undone"
3. Wait for explicit user confirmation
4. After execution, VERIFY the deletion
5. Run validate_bot to check for broken references

Pattern 3: RECOVER on failure#

When any operation fails or verification shows a discrepancy:

1. Diagnose: Check limits (flow count), conflicts (duplicate keywords), permissions
2. Report: Tell user exactly what went wrong
3. Propose: Offer concrete fix (delete unused flow, rename keyword, retry)
4. Execute: Fix with user approval, then VERIFY

---

FLOW CREATION RULES#

create_flow parameters#

text

projectId:        UUID (from list_projects)
name:             "Human Readable Name" (Title Case, user's language)
label:            "snake_case_slug" (lowercase, no spaces)
keywords:         ["keyword1", "keyword2"] or ["EVENTS.WELCOME"]
listenKeywords:   false (ALWAYS false unless EVENTS.VOICE_NOTE)
transcribeAudio:  true only for EVENTS.VOICE_NOTE
interpretImage:   true only for EVENTS.MEDIA
analyzeDocument:  true only for EVENTS.DOCUMENT

CRITICAL RULES#

• listenKeywords MUST be false for ALL flows EXCEPT EVENTS.VOICE_NOTE
• A new flow has 0 answers — the bot will NOT respond until you add answers
• Always add answers IMMEDIATELY after creating a flow
• Text keywords must be UNIQUE across all flows
• System events (EVENTS.*) must not be mixed with text keywords
• Each EVENTS.* can appear in only ONE flow

System Events Reference#

EventUse caseRequired flagsEVENTS.WELCOMECatch-all / fallbacklistenKeywords: falseEVENTS.VOICE_NOTEVoice message handlerlistenKeywords: true, transcribeAudio: trueEVENTS.MEDIAImage handlerinterpretImage: trueEVENTS.DOCUMENTDocument handleranalyzeDocument: trueEVENTS.LOCATIONLocation shared—EVENTS.ACTIONButton/list response—

---

ANSWER TYPES REFERENCE#

add_text — Simple text message#

text

type: "add_text"
message: "Your text here"  ← MAX 160 chars for WhatsApp

add_chatpdf — AI-powered assistant (Pattern 2)#

text

type: "add_chatpdf"
message: ""  ← MUST be empty string

CRITICAL: NEVER mix add_chatpdf with add_text in the same flow. Both fire on every message → broken double-response loop. A flow with add_chatpdf must contain ONLY the add_chatpdf answer.

After creating, configure via update_answer with assistant field:

text

assistant: {
  instructions: "You are a helpful assistant for [business]...",
  model: "gpt-5.4-nano"  (optional)
}

add_image / add_video / add_doc / add_voice_note — Media#

text

type: "add_image"
message: ""
options: { media: { url: "https://public-url.com/image.jpg" }, gotoFlow: {} }

add_http — HTTP webhook/API call#

text

type: "add_http"
message: ""
plugins: {
  http: {
    url: "https://api.example.com/endpoint",
    method: "GET" | "POST",
    headers: { "Content-Type": "application/json" },  // optional
    body: { key: "value" },  // optional, for POST
    rules: []  // REQUIRED — always include, even if empty
  }
}

CRITICAL: plugins.http.rules is REQUIRED. Omitting it causes backend rejection.

add_mute — Mute contact (human handoff)#

text

type: "add_mute"
plugins: { mute: { status: true, gapTime: 60 } }
options: { gotoFlow: { flowId: "farewell-flow-uuid" } }

Mutes the INDIVIDUAL contact, not the whole bot. gapTime = minutes until auto-unmute.

add_intent — AI semantic routing#

text

type: "add_intent"
plugins: {
  intent: {
    rules: [{
      conditionRule: "The user wants to talk to a human",
      conditionFlowId: "<target-flow-uuid>",
      condition: "",
      conditionValue: ""
    }]
  }
}

Capture rule#

options.capture = true → bot waits for user reply, passes it to NEXT answer. NEVER set capture=true on the LAST answer of a flow — value is silently lost.

Redirect#

options.gotoFlow = { flowId: "<target-flow-uuid>" } → redirect after this answer.

---

DECISION TREE: Which Pattern to Use#

text

User request → What type of business?
├── Needs appointments/citas/availability → Pattern 2 (AI) ★ RECOMMENDED
├── Needs Q&A about products/services    → Pattern 2 (AI)
├── Needs order tracking/status          → Pattern 2 (AI) + HTTP
├── Simple info (hours, location, menu)  → Pattern 1 (keyword-based) OK
├── Lead generation / qualification      → Pattern 2 (AI) + capture
└── Human handoff / escalation           → Pattern 2 (AI) + mute

DEFAULT: Pattern 2 (AI-powered with add_chatpdf) for 80% of real cases. Only use pure keyword → text flows for very simple, static information.

---

PATTERN TEMPLATES BY VERTICAL#

Salon / Beauty / Services#

• WELCOME: add_chatpdf with instructions about services, prices, availability
• AI instructions must include: services list, hours, booking guidance, escalation trigger
• Escalation flow: add_mute + human handoff
• Knowledge base: scrape website with assistant.scrapeUrl

Restaurant / Food#

• WELCOME: add_chatpdf with menu, hours, delivery info
• Order flow: capture address + items via AI
• Location flow: add_text with Google Maps link

E-commerce / Store#

• WELCOME: add_chatpdf with catalog, pricing, shipping
• Order status: add_http to check order API
• Support escalation: add_mute

Content Creator / Digital Products#

• WELCOME: add_chatpdf with product catalog, pricing
• Purchase flow: redirect to payment link
• Support: AI handles FAQ, escalates complex issues

Forum / Event#

• WELCOME: add_chatpdf with event details, schedule, registration
• Registration: capture data + add_http to registration API

---

COMPLETE WORKFLOW: Building a Bot#

Step 1: Get or Create Project#

text

list_projects()
├── Project exists → use its projectId
└── Need new → create_project(name) → list_projects() → VERIFY

Step 2: Plan Flows#

Before creating anything, plan all flows and share the plan with user:

text

📋 Bot Plan: [Business Name]
├── welcome (EVENTS.WELCOME) — AI assistant with business context
├── escalation (keyword: "agente", "humano") — Human handoff
├── [additional flows based on business needs]
└── Total: N flows

Step 3: Create Flows (one at a time)#

For EACH flow:

text

1. create_flow(projectId, name, label, keywords, ...)
2. list_flows(projectId) → VERIFY flow exists, get flow_id
3. create_answer(projectId, flowId, type, message, ...)
4. list_answers(projectId, flowId) → VERIFY answer exists
5. [If add_chatpdf] update_answer(answerId, assistant: { instructions: "..." })
6. list_answers(projectId, flowId) → VERIFY instructions set

NEVER create all flows first then add answers. Create flow → add answers → verify → next flow.

Step 4: Validate#

text

validate_bot(projectId)
├── criticalCount = 0 → Ready to deploy
└── criticalCount > 0 → Fix issues first
    ├── Dead ends → add answers to empty flows
    ├── Long messages → shorten to ≤160 chars
    ├── Dangling capture → remove capture from last answer
    └── Missing WELCOME → create welcome flow

Step 5: Deploy (with GATE)#

text

1. validate_bot(projectId) → MUST pass (criticalCount = 0)
2. Show deployment summary to user:
   ┌─────────────────────────────┐
   │ 📤 DEPLOY SUMMARY          │
   │ Project: [name]            │
   │ Flows: N                    │
   │ Answers: M                  │
   │ Validation: ✅ PASS        │
   │ Confirm? [yes/no]          │
   └─────────────────────────────┘
3. Wait for user confirmation
4. deploy(projectId, action: "create")
5. deploy(projectId, action: "status") → check status
6. If READY_TO_SCAN → deploy(projectId, action: "qr") → show QR

---

ERROR HANDLING FRAMEWORK#

Common Failures & Recovery#

ErrorDiagnosisRecoveryFlow created but not in listSilent failure / API lagRetry create, verify again"Limit reached"50/50 flows usedList flows, find unused, offer to deleteDuplicate keywordKeyword conflictlist_flows to find conflict, renameAnswer > 160 charsWhatsApp truncationShorten message, verifyDeploy failsValidation issuesRun validate_bot, fix all criticalsadd_chatpdf + add_text in same flowDouble-response bugDelete the add_text answercapture=true on last answerDangling captureRemove capture or add follow-up answer

Batch Operations: Sequential with Verification#

When creating multiple flows, ALWAYS do them sequentially:

text

FOR EACH flow in plan:
  1. create_flow → VERIFY
  2. create_answer(s) → VERIFY each
  3. [configure AI if needed] → VERIFY
  THEN next flow

NEVER batch-create all flows then batch-add answers. This hides partial failures.

---

FINAL REPORT FORMAT#

After completing bot creation, always provide:

text

📊 BOT REPORT: [Project Name]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Project ID: [uuid]

✅ Flows Created:
  1. [flow_name] (id: [uuid]) — [N] answers — [type summary]
  2. ...

⚠️ Issues Fixed:
  • [description of any issues encountered and resolved]

🔍 Validation: [PASS/FAIL]
  • Criticals: 0
  • Warnings: [N]

📤 Deploy Status: [DEPLOYED / NOT YET / READY_TO_SCAN]

🔗 Tool Call Trace:
  [list of all tool calls made in order]

---

ANTI-PATTERNS (Never Do These)#

1. ❌ Creating a flow without immediately adding answers
2. ❌ Reporting success without verification ( list_*)
3. ❌ Deleting without showing impact and getting confirmation
4. ❌ Deploying without running validate_bot first
5. ❌ Mixing add_chatpdf and add_text in the same flow
6. ❌ Setting listenKeywords: true on non-VOICE_NOTE flows
7. ❌ Setting capture: true on the last answer of a flow
8. ❌ Batch-creating all flows before adding answers
9. ❌ Ignoring validation warnings about message length (>160 chars)
10. ❌ Creating add_http answers without plugins.http.rules: []

---

REFERENCES#

For vertical-specific templates and advanced patterns, read:

• references/verticals.md — Detailed bot templates per business type
• references/advanced-patterns.md — HTTP integrations, multi-flow routing, knowledge base setup