mirror of
https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools.git
synced 2026-06-18 07:19:35 +00:00
72 lines
2.7 KiB
Markdown
72 lines
2.7 KiB
Markdown
# 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.
|