Qontak | AI Agent | Meta Business Agent Integration — Phase 3: Connector Gateway + Test/Eval

HEADER BLOCK

Field	Value
PM	Dimas Fauzi Hidayat
PRD Version	1.9
Status	DRAFT (sequenced after Phase 2; also gated on Meta connector API availability)
PRD Type	PHASE (Phase 3 of 3)
Epic	TBD — add once Epic is created
Squad	Chatbot (BOT)
RFC Link	N/A — RFC to follow after PRD is READY
Figma Master	Pending — low-fi wireframes embedded in §6 (Actions column, Testing surface); Figma TBD
Anchor	Yes — Qontak | AI Agent | Meta Business Agent Integration — ANCHOR
Labels	epic:qontak-chatbot | module:ai-agent | feature:meta-business-agent
Last Updated	2026-07-19

---

Table of Contents

• HEADER BLOCK
• CONDITIONAL BLOCK: PHASE CONTEXT
• One-liner + Problem
• Target Users + Persona Context
• Non-Goals
• Scope Changes
• Constraints
• New Features
• API & Webhook Behavior
• System Flow + User Stories
• Rollout
• Observability
• Success Metrics
• Launch Plan & Stage Gates
• Dependencies
• Key Decisions + Alternatives Rejected
• Open Questions
• PRD CHANGELOG

---

CONDITIONAL BLOCK: PHASE CONTEXT

Field	Value
Anchor PRD	Qontak | AI Agent | Meta Business Agent Integration — ANCHOR
Phase	Phase 3 of 3
Phase Goal (verbatim from Anchor Phase Index)	Let MBA execute Qontak-hosted actions through an authenticated connector gateway, and run existing AI agent test cases against Meta's agent test/eval APIs.
Prior phases	Phase 1: MBA-aware runtime (standby persistence, control state, thread control, inbox UI). Phase 2: MBA management on the channel page + knowledge/persona sync on publish.
Deferred to later phases	None — final planned phase. Proactive Agent Event messaging (business-event-triggered follow-ups) is captured as a Could Have story here and rolls to a future ADJUSTMENT if cut.
Cross-phase dependencies	Connector/tool registration uses Phase 2's MBA Graph client and publish-sync trigger; tool execution reuses the AiAgentAction catalog (existing) and Phase 2's linked-agent relationship; test/eval verification uses Phase 1's transcript persistence to compare live behavior.

Evidence note (research grounding): sources: [] — carried from prior phases; validate action-usage demand with Phase 2 beta partners (which of their existing actions they'd expose to MBA is a Stage 0 interview question).

2. One-liner + Problem

One-liner: Give Meta Business Agent hands and a report card — it executes Qontak-hosted actions through a secure gateway, and existing test cases verify it before and after go-live.

Problem: After Phase 2, MBA answers from synced knowledge but cannot do anything: Meta's connector model requires the business to host its own API endpoints, which most Qontak SMBs cannot build — so order lookups, payments, and bookings that Qontak's own AI agent already executes natively (Midtrans, CRM, API actions) are out of MBA's reach, making it strictly weaker than the agent it replaces. And there is no verification loop: admins turn MBA on with no way to run their curated AiAgentTestCase suites against it, so regressions surface on live customers. Strategically, hosting the connector endpoints is Track 3's lock-in ("we keep the hands") — without this phase, a customer's actions could be wired to any vendor's endpoints instead.

---

3. Target Users + Persona Context

Persona	Role	Goal	Pain	Workaround
Primary — Org Admin	Admin who curates the AI agent's actions and owns go-live quality	Expose the actions the team already built to MBA safely, and verify MBA's answers with the same test cases used for the Qontak agent	MBA can't execute any Qontak action; no pre-go-live verification against Meta's agent	Keep transactional intents on the Qontak agent only — splitting the AI experience per topic
Secondary — CS Supervisor	Supervisor accountable for AI resolution quality	Trust that MBA's actions ran correctly and see failures early	Action failures inside MBA are invisible until a customer complains	None

(See Constraints for plan availability and feature flag scope.)

---

4. Non-Goals

1. No customer-hosted connector endpoints — the gateway is Qontak-hosted only; we do not proxy to or register customer-owned URLs.
2. No new action types built for MBA — the existing AiAgentAction catalog (API + native) is the universe; MBA-specific actions are not authored separately.
3. No credentials shared with Meta — Meta receives tool names/schemas only; execution and credentials stay inside Qontak.
4. No scorecard/quality-audit changes — scoring MBA conversations belongs to the Unified Agent Scorecard initiative (it consumes Phase 1 transcripts).
5. No autonomous test generation — test cases come from the existing AiAgentTestCase suites; generating new ones is the QA AI Agent initiative's scope.
6. No mobile changes — web only.

---

Scope Changes

Engineering surfaces this PRD touches (controlled vocab). Kept in sync with the scope_changes frontmatter above.

• Backend — chatbot: the connector gateway — a new authenticated public API surface that receives Meta's tool calls, verifies the caller, executes the mapped AiAgentAction with vaulted credentials, and returns results — architecturally a public, Meta-authenticated sibling of the existing internal AI-Service action-execute endpoint (POST /api/internal/v1/ai_agents/{vendor_ai_agent_id}/actions/execute, action_execute.rb), reusing the same ActionExecutorFactory + CredentialResolver execution path behind a new caller-auth layer and an exposed-actions-only universe; per-action expose flag; connector/tool registration added to the SyncToMetaMba publish flow (schema derived from the action's parameters JSON — incl. its function_parameters key for API actions — exactly as the AI-service tool sync does: sync_to_ai_service.rb:419-484 / skill_pack_builder.rb:103-166, emitting qontak_function_call args); MBA test/eval runner over AiAgentTestCase/AiAgentTestCaseQuestion (models exist, but ground-prd 2026-07-19: no live runner exists today — fetch_room_conversations_worker.rb only mines historical Q/A pairs — so the runner is net-new here or lands first via the Import Test Case initiative; Dependency 6). hub-core: none beyond Phase 2's Graph client gaining connector/tool + test/eval endpoints.
• Frontend — chatbot-fe Bot automation → Actions: "Meta connector" column with per-action expose toggle; Bot automation Testing surface: "Run against Meta agent" option + results view — ground-prd 2026-07-19: the test-case Validation UI exists only in the legacy V1 engine (modules/ai-agent AiAgentModal Validation tab); the current V2 builder has no Testing tab (AiAgentEditor.vue:3057-3059 — Profile/Capabilities/Routing only), so this phase adds a V2 testing surface or extends the one the Import Test Case initiative delivers (Dependency 6). Actions table: real columns are Action name · Action type · Last updated (ActionsTable.vue:170-174) — no Status/Usage columns.
• Infra — public exposure, rate limiting, and WAF/allowlist rules for the gateway endpoint (new public surface — security review is a blocking dependency).

---

5. Constraints

Field	Value
Platform	Web only.
Performance	Gateway tool-call execution ≤ 5s p95 end-to-end (budget pending Meta's documented timeout — Open Question 1); registration sync within the Phase 2 publish SLA (≤ 10 min p95).
Security	Gateway requests must be verifiable as Meta-originated. Per Meta docs v2.0.0 the connector registration carries the credential Meta uses to call the gateway: auth_type ∈ {OAUTH2_CLIENT_CREDENTIALS, API_KEY, BASIC, CUSTOM, NONE} + optional mTLS client certificate (upsertCertificate), rotatable via upsertApiKey/upsertOAuth; Qontak registers a per-org rotating credential (API key or OAuth2 client-credentials; mTLS preferred where supported — final pick at RFC) and monitors connection_status (PENDING_OAUTH/ACTIVE/EXPIRED/ERROR). This is the gateway's own credential — tenant/action credentials still never leave Qontak. Org-scoped: a tool call can only ever execute against the org that registered it; rate-limited per org; full audit log per invocation.
Data limits	Tool responses capped per Meta's connector spec; oversized results truncated with an explicit error, never silently.
Plan scope	Follows Phase 2's packaging decision (Anchor OQ-3); actions exposure inherits the plan gating of the underlying action catalog.
No Mekari AI Services dependency	The reasoning is Meta's; the gateway verifies, resolves, and executes AiAgentAction wholly inside chatbot BE, and test/eval calls Meta's APIs directly — Mekari AI Services appears nowhere in this phase (mirrors the Phase 2 §5 constraint). Code-verified: action execution is already chatbot-BE-owned end to end — action_execute.rb resolves the action from ai_agent.parameters (V2), resolves vaulted org-scoped credentials via CredentialResolver, and executes via the per-type ActionExecutorFactory executors; AI Services is merely today's caller of that internal endpoint. The gateway swaps the caller (Meta, with connector-credential auth) and keeps the execution engine.
Feature flag	mba_connector_gateway | default: OFF per organization. Separate kill switch from mba_management — actions can be disabled without turning MBA off.
Data lifecycle	Gateway invocation logs retained 90 days then purged (aligned with existing action-execution logs); test/eval run results retained with their AiAgentTestCase records.

6. New Features

Surface 1: existing Bot automation → Actions page — one new column.

Actions (existing: Action name · Action type · Last updated)
└── "Meta connector" column (NEW)
    ├── Toggle per action: Exposed / Not exposed (default: Not exposed)
    └── Status: Registered / Pending publish / Failed(+Retry) / —

Surface 2: existing Bot automation → Testing page — one new run target.

Testing (V1 Validation today: AiAgentTestCase list + runs — V2 surface required, Dependency 6)
├── "Run against Meta agent" option (NEW) on a test case (visible only when MBA is Active)
└── Results view (existing pattern): per-question answer + pass/fail + confidence,
    labeled "Meta Business Agent" run (NEW label + eval summary row)

UI states: expose toggle disabled with tooltip when MBA is not Active on any linked number · registration Failed shows retry per action · test run in-progress uses the existing run states · results empty state unchanged.

Wireframe 1 — Actions page, new "Meta connector" column (existing vs. new):

The existing Actions table (real columns: Action name · Action type · Last updated — ActionsTable.vue:170-174; the wireframe's Status/Usage columns do not exist today, Figma should add or drop them deliberately) is unchanged; the single dashed-blue addition is the "Meta connector" column — an expose toggle defaulting off, and the tool's registration status. Exposing an action registers it as a connector tool on the next publish (riding the Phase 2 sync); the schema derives from the action's parameter schema and credentials never leave Qontak. The toggle is the admin's per-action scope choice, not a move: unexposed actions stay Qontak-agent-only, exposed actions serve both agents, and exposing never changes the action's availability to the Qontak agent. It is the action-side mirror of Phase 2's per-source "Meta sync" toggle on Resources — knowledge and actions share one MBA-vs-Qontak scoping model.

Wireframe 2 — Testing page, new "Run against Meta agent" target (existing vs. new):

The existing Testing page and AiAgentTestCase runs are unchanged; the two dashed-blue additions are the "Run vs Meta agent" target and the Meta-labeled results view (per-question answer + pass/fail + eval score). Because it stores on the same run history, an MBA run sits side-by-side with the Qontak-agent run for direct answer-quality comparison.

Figma TBD.

---

7. API & Webhook Behavior

Plain-language contract; auth mechanics and schemas belong to the RFC.

#	Behavior	Entity Affected	Triggered By	Expected Behavior	Failure Behavior
1	Register connector	Meta connector config	First publish with ≥1 exposed action	Register the org's Qontak gateway as the connector (base URL + auth per Meta's spec) via the Phase 2 Graph client	Meta rejection → all exposed actions show Failed; mba_connector_register_failed logged
2	Register/update connector tools	Meta connector tools	Publish (existing event)	Each exposed AiAgentAction is registered as a tool — name, description ("Use this tool when…" guidance), and a request_definition (HTTP method, path template, path/query/header/body schemas) derived from its parameter schema (same derivation as the existing AI-service tool sync); unexposed/deleted actions are deregistered; after registration, a smoke test via Meta's POST …/tools/{tool_id}/run verifies the wiring end-to-end and the result is recorded on the action row	Per-tool failure → Failed + Retry on that action row; siblings unaffected; smoke-test failure → warning state on the row (registered but unverified)
3	Execute tool call	Action execution, audit log	MBA calls the gateway mid-conversation	Verify the request is Meta-originated and org-scoped → execute the mapped AiAgentAction through the same execution engine the AI-Service path uses today (ActionExecutorFactory per action type + CredentialResolver for vaulted org-scoped credentials, per action_execute.rb), passing a distinct trigger value (e.g. meta_business_agent vs today's ai_agent) so the existing action event log separates the callers → return the result within the timeout budget; invocation audited (org, tool, latency, outcome)	Auth failure → rejected + mba_gateway_auth_failed (alerts on spikes); action error → structured error to Meta so MBA can respond gracefully; timeout → structured timeout error + log
4	Enforce org isolation	Gateway	Every tool call	Tool call resolves to exactly one org's action + credentials; cross-org resolution is impossible by construction (tool ids are org-scoped)	Any ambiguous resolution → hard reject + page (severity: security)
5	Run test case against MBA	AiAgentTestCase run	Admin clicks "Run against Meta agent"	Questions sent via Meta's agent_test API — multi-turn via conversation_id (ground-prd 2026-07-19: the multi-turn runner does not exist yet — it arrives via the Import Test Case initiative or is built here; Dependency 6); answers + handoff_reason/no_response_reason stored on the run; eval via Meta's eval-case model: case configs (scenario, categories, max_turns, success_criteria) live at Meta, combo runs submitted by eval_case_ids, job polled through stages (simulation → evaluation → insights), 1–5 conversation + turn scores, top_failure_categories, recommended_actions persisted on the run; run labeled as an MBA run	Test API error → run marked failed with reason; partial runs resumable; eval job FAILED → failed_case_ids surfaced
6	Rate limit	Gateway	Tool-call volume exceeds org budget	Throttle with structured "temporarily unavailable" errors so MBA degrades to a text answer	Sustained throttling → alert (§10)
7	Ingest Meta-side connector logs	Action observability	Scheduled pull (within Meta's 7-day retention window)	GET /agent_connectors/{id}/logs — success rate, p95/p99 latency, failure-pattern summaries merged into the §10 dashboards and the Actions usage views, reconciled against the gateway's own audit log	Log API error → skip cycle + retry next window; divergence gateway-vs-Meta counts > 5% → investigate

Meta API surface & build map — this phase's slice (docs v2.0.0, fetched 2026-07-18):

Meta surface	Endpoints & key facts (v2.0.0)	Qontak builds	Reuses	Where
Connectors	Full CRUD /{phone_number_id}/agent_connectors[/{connector_id}] + POST /upsertApiKey / /upsertOAuth / /upsertCertificate (credential rotation) + GET /logs; Meta calls out to the registered base_url; auth_type ∈ {OAUTH2_CLIENT_CREDENTIALS, API_KEY, BASIC, CUSTOM, NONE} + optional mTLS client cert; connection_status ∈ {PENDING_OAUTH, ACTIVE, EXPIRED, ERROR}; logs: 7-day retention/window, success rate, p95/p99, failure patterns	Register the Qontak gateway as the org's connector with a per-org rotating credential (API key / OAuth2 / mTLS — RFC pick); monitor connection_status; logs ingestion into §10	Phase 2 MBA API client + publish-sync trigger	S01–S03, §7 #1/#7, §5 Security
Connector Tools	Full CRUD /agent_connectors/{connector_id}/tools[/{tool_id}] + POST …/{tool_id}/run (out-of-conversation execution); per tool name, description ("Use this tool when…"), request_definition (HTTP method, path template, path/query/header/body schemas), user_auth_required	Tool registration from exposed AiAgentActions (schema → request_definition); deregister on unexpose/delete; post-registration smoke test via /run	AI-service tool-schema derivation	S01, §7 #2
Agent Test	POST /{phone_number_id}/agent_test — user_msg + conversation_id → multi-turn simulation, no consumer number needed; returns agent_response, handoff_reason, no_response_reason, quick_replies, product_variant_ids (the last two imply a Meta-side commerce/catalog surface — observe in beta, no build)	MBA test runner over existing suites, multi-turn	AiAgentTestCase + the Import Test Case multi-turn runner	S04, §7 #5
Agent Eval	Under /{phone_number_id}/agent-eval: GET /cases (Meta-side case configs: scenario, categories, max_turns, success_criteria), POST /run (combo by eval_case_ids) → job_id, GET /run (stages simulation → evaluation → insights), GET /details, GET /summary; scores 1–5 at conversation + turn level; top_failure_categories, recommended_actions	Eval-case management, combo-run submission + polling, score/insight ingestion onto run history	existing run-history views	S04, §7 #5
Agent Event	POST /{phone_number_id}/agent_event + GET …/{agent_event_id} — event{type ≤256, description ≤1,024, payload ≤4,096 opaque JSON} + to E.164; async statuses request_received/processing/sent/failed/skipped/success + skipped_reason	Event submission from mapped business events + status polling	business event hooks, standby persistence renders the follow-up	S05

---

8. System Flow + User Stories

System Flow

1. Admin opens Bot automation → Actions and toggles "Meta connector" ON for the actions MBA may use.
2. Admin publishes the agent (existing action) → connector + tools register at Meta alongside the Phase 2 knowledge sync.
3. Failure branch: a tool fails to register → Failed badge + retry on that action row; others proceed.
4. A customer asks MBA something transactional ("where's my order?"); MBA picks the tool and calls the Qontak gateway.
5. Gateway verifies the caller, resolves the org-scoped tool, executes the AiAgentAction with vaulted credentials, and returns the result; MBA answers grounded on it.
6. Failure branch: action error or timeout → structured error to Meta; MBA degrades to a text answer; invocation logged + visible in observability.
7. Before (and periodically after) go-live, admin runs an existing test case with "Run against Meta agent"; answers and eval scores are stored on the run.
8. Failure branch: test run fails or scores below the suite's threshold → admin fixes knowledge/actions and republishes before enabling (or keeps the agent constrained to the allowlist).

System-flow diagram (User Journey + tool-execution sequence — mirrors the numbered steps above, all failure branches included):

sequenceDiagram
    autonumber
    actor Adm as Org Admin
    participant Q as Qontak (Actions + connector gateway)
    participant M as Meta MBA
    actor C as Customer

    Adm->>Q: Toggle "Meta connector" ON for selected actions
    Adm->>Q: Publish agent (existing action)
    Q->>M: Register connector + tools (schemas only — no credentials)
    alt A tool fails to register
        M-->>Q: Reject tool
        Q-->>Adm: Failed + Retry on that action row (siblings proceed)
    else Registered
        M-->>Q: Tools registered
    end
    C->>M: "Where's my order?" (transactional)
    M->>Q: Tool call to the gateway
    Q->>Q: Verify Meta-originated + org-scoped — execute AiAgentAction (vaulted creds)
    alt Action succeeds
        Q-->>M: Result
        M-->>C: Grounded answer
    else Action error / timeout / rate-limited
        Q-->>M: Structured error
        M-->>C: MBA degrades to a text answer
    end
    Note over Adm,M: Before go-live and periodically after
    Adm->>Q: Run test case "against Meta agent"
    Q->>M: Send questions via agent test API
    M-->>Q: Answers + eval scores (stored on the run)
    alt Below threshold
        Adm->>Q: Fix knowledge / actions, republish before enabling
    end

User Stories

User Story	Importance	Mockup	Technical Notes	Acceptance Criteria
[MBA3-S01] — Expose an action as an MBA tool As an org admin, I want a per-action toggle that exposes it to MBA on publish, so that I control exactly what Meta's agent can do.	Must Have	§6 Actions wireframe — Figma TBD	Data Fields: • mba_exposed (bool, default false) per AiAgentAction • mba_tool_status (registered | pending | failed) Before-After Behavior: Before: MBA has no tools; the Actions page has no Meta column. After: exposed actions register as connector tools on publish; unexposed/deleted actions are deregistered.	— Happy Path — • AC-1: Given an action is toggled Exposed, when the admin publishes, then it registers at Meta with name/description/args derived from its parameter schema and shows Registered. • AC-2: Given an exposed action is toggled off or deleted, when the next publish runs, then it is deregistered at Meta. • AC-3: Given an action is toggled Exposed or back to Not exposed, when the Qontak AI agent runs, then the action's availability to the Qontak agent is unchanged either way (the toggle adds/removes MBA scope only — per-action MBA-vs-Qontak choice, mirroring Phase 2's per-source "Meta sync" toggle). — Error / Unhappy Path — • ERR-1: Given Meta rejects one tool, when registration completes, then that row shows Failed + Retry and sibling tools are unaffected. — Permission Model — • CAN: org admin • CANNOT: supervisor/agent — column read-only
[MBA3-S02] — Gateway executes MBA tool calls As MBA (on behalf of a customer), I want tool calls executed against the org's real actions, so that customers get transactional answers, not deflections.	Must Have	— (backend)	Data Fields: • org-scoped tool id → AiAgentAction mapping • invocation audit record (org, tool, latency, outcome) Before-After Behavior: Before: no public gateway exists; MBA cannot act. After: authenticated Meta-originated calls execute the mapped action with vaulted credentials and return within the timeout budget.	— Happy Path — • AC-1: Given a registered tool, when Meta calls the gateway with valid auth, then the mapped action executes and the result returns within 5s (p95). • AC-2: Given any tool call, when it resolves, then it executes only against the registering org's action and credentials (org isolation by construction). — Error / Unhappy Path — • ERR-1: Given invalid or unverifiable auth, when a call arrives, then it is rejected with no execution and mba_gateway_auth_failed is logged (spike alert per §10). • ERR-2: Given the underlying action errors or times out, when execution completes, then a structured error returns to Meta (so MBA degrades to text) and the invocation is logged with the failure reason. • ERR-3: Given the org exceeds its rate budget, when further calls arrive, then they are throttled with structured "temporarily unavailable" errors.
[MBA3-S03] — Action observability for supervisors As a CS supervisor, I want to see MBA's action invocations and failures, so that broken integrations surface before customers complain.	Should Have	§6 Actions wireframe — Figma TBD	Data Fields: • invocation log (tool, room ref, outcome, latency) Before-After Behavior: Before: MBA action activity is invisible. After: invocations appear in the existing action-usage views and §10 events power dashboards/alerts.	— Happy Path — • AC-1: Given tool calls executed, when the supervisor views the action's usage, then MBA invocations appear with outcome and timestamp alongside existing usage data. — Error / Unhappy Path — • ERR-1: Given an action fails repeatedly for MBA (≥5 failures in 1h), when the threshold is hit, then the §10 alert fires and the Actions row shows a warning state.
[MBA3-S04] — Run test cases against MBA As an org admin, I want to run my existing test suites against Meta's agent, so that go-live and every republish are verified, not hoped.	Must Have	§6 Testing wireframe — Figma TBD	Data Fields: • test run labeled target: meta_business_agent on existing AiAgentTestCase run records • per-question answer + eval score Before-After Behavior: Before: AiAgentTestCase/Question models exist but there is no live runner (the V1 Validation UI reviews stored Q/A; fetch_room_conversations_worker.rb only mines pairs) and the V2 builder has no Testing tab. After: a V2 testing surface with a run target that sends questions via Meta's agent test API and records eval scores on the run history (runner via Dependency 6 or in-phase).	— Happy Path — • AC-1: Given MBA is Active (or Prepared with an allowlist), when the admin runs a test case against the Meta agent, then every question is executed via Meta's test API and answers persist on the run. • AC-2: Given the run completes, when eval scores return, then the run shows the eval summary and per-question detail labeled as an MBA run. — Error / Unhappy Path — • ERR-1: Given Meta's test API errors mid-run, when the run halts, then completed questions persist, the run is marked failed with reason, and it can resume from the failure point.
[MBA3-S05] — Proactive follow-up via Agent Event (exploratory) As an org admin, I want business events (e.g., payment completed) to trigger an MBA follow-up message, so that the agent closes loops proactively.	Could Have	—	Data Fields: • event → conversation mapping via Agent Event API Before-After Behavior: Before: none. After: selected Qontak events can trigger MBA proactive messages. Rolls to a future ADJUSTMENT if cut.	— Happy Path — • AC-1: Given a mapped business event fires for a live MBA conversation, when the Agent Event API is called, then MBA sends the follow-up and it appears in the room via standby persistence.
[MBA3-S01-NEG] — Credentials never leave Qontak (Guard Rail — from Non-Goal 3) As the sync/registration flow, when tools register at Meta, then only names, descriptions, and arg schemas are sent — never endpoints' credentials or secrets.	Guard Rail	—	—	NEG-1: Given any connector/tool registration payload, when inspected, then it contains no credential material, tokens, or internal endpoint secrets (verified by contract test).
[MBA3-S02-NEG] — Unexposed actions are invisible to Meta (Guard Rail — from Non-Goal 2) As an org admin, when an action is not exposed, then MBA can neither see nor call it.	Guard Rail	—	—	NEG-1: Given an action with mba_exposed = false, when registration syncs and when a forged tool call names it, then it is absent from Meta's tool list and the gateway rejects the call.

Dependencies: MBA3-S02 depends on S01 (registered tools); S03 depends on S02; S04 is independent of S01–S03 (test/eval works without exposed actions); S05 depends on S02.

---

9. Rollout

Stage	Audience	Duration	Exit condition
Stage 0 — Internal QA	Test org + test WABA; gateway exposed to Meta staging only; read-only actions first (e.g., order lookup), then transactional (Midtrans sandbox)	3 weeks	Gate 1
Stage 1 — Closed beta	Phase 2 partner orgs; read-only actions GA'd first, transactional actions per-org opt-in	4 weeks	Gate 2
Stage 2 — GA	mba_connector_gateway available to all MBA-active orgs; transactional actions stay per-action opt-in by design	—	Gate 3

No data migration. Transition behavior: an MBA answering mid-conversation when its tools first register picks them up on Meta's side without redeployment; conversations started before registration simply have no tool access until their next turn.

---

10. Observability

Event	Trigger	Key properties
mba_tool_registered / mba_tool_register_failed	S7 #1/#2	org_id, action_id, meta_error_code
mba_gateway_invocation	S7 #3	org_id, tool, outcome, latency_ms
mba_gateway_auth_failed	S7 #3	source_ip, reason
mba_gateway_org_isolation_violation	S7 #4	(should never fire — severity: security page)
mba_gateway_throttled	S7 #6	org_id, window
mba_test_run_{completed,failed}	S7 #5	org_id, test_case_id, pass_rate, eval_score

Dashboard owner: Chatbot squad (gateway panel shared with Security for auth-failure trends).

Alert thresholds: auth-failure spike (>100/5min) → page; any org_isolation_violation → immediate page (security incident); tool-call error rate >10% per org over 1h → notify support; p95 latency >4s over 15m → investigate.

Post-Launch Monitoring Cadence

Weekly for the first 4 weeks post-GA (Dimas F + Chatbot EM + Security rep for the first two). Immediate investigation: any isolation event (target: zero, ever), or tool-call success <95% weekly.

---

11. Success Metrics

Adoption & Usage:

Metric	Definition	Baseline	Target
⭐ Actions exposed per MBA org	Median # of actions exposed to MBA among gateway-enabled orgs	N/A — capability doesn't exist	≥2 within 60 days of GA (validates "hands" adoption)
Test-before-go-live rate	% of orgs running ≥1 MBA test run before first enable	N/A	≥50%

Quality & Accuracy:

Metric	Definition	Baseline	Target
Tool-call success rate	Successful executions ÷ authenticated invocations	N/A	≥95%
Org isolation violations	Count	N/A	0 — hard guard rail

Efficiency & Impact:

Metric	Definition	Baseline	Target
Transactional containment on MBA rooms	MBA rooms with ≥1 successful tool call resolved without human takeover (via Phase 1 control-state data)	N/A	Reported from GA; target set after 1 quarter of data

---

12. Launch Plan & Stage Gates

Gate	Stage	Criteria (measurable)
Gate 1 — QA exit	Stage 0 → 1	Security review passed (hard gate — new public surface); auth verification + org isolation verified by adversarial tests (forged calls, cross-org tool ids); read-only and Midtrans-sandbox actions round-trip on live MBA; test/eval run completes on the test WABA
Gate 2 — Beta exit	Stage 1 → 2	Tool-call success ≥95% over 2 weeks; zero isolation events; ≥1 partner org running a transactional action live; test-run adoption ≥50% among beta orgs
Gate 3 — GA health	Post-GA	§10 cadence green 4 weeks; rate limiting verified under a real spike or load test

---

13. Dependencies

#	Dependency	Owner	Blocking?	Notes
1	Phase 2 shipped (Graph client, publish sync, linked-agent model, MBA Active state)	Chatbot squad	YES	Registration and enablement ride Phase 2 machinery.
2	Meta connector + agent test/eval API access and documentation (auth spec, timeout budget, payload limits)	Meta via partner manager	YES	The auth mechanism and timeout budget shape the RFC (OQ-1/OQ-2).
3	Security review of the gateway (new authenticated public surface)	Mekari Security	YES	Gate 1 hard gate; engage at RFC stage, not after build.
4	Infra: public routing, WAF/rate-limit rules for the gateway endpoint	Infra squad	YES	Cross-squad; small, but on the critical path.
5	Midtrans sandbox org for transactional Stage 0 tests	Chatbot squad (existing)	NO	Reuses the native-integration test setup.
6	Import Test Case multi-turn runner + a V2-builder testing surface	Chatbot squad (Import Test Case initiative, in build)	YES	Ground-prd 2026-07-19: no live AiAgentTestCase runner exists and the V2 builder has no Testing tab — without this landing first, S04 builds both in-phase (re-estimate).

---

14. Key Decisions + Alternatives Rejected

14a — Decisions Made

Date	Decision	Rationale
2026-07-08	Gateway is Qontak-hosted and executes the existing AiAgentAction catalog — Meta never receives credentials or internal endpoints	Track 3 "we keep the hands": the strategic lock-in, and the only model most SMBs can actually use
2026-07-08	Tool schemas derive from action parameter schemas exactly as the existing AI-service tool sync derives them	One derivation path, already proven in code (ai_service_tool_sync concern); no second schema format to maintain
2026-07-08	Per-action expose toggle, default OFF	Least-privilege by default; a payment action reachable by Meta's agent must be an explicit admin decision
2026-07-08	Registration rides the publish event (with Phase 2's sync), not a separate sync action	Same single mental model: publish = everything Meta knows gets updated
2026-07-08	Test/eval reuses AiAgentTestCase as a second run target rather than a new test entity	The suites and the review UX already exist; MBA is one more target, keeping side-by-side comparison natural

14b — Alternatives Rejected

Alternative	Why Rejected	Date
Proxy/register customer-hosted endpoints as connectors	Abandons the lock-in AND excludes the SMB majority who have no endpoints to host; support burden of debugging third-party APIs	2026-07-08
A separate MBA-actions catalog decoupled from AiAgentAction	Splits curation and drifts capabilities between the two agents; violates the one-source-of-truth doctrine	2026-07-08
Expose all actions automatically when the gateway is enabled	Turns enabling a feature flag into granting Meta's agent payment powers — unacceptable blast radius	2026-07-08
Build a new MBA test framework	AiAgentTestCase + the Import Test Case work already model suites, runs, and review; duplication with no upside	2026-07-08

---

15. Open Questions

#	Type	Question	Owner	Deadline
1	Open Question RESOLVED 2026-07-18	Meta docs v2.0.0: connector auth_type ∈ {OAUTH2_CLIENT_CREDENTIALS, API_KEY, BASIC, CUSTOM, NONE} + optional mTLS client cert, rotatable via upsert endpoints (see §5 Security). Remaining RFC choice: API key vs OAuth2 client-credentials vs mTLS for the per-org gateway credential	Chatbot tech lead	RFC
2	Open Question	Meta's tool-call timeout budget — bounds which existing actions are viable (long-running actions may need async patterns or exclusion)	Chatbot tech lead	RFC
3	Open Question	Eval score semantics: is Meta's eval comparable enough to our judge-based scoring to show side-by-side, or displayed separately?	Dimas F + QA	Stage 0
4	Assumption	Native actions (Midtrans, Qontak CRM) execute unchanged when invoked via the gateway (same code path as agent-invoked execution)	Chatbot tech lead	RFC
5	Risk	Gateway becomes an attack surface (forged calls, enumeration, DoS) — Mitigation: blocking security review (Dependency 3), org-scoped tool ids, rate limiting, WAF, isolation alert paging	Chatbot squad + Security	Gate 1
6	Risk	Meta's connector spec changes or regionally staggers — Mitigation: phase sequenced after Phase 2 GA experience; contract tests pinned to the documented spec version	Chatbot squad	Stage 0

---

PRD CHANGELOG

Version	Date	By	Section	Type	Summary
1.0	2026-07-08	Claude	All	CREATED	Initial Phase 3 PRD created from the MBA strategic-response grounding; drafted ahead of sequencing per PM instruction (gates recorded in Header + Dependencies).
1.1	2026-07-08	Claude	8	MODIFIED	Added the System-flow sequence diagram (mermaid) to §8, transcribing the numbered flow + tool-execution sequence incl. all failure branches (per score-prd 14a.5).
1.2	2026-07-08	Claude	Header, 6, 8	MODIFIED	Embedded the Actions "Meta connector" and Testing "Run vs Meta agent" wireframes (wireframes/phase-3-*.svg) in §6; Header Figma line and story Mockup cells now link them (closes score-prd §6 gap).
1.3	2026-07-18	Claude	Header, 6, 8	MODIFIED	Made the per-action MBA-vs-Qontak scope choice explicit (PM requirement): §6 states the expose toggle is a scope choice that never changes the action's Qontak-agent availability; MBA3-S01 gains AC-3 asserting it; cross-referenced as the action-side mirror of Phase 2's per-source "Meta sync" toggle (Phase 2 PRD v1.3).
1.4	2026-07-18	Claude	Header, 5, 7, 15	MODIFIED	API-grounding vs Meta MBA docs v2.0.0 (§7 Meta API surface & build map): gateway auth resolved (connector auth_type + mTLS + upsert rotation; per-org credential — OQ-1 resolved to an RFC pick); tool request_definition shape + post-registration smoke test via /tools/{tool_id}/run added (§7 #2); agent_test multi-turn via conversation_id + Meta eval-case model with 1–5 conv/turn scores + failure categories specced (§7 #5); Meta connector logs ingestion added (§7 #7).
1.5	2026-07-18	Claude	Header, 7	MODIFIED	Standalone API-inventory doc dissolved into the Phase PRDs per PM instruction: §7 gains this phase's "Meta API surface & build map" table (Connectors, Connector Tools, Agent Test, Agent Eval, Agent Event).
1.6	2026-07-19	Claude	Header, 5	MODIFIED	Zero-Mekari-AI-Services constraint added to §5 (gateway execution + test/eval run wholly in chatbot BE → Meta direct), mirroring Phase 2 v1.6.
1.7	2026-07-19	Claude	Header, Scope, 5, 7	MODIFIED	Actions mechanism code-verified (companion to the Phase 2 resources check): execution is already wholly chatbot-BE-owned (action_execute.rb → ActionExecutorFactory + CredentialResolver; AI Services is only the caller of the internal actions/execute endpoint) — gateway documented as its public Meta-authenticated sibling reusing the same executor path with a distinct audit trigger.
1.8	2026-07-19	Claude	Header, Scope, 6, 7, 8, 13	MODIFIED	ground-prd fixes (all Confirmed P0/P1): test/eval reuse corrected — no live AiAgentTestCase runner exists and the V2 builder has no Testing tab (V1 Validation only); new blocking Dependency 6 (Import Test Case runner + V2 testing surface); Actions table real columns recorded (no Status/Usage); tool-schema derivation pinned to sync_to_ai_service.rb:419-484 (function_parameters is a key inside parameters JSON, not a column).
1.9	2026-07-19	Claude	8	MODIFIED	Mermaid parse fix: semicolons in sequence-diagram message text broke rendering (replaced with em dashes); diagram now validates with mmdc.