# Meta App Setup For Order Messenger

This guide is for the separate `Order Messenger` Tech Provider fork, not the current live `Polus` WhatsApp bot app.

## Recommended App Strategy

Create a new Meta Business app named `Order Messenger` for the provider product. Reusing the live `Polus` app is possible, but it makes App Review, Embedded Signup, and customer onboarding changes riskier because the app already controls a working number.

Suggested app identity:

- Display name: `Order Messenger`
- App domain: `polustechnology.com`
- Provider portal URL: `https://tech.whatsapp.polustechnology.com`
- Webhook callback URL: `https://tech.whatsapp.polustechnology.com/webhooks/whatsapp`

## 1. Business Prerequisites

Complete these in Meta Business Manager before review:

- Business portfolio exists for Polus Technology Ltd.
- Business verification is completed or in progress.
- Two-factor authentication is enforced for business admins.
- A WhatsApp sender exists for Polus itself so Meta can see your own business use case.
- Privacy policy, terms, and data deletion pages are live on `polustechnology.com`.

## 2. Create The Meta App

In Meta for Developers:

1. Create a new app.
2. Choose a business-oriented app type.
3. Attach it to the Polus Technology business portfolio.
4. Add app details:
   - Display name
   - Contact email
   - App domains: `polustechnology.com`, `www.polustechnology.com`, and `tech.whatsapp.polustechnology.com`
   - Privacy policy URL
   - Terms URL
   - User data deletion URL
   - App icon
   - Category such as `Messenger bots for business`

## 3. Add Products And Use Cases

Add these products/use cases:

- WhatsApp
- Facebook Login for Business
- Webhooks

For the direct Meta Cloud API route, the core permissions you should expect to justify are:

- `whatsapp_business_messaging` for sending and receiving WhatsApp messages.
- `whatsapp_business_management` for WABA, phone number, template, and account management.
- `business_management` for Embedded Signup/business asset onboarding flows.
- `public_profile` as part of Facebook Login.

If you later use Twilio as the provider channel, Meta still requires the app and Embedded Signup, but Twilio handles sender registration through its own Senders API after the customer completes the Meta popup.

## 4. Configure Embedded Signup

In the WhatsApp product area:

1. Create an Embedded Signup configuration.
2. Use the provider portal URL as the launch domain.
3. Copy the Configuration ID into `.env` as `META_EMBEDDED_SIGNUP_CONFIGURATION_ID`.
4. Copy the Meta app ID into `.env` as `META_APP_ID`.
5. Use HTTPS for any public test. Localhost is fine for basic UI development, but reviewers and customer onboarding need a public HTTPS URL.

For coexistence with the WhatsApp Business mobile app, configure the Embedded Signup flow that supports existing WhatsApp Business app users. That allows a customer to keep using the Business App while the Cloud API receives synced messages.

## 5. Configure Webhooks

For this MVP:

- Callback URL: `https://tech.whatsapp.polustechnology.com/webhooks/whatsapp`
- Verify token: the value you set as `META_WEBHOOK_VERIFY_TOKEN`

Subscribe to WhatsApp events needed by your product:

- Messages
- Message status updates
- Account or template events, if Meta exposes them for your app/use case

The MVP records all incoming WhatsApp webhook payloads and maps events to customers by `metadata.phone_number_id`.

## 6. App Review Preparation

Meta reviewers will need to see the customer onboarding flow end to end.

Prepare:

- A public HTTPS provider portal.
- Test credentials or clear reviewer access instructions.
- A screen recording showing:
  - Creating/selecting a customer in your portal.
  - Launching Embedded Signup.
  - Completing the WhatsApp onboarding popup.
  - Seeing the WABA/phone number mapped in your portal.
  - Receiving/sending a test WhatsApp message.
- A short written explanation for each requested permission.
- Confirmation that customer data is only used to provide WhatsApp messaging, order automation, support, and account management.

Suggested reviewer instruction:

```text
Go to https://tech.whatsapp.polustechnology.com and sign in with the reviewer credentials provided.
Create a test customer or use the pre-created test customer.
Click "Launch Embedded Signup" to open Meta's WhatsApp onboarding flow.
Complete the flow with the reviewer business assets/test WhatsApp number.
After the popup closes, return to the dashboard and confirm the onboarding event is shown.
Send a WhatsApp test message to the connected number; the dashboard will show the webhook event under Recent provider events.

The app uses Meta APIs for WhatsApp Business customer onboarding and messaging only. It does not use Facebook Login for consumer social features. Facebook Login for Business is used only to launch Embedded Signup and receive authorization for WhatsApp Business assets.
```

## 7. Direct Meta Vs Twilio Route

Direct Meta route:

- You own token exchange, WABA subscription, phone registration, webhook routing, and billing/credit-line decisions.
- Best long-term if Polus wants direct provider control.
- More review and operational responsibility.

Twilio Tech Provider route:

- You still create and review a Meta app.
- You accept Twilio's Partner Solution request.
- Embedded Signup happens in your app, but Twilio registers WhatsApp senders through its Senders API.
- Usually faster operationally if you want Twilio to absorb more WhatsApp infrastructure.

## 8. MVP Checklist

- Add provider app env values.
- Run `npm run provider:dev`.
- Create a test customer.
- Deploy the provider portal to HTTPS.
- Set the provider webhook URL and verify token in Meta.
- Launch Embedded Signup from the provider portal.
- Record WABA/phone details.
- Send a message and confirm the webhook event maps to the customer.
- Submit App Review with the screen recording and test instructions.