system-prompts-and-models-of-ai-tools/dealix/docs/WHATSAPP_OPERATOR_FLOW.md

WhatsApp Operator Flow — Design

Message types

• Session messages — conversational text (Arabic).
• Interactive (buttons) — up to 3 reply buttons per message (WhatsApp Cloud API limit).
• Template messages — for opt-in / utility (separate approval with Meta).

Reply buttons

Step 1 — Opportunity / brief

Suggested labels (Arabic):

• قبول → opp:{id}:accept
• تخطي → opp:{id}:skip
• رسالة → opp:{id}:draft (opens second step for message approval)

Step 2 — After «رسالة»

• اعتماد → msg:{draft_id}:approve
• تعديل → msg:{draft_id}:edit
• إلغاء → msg:{draft_id}:cancel

Payload examples

See auto_client_acquisition/personal_operator/whatsapp_cards.py — functions return JSON structures compatible with WhatsApp interactive button payloads. No HTTP send is performed in-repo.

Webhook parse

Inbound events should map button_reply.id through parse_button_reply() to { kind, action, opportunity_id | draft_id }.

Decision mapping

Button id suffix	Meaning
:accept	Accept opportunity → draft path, still approval_required.
:skip	Skip; no outbound.
:draft	Prepare message draft → second step.
:schedule	Meeting draft only until calendar adapter + approval.

Opt-in requirement

• No cold WhatsApp to unknown contacts.
• Opt-in ledger + contactability checks (Compliance OS) before any template or session outbound.

Failure cases

• More than 3 actions → use second message or list message.
• Unknown button id → log + safe default (no send).
• Rate limits / 131047 template issues → surface to operator UI.

Testing checklist

• Payload never exceeds 3 buttons
• IDs stable per opportunity / draft
• Arabic labels render under 20 chars per button title where required
• Webhook signature verification (future)

Staging checklist (webhook — عند التفعيل لاحقاً)

• Meta App + رقم هاتف تجريبي + Verify Token في env السيرفر فقط
• POST /webhook (أو المسار المعتمد) يتحقق من توقيع X-Hub-Signature-256
• Feature flag لأي إرسال فعلي: WHATSAPP_ALLOW_LIVE_SEND → core.config.settings.whatsapp_allow_live_send (الافتراضي false)
• سجل opt-in قبل أي template تسويقي
• اختبار أزرار 3+3 على جهاز حقيقي في sandbox
• لا cold outreach في سيناريوهات الاختبار

Flow principle

Accept / Skip / Draft first; Schedule only after accept or draft path confirms intent.