# PLAN — Twilio as a third WhatsApp provider, and a Hong Kong number (2026-10-13)

**Status (2026-10-15): DONE for `+60360431529`.** Built 2026-10-13, Sandbox-tested 2026-10-14,
deployed, and the sender cut over from investhink.ai to production on 2026-10-15 ~00:30 MYT (the
cutover record is in twilio.md → *Production cutover*). Still open: the Hong Kong number (owner tasks
O4–O9 and an outbound-capable +852 caller ID), and broadcasts on a Twilio number (deferred by the
owner, 2026-10-15). What is built is described in
[twilio.md](/docs/modules_handbook/manage/messages/whatsapp/twilio.md). Sibling of
[readMe.md](/docs/modules_handbook/manage/messages/whatsapp/readMe.md); the AI-caller half touches
[voice-agent/readMe.md](/docs/modules_handbook/shared/voice-agent/readMe.md).

## 1. Goal and decisions already taken

Hong Kong leads (the Cantonese `hk-data` funnel and its AI welcome call) should hear from a **+852
number**: the AI calls them from it, and WhatsApp messages come from it.

Owner decisions, 2026-10-13:

| # | Decision |
|---|---|
| D-a | **Twilio is the WhatsApp provider (BSP)** for the HK number: a new provider in the CRM beside Cloud API and the QR Bridge. |
| D-b | The HK number joins the **same Twilio WABA** as the existing Twilio sender (one WABA per Twilio account). No subaccount. |
| D-c | The HK number is **also the AI caller's caller ID** for Hong Kong campaigns. ⚠️ **Blocked on Twilio** — see the Console findings below. |
| D-d | The owner does every Twilio / Meta console step by hand (section 3). |
| D-e | **`+60360431529` moves into the CRM too** (owner, later the same day): the CRM replaces investhink.ai as that sender's receiver, and its past messages are imported (section 4.8). It goes live **first** — it needs no number purchase. |
| D-f | Defaults applied until the owner says otherwise: no broadcasts on Twilio in v1; templates authored in the Twilio Console in v1; no weekly call cap until the HK rule is confirmed. |

**Console findings (owner, 2026-10-13):**
- **The existing Twilio sender `+60360431529` belongs to another system.** Its "Webhook URL for
  incoming messages" is `https://investhink.ai/messaging/webhook/…` (no status callback, no
  Messaging Service). The 10 × 63016 failures are that system sending free-form outside the window.
  → Superseded by D-e: the CRM takes this sender over at a planned cutover (section 6), never by an
  ad-hoc webhook edit.
- **The Twilio WABA and the CRM's Cloud WABA are in different Meta business portfolios.** Business
  verification therefore has to be checked on the Twilio WABA's own portfolio.
- **Buy-a-number search, Hong Kong + Voice:** the Number type list offers only **Mobile** and
  **Toll-free**, and every result is a **Toll-free +852 800** number (US$25/mo). Twilio forbids
  outbound calls from toll-free numbers, so **no self-serve Twilio HK number can be the AI caller's
  caller ID**. Buying also needs a **primary compliance profile** (Trust Hub) first.

## 2. Facts this plan rests on (checked 2026-10-13)

**Twilio numbers in Hong Kong**
- Twilio's pricing CSV lists two HK types: **Mobile (+852 9)** — SMS yes, **voice no**, US$15/month;
  **Toll-Free (+852 800)** — inbound voice only, US$25/month.
  [SiteNumbersPricing.csv](https://assets.cdn.prod.twilio.com/pricing-csv/SiteNumbersPricing.csv)
- The regulatory page lists a third type the CSV omits: **National (+852 30 / +852 58)**, business only.
  It is the likeliest voice-capable type, but no public page says so — **confirm in the Console**
  (Buy a number → Hong Kong → tick Voice). [HK regulatory](https://www.twilio.com/en-us/guidelines/hk/regulatory)
- Since March 2023, a call to Hong Kong that shows a Hong Kong caller ID must use a **Twilio** number
  (Verified Caller ID was withdrawn under OFCA's anti-scam measures).
  [HK voice guidelines](https://www.twilio.com/en-us/guidelines/hk/voice)
- Bundle for a business: Business Registration Certificate, proof of address with the business name
  (≤ 3 months old), authorised representative's ID. Approval ~2–3 business days.

**Twilio WhatsApp**
- One WABA per Twilio account; every sender in the account must be in it; a second sender selects
  the same WABA and Business Portfolio. Before Meta business verification, at most two senders.
  [Self Sign-up](https://www.twilio.com/docs/whatsapp/self-sign-up) · [63102](https://www.twilio.com/docs/api/errors/63102)
- **This WABA is not the CRM's Cloud WABA** (`2094456611497681`). Templates are WABA assets, so every
  template a Twilio channel sends must be created again in Twilio and approved there.
- Templates are **Content Templates**, sent by `ContentSid` + `ContentVariables`; outside the 24-hour
  window anything else fails with 63016. Listed with approval state by
  `GET https://content.twilio.com/v1/ContentAndApprovals`; submitted by
  `POST /v1/Content/{sid}/ApprovalRequests/whatsapp` (`name`, `category`).
  [Content API](https://www.twilio.com/docs/content/content-api-resources)
- A `twilio/quick-reply` button `id` **accepts variables**, and a tap returns it in `ButtonPayload`
  (title in `Body` / `ButtonText`). So the AI-call "call me again" payload, which names the call,
  survives the move to Twilio. [quick-reply](https://www.twilio.com/docs/content/twilio-quick-reply)
- Inbound webhooks are **form-encoded** and signed with `X-Twilio-Signature` (HMAC-SHA1 of the full
  URL + sorted POST params, keyed by the auth token). Status callbacks: queued / sent / delivered /
  read / failed / undelivered, with `ErrorCode`; they may arrive out of order.
- Twilio adds **US$0.005 per message, inbound and outbound**, on top of Meta's per-template fee.
- WhatsApp registration does not touch the number's ordinary voice: Retell keeps calling through the
  SIP trunk. Retell imports a number from any SIP-trunk provider.

**Current CRM (code read 2026-10-13)**
- Providers: `PROVIDER_CLOUD_API = 1`, `PROVIDER_BRIDGE = 2`, `PROVIDER_SANDBOX = 3`, behind the
  `WhatsappDriver` contract resolved by `WhatsappManager`. Credentials live encrypted per channel in
  `provider_config`; `provider_ref` is the inbound routing key.
- **~70 call sites** test `isCloudApi()` / `PROVIDER_CLOUD_API` (52 files) — most of them mean
  "this channel needs approved templates and has a 24-hour window" (section 4.2).
- `SendAiCallFollowUp` sends from **the first connected Cloud channel** — no per-campaign choice.
- The AI caller has **one global caller ID** (`services.retell.from_number`), read by
  `RetellConversationalCaller::call()` and stamped by `PlaceAiVoiceCall`.

## 3. Owner tasks (console, by hand)

| # | Task | Blocks |
|---|---|---|
| O1 | Meta → the **Twilio WABA's** business portfolio → Security Center: check **business verification**. Two numbers (+60360431529 + HK) fit even unverified; verification matters for the **messaging limit** (unverified ≈ 250 business-initiated recipients per 24 h, shared by the portfolio) | HK volume |
| O2 | ✅ Found — the sender's webhook points at **investhink.ai**. **Do not change it yet**: the CRM has no Twilio endpoint until P1 is on production, and a URL with nothing behind it loses every incoming message. The switch is the cutover runbook (section 6) | cutover |
| O3 | ✅ Done — HK + Voice gives Toll-free only. Next: check whether the Number type list has any other option; else open a Twilio ticket for an **outbound-capable HK National number (+852 3x / 5x)**, or source one from another carrier (section 9) | D-c |
| O4 | Create the Trust Hub **primary compliance profile**, submit the HK **regulatory bundle**, then buy a **Mobile (+852 9)** number for WhatsApp (search with SMS ticked, Voice unticked) | O6 |
| O5 | Attach the HK number to the existing **Retell Elastic SIP trunk**, then **import it in Retell** (E.164 + the trunk's termination URI) | P4 caller ID |
| O6 | WhatsApp **Self Sign-up** for the HK number into the same WABA; display name e.g. "PropertyLab Hong Kong". A voice-only number gets its OTP via the Voicemail Twimlet (emailed) | P1 go-live |
| O7 | Create and submit the **Cantonese Content Templates** (list in section 7) | P2 go-live |
| O8 | After deploy: set each sender's **webhook URL + status callback URL** to production (section 4.4) | go-live |
| O9 | Enter the Twilio channel's Account SID + Auth Token **in the CRM page** — never in chat | go-live |

## 4. Design

### 4.1 The provider

- `WhatsappChannel::PROVIDER_TWILIO = 4` (`PROVIDERS` badge "Twilio", colour sky).
- `provider_config` (encrypted): `account_sid`, `auth_token` (or `api_key_sid` + `api_key_secret`),
  `sender` (E.164), optional `messaging_service_sid`.
- `provider_ref` = the sender's E.164 (`+85230…`) — what an inbound webhook's `To` resolves to.
- `WhatsappManager::driver()` maps 4 → `TwilioDriver`.
- Add channel: `ChannelFormModal` gains a **Twilio** type (Account SID, Auth Token, sender number),
  `StoreChannelRequest` validates it (`AC` + 32 hex, E.164), `ChannelsController::createTwilio`
  verifies the credentials with one read-only `GET /2010-04-01/Accounts/{sid}.json` and checks the
  sender is a WhatsApp sender of that account before saving.

### 4.2 "Official channel" helpers, and the call-site audit

New on `WhatsappChannel`:
- `isOfficial()` = Cloud **or** Twilio — needs approved templates outside a 24-hour window.
- `canSendFreeformAnytime()` = Bridge or Sandbox.
- `isCloudApi()` keeps its meaning: **Meta Graph only**.

Every call site is re-read and moved to the helper that matches what it means:

| Group | Meaning | Becomes | Sites (examples) |
|---|---|---|---|
| A | template / 24 h window | `isOfficial()` | `WhatsappConversation::canSendFreeform`, `AgentInbox` window, funnel WhatsApp rules (`FunnelWhatsappController`, `FunnelsController`, `FunnelWhatsapp\StoreRequest`, `RunFunnelReminders`, `SendFunnelWhatsAppMessage`, `FunnelWhatsappComposer`), payment automations, booking WhatsApp, reactive flows (`AdvanceFlowRun`, `StartProactiveFlow`, `FlowsController`), AE `HostOptions` / `Workflow`, RevenueJourney dispatcher, the `is_cloud` props (~31 Vue uses keep the prop name, computed from `isOfficial()`) |
| B | Meta Graph feature | stays `isCloudApi()` | Embedded Signup + manual-ID connect, Coexistence, Cloud webhook + forwarding, `ChannelInfoSync` / `SyncWhatsappQuality`, OTP auth templates, BSUID recipients, CEO report channel |
| C | free-form anytime | `canSendFreeformAnytime()` | `SendWebsiteFormWhatsApp` |
| D | broadcasts | **stays Cloud-only in v1** | `BroadcastsController`, `DispatchBroadcastBatch`, `BuildBroadcastAudience`, `WhatsappBroadcastRepository`, `Broadcasts\StoreRequest` |
| E | channel lists | include Twilio | `SyncWhatsappTemplates`, template pickers, `DiagnoseAiCallFollowUps`, Notify's provider default |

The audit is done file by file in the PR, with the group written next to each change, so a reviewer
can see why each site moved.

### 4.3 `TwilioDriver implements WhatsappDriver`

| Method | v1 behaviour |
|---|---|
| `sendText`, `sendMedia` | `POST /2010-04-01/Accounts/{sid}/Messages.json`, `From/To = whatsapp:+…`; media via a short-lived `MediaService::temporaryUrl()` (Twilio fetches a public URL); one attachment per message, ≤ 16 MB |
| `sendTemplate` | `ContentSid` + `ContentVariables`: the CRM's Cloud-style params (`parameters[]`, button `text` / `payload`) are translated with the variable map stored on the synced template (4.5) |
| `parseInboundWebhook` | one `NormalizedMessage` per request: `Body`, `MediaUrl{n}` / `MediaContentType{n}`, `ProfileName`, `WaId`; `ButtonPayload` → `meta.context.interactive.id` (what `considerAiCallButton` already reads); `OriginalRepliedMessageSid` → reply context |
| `parseStatusUpdates` | `MessageSid` + `MessageStatus` → the existing monotonic ladder; `ErrorCode` → the message's error |
| `fetchMedia` | `MediaUrl` with HTTP Basic auth (account SID + token) → `MediaService` |
| `syncTemplates` | `ContentAndApprovals` → `WhatsappRepository::storeTemplates` (4.5) |
| `markRead`, `sendTyping` | no-op in v1 |
| `sendReaction`, `sendLocation`, `sendInteractive`, `editText` | throw a clear "not supported on Twilio" → the message lands FAILED with that reason |
| group / history / presence / label / call parsers | return `[]` (as Cloud does) |

### 4.4 Webhooks

- `POST webhooks/whatsapp/twilio` (inbound) and `POST webhooks/whatsapp/twilio/status` (status
  callback), handled in `WhatsAppWebhookController` like `handleCloud`: resolve the channel by
  `To` (inbound) / `From` (status) → **verify `X-Twilio-Signature` with that channel's token** →
  `200` fast → dispatch `ProcessInboundWhatsAppWebhook($payload, PROVIDER_TWILIO)`. CSRF-exempt
  via `webhooks/*`.
- **One canonical receiver, production** — the same rule as Retell: a sender has one webhook URL.
  Development tests on the **Twilio WhatsApp Sandbox** (its own webhook setting pointing at the dev
  site), so the real senders never point at a dev box.

### 4.5 Templates

- Migration: `whatsapp_templates.provider_template_id` (string 64, nullable, index) — the Content SID.
  `name` = the WhatsApp approval name, so the CRM keeps addressing templates by name + language.
- `components` stores the Twilio `types` block plus a **variable map** (which `{{n}}` is the body's
  first param, which is the URL button's suffix, which is a quick-reply id), so `sendTemplate` can
  translate Cloud-style params without each caller knowing about Twilio.
- Status / category come from the WhatsApp approval request (`approved` → `STATUS_APPROVED`, …).
- Every Twilio channel of the same account gets the same template rows (one sync per channel).
- **Authoring stays in the Twilio Console in v1.** The CRM Templates page (author + submit) remains
  Cloud-only; Twilio rows appear read-only with a "managed in Twilio" badge.

### 4.6 Errors

`SendErrorExplainer` and `BroadcastErrorRouter` learn the Twilio codes that matter: 63016 (outside
window → template needed), 63049 (Meta did not deliver a marketing template — the 131049
equivalent, same cooldown), 63024 (invalid recipient), 63003 / 63032 and any others met in the
spike. An unknown code still says "unknown", never a guess.

### 4.7 AI caller (HK number)

| Change | Detail |
|---|---|
| Caller ID per campaign | `ai_call_profiles.from_number` (string 20, nullable; null = the Delivery APIs default). `ConversationalCaller::call()` gains `?string $fromNumber`; `RetellConversationalCaller`, `LogConversationalCaller` and `PlaceAiVoiceCall` (row `from_number`) use it. The profile form offers the numbers Retell holds (`GET /list-phone-numbers`, read-only, cached). |
| Calling window per campaign | `ai_call_profiles.call_window` (json `{start, end}`, nullable; null = today's global switch). `PlaceAiVoiceCall::outsideCallWindow(?AiCallProfile)`; `SendFunnelAiCall`'s defer and the thank-you countdown pass the profile. The HK campaign gets **09:00–22:00** whatever `RETELL_QUIET_HOURS` says. |
| Follow-up WhatsApp per campaign | `ai_call_profiles.whatsapp_channel_id` (nullable; null = today's "first connected Cloud channel"). `SendAiCallFollowUp` and `templateFor()` use it; the yue / v2 / opt-out template choice is checked against **that** channel. |
| Button taps | Unchanged: Twilio's `ButtonPayload` lands where Cloud's interactive id does, so `considerAiCallButton` and the `/ai-callback/{token}` URL button work as they are. |
| Weekly cap (to confirm) | A third-party summary of HK rules says ≤ 3 calls per week to the same number. Implemented only after the owner confirms the rule (a per-profile `max_calls_per_week`). |

### 4.8 Importing a sender's past messages

Twilio keeps every message the account sent or received, so a sender's history comes from Twilio
itself — no export from investhink.ai is needed for the messages.

- `php artisan whatsapp:import-twilio-history {channel} {--since=} {--dry-run}` pages
  `GET /2010-04-01/Accounts/{sid}/Messages.json` filtered on `From` and on `To` =
  `whatsapp:{sender}` (read-only, oldest first).
- Each row becomes a `whatsapp_messages` row through `WhatsappRepository`: direction from
  `From`/`To`, `provider_message_id` = the Message SID (the existing per-channel unique index makes a
  re-run idempotent), contact + conversation found or created by phone, `is_historical = true` so no
  AI, flow, consent or notify logic fires, `status` from Twilio's final status.
- Contacts are matched to existing leads by phone (the connect-time ContactLinker rule — match only,
  never create a lead).
- Media: **as built**, not downloaded during the import (like every other backfill — the inbox
  fetches it when the bubble is opened); `--with-media` downloads it during the run. A media file
  Twilio no longer holds becomes a text row saying so.
- To verify in P0: how far back Twilio's message log reaches on this account, and whether old media
  is still downloadable. What investhink.ai knows beyond the messages themselves (its bot state,
  tags) is the only thing an export from it would add — not needed for v1.

### 4.9 Migrations

1. `whatsapp_templates.provider_template_id`.
2. `ai_call_profiles.from_number`, `call_window`, `whatsapp_channel_id`.

No change to `whatsapp_channels` (the provider integer and the encrypted config already fit).

## 5. Phases

| Phase | Work | Estimate | Status |
|---|---|---|---|
| P0 spike | Twilio Sandbox: send text / template / media, inbound + button payload + status callbacks, Content API list, quick-reply variable ids. Messages go only to a handset that joined the sandbox, with the owner's go-ahead for each test | 1–2 days | **owed** — needs the owner's handset |
| P1 provider core | constant, driver, webhooks + signature, Add-channel form, inbox send / receive / ticks, error explainer | 4–5 days | built (faked HTTP tests) |
| P2 templates | Content API sync, `provider_template_id` + variable map, `sendTemplate`, pickers | 3 days | built |
| P3 official-channel audit | the helpers + every group A / C / E site, Vue props | 4–5 days | built |
| P-H history import | `whatsapp:import-twilio-history` (4.8) | 2 days | built |
| P4 AI caller | caller ID, calling window, follow-up channel per campaign | 3 days | built (weekly cap not built — D-f) |
| P5 docs, tests, deploy | handbook (`twilio.md` + readMe + voice-agent), tests, deploy, live test on the owner's own phone | 2 days | docs + tests done; deploy + live test owed |

About **4 weeks** of engineering, running in parallel with the owner tasks.

**Go-live order:**
1. **`+60360431529` (MY)** — after P1, P2, P3 and P-H are on production. Needs no purchase.
2. **HK Mobile `+852 9…` (WhatsApp)** — once bought, signed up into the WABA (O4, O6) and its
   templates approved (O7).
3. **HK outbound caller ID** — whenever the owner has an outbound-capable +852 number; then it is a
   profile setting (P4), no code.

## 6. Cutover runbook — `+60360431529` from investhink.ai to the CRM

1. P1–P3 and P-H deployed to **production** (`app.propertylab.com.my`).
2. CRM production → Messages → Settings → Channels → Add channel → **Twilio** → Account SID, Auth
   Token, sender `+60360431529`. Nothing is received yet; outbound works.
3. `whatsapp:import-twilio-history <channel> --dry-run`, check the counts, then run it for real.
4. Agree a cutover time with whoever runs investhink.ai (it will stop receiving this number).
5. Twilio Console → this sender → **Webhook URL for incoming messages** =
   `https://app.propertylab.com.my/webhooks/whatsapp/twilio`, **Status callback URL** =
   `https://app.propertylab.com.my/webhooks/whatsapp/twilio/status`. Write down the old investhink.ai
   URL first — putting it back is the rollback.
6. Owner sends a WhatsApp from their own phone → it appears in the Inbox; reply from the Inbox.
7. Re-run the history import with `--since=` the step-3 time to fill the gap.
8. Stop investhink.ai from **sending** through the account (switch its WhatsApp feature off, or revoke
   the API key it uses), so two systems never answer the same customer.

## 7. Templates the HK number needs (owner task O7)

Cantonese (`zh_HK`), same buttons and variables as today's Cloud versions:

| Purpose | Today on Cloud | Twilio version |
|---|---|---|
| HK funnel welcome | `hk_data_webinar_welcome_1` | same name |
| AI call — thanks (quick replies `AI_CALL_ACK` + call-again id variable) | `ai_caller_thanks_yue_1` | same name |
| AI call — missed (URL button with token suffix) | `ai_caller_missed_yue_1` | same name |
| Unticked the AI-call box | `ai_caller_optout_yue_1` | same name |
| HK funnel reminders | per funnel rule | one per rule |

## 8. Out of scope in v1

Broadcasts on Twilio · authoring / submitting templates from the CRM · reactions, location,
interactive menus, typing and read receipts · Coexistence · quality-rating sync (Twilio exposes sender
status only) · CEO reports over Twilio · moving the Cloud number to Twilio or back.

## 9. Risks and open questions

1. **investhink.ai runs `+60360431529` today** (O2). The takeover happens only through the cutover
   runbook (section 6): an early webhook edit loses messages, and a late "stop investhink.ai sending"
   leaves two systems answering one customer. investhink.ai's existing Content Templates live in the
   same account — the CRM syncs and may reuse them, and new template names must not collide.
2. **No self-serve Twilio HK number can place outbound calls** (O3). Until an outbound-capable +852
   number exists — a Twilio National number via a ticket, or another carrier's number on its own SIP
   trunk imported into Retell — HK leads keep being called from `+60360431529`. P4's per-campaign
   caller ID is still built, so switching is a profile setting once the number exists. The WhatsApp
   part is unaffected (it uses the +852 9 Mobile number).
3. **No local send guard.** Like Cloud, a Twilio channel sends for real from any box holding its
   credentials — and this dev VM runs `APP_ENV=production`. Development uses Twilio Sandbox
   credentials only; production credentials are entered on production only.
4. **Two WABAs, two template libraries.** A change to a Cantonese template is made twice (Cloud and
   Twilio) for as long as both carry HK traffic.
5. **Portfolio limits are shared** across every number of the business, whatever the provider.
6. **HK rules beyond the calling window** (pre-recorded / AI voice under the UEMO do-not-call
   register) need a legal check before volume.

## 10. Tests (proportionate)

Feature tests for: the webhook signature (valid / forged), inbound form → message (text, media,
button payload), status ladder + error code, `sendTemplate` variable translation, the
`isOfficial()` window on a Twilio conversation, follow-up channel choice, caller ID pass-through, the
per-campaign calling window. HTTP is faked throughout — no test reaches Twilio or Retell.
