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. 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)

Tool	Purpose	Mutating?
INLINECODE1	List all projects	No
INLINECODE2

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

---

MANDATORY PATTERNS

Pattern 1: VERIFY after every mutation

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

CODEBLOCK0

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. 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. 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

CODEBLOCK1

CRITICAL RULES

• - listenKeywords MUST be false for ALL flows EXCEPT INLINECODE20
• 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

Event	Use case	Required flags
INLINECODE21	Catch-all / fallback	listenKeywords: false
INLINECODE22

Voice message handler | listenKeywords: true, transcribeAudio: true | | EVENTS.MEDIA | Image handler | interpretImage: true | | EVENTS.DOCUMENT | Document handler | analyzeDocument: true | | EVENTS.LOCATION | Location shared | — | | EVENTS.ACTION | Button/list response | — |

---

ANSWER TYPES REFERENCE

add_text — Simple text message

CODEBLOCK2

add_chatpdf — AI-powered assistant (Pattern 2)

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:
CODEBLOCK4

addimage / addvideo / adddoc / addvoice_note — Media

CODEBLOCK5

add_http — HTTP webhook/API call

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)

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

CODEBLOCK8

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

CODEBLOCK9

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 INLINECODE40

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: INLINECODE45

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

CODEBLOCK10

Step 2: Plan Flows

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

Step 3: Create Flows (one at a time)

For EACH flow:
CODEBLOCK12

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

Step 4: Validate

CODEBLOCK13

Step 5: Deploy (with GATE)

CODEBLOCK14

---

ERROR HANDLING FRAMEWORK

Common Failures & Recovery

Error	Diagnosis	Recovery
Flow created but not in list	Silent failure / API lag	Retry create, verify again
"Limit reached"

50/50 flows used | List flows, find unused, offer to delete | | Duplicate keyword | Keyword conflict | list_flows to find conflict, rename | | Answer > 160 chars | WhatsApp truncation | Shorten message, verify | | Deploy fails | Validation issues | Run validate_bot, fix all criticals | | addchatpdf + addtext in same flow | Double-response bug | Delete the add_text answer | | capture=true on last answer | Dangling capture | Remove capture or add follow-up answer |

Batch Operations: Sequential with Verification

When creating multiple flows, ALWAYS do them sequentially:
CODEBLOCK15

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

---

FINAL REPORT FORMAT

After completing bot creation, always provide:

CODEBLOCK16

---

ANTI-PATTERNS (Never Do These)

1. 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 INLINECODE56

---

REFERENCES

For vertical-specific templates and advanced patterns, read:

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