WhatsApp Meta Cloud API setup — complete guide

1. Create a Meta Business Portfolio

A Business Portfolio (formerly "Business Manager") is the container that owns your WhatsApp Business Account, your Meta App, and your phone number. It's the top-level entity Meta uses for billing and verification.

1. Go to business.facebook.com.
2. Click Create Account. Enter your business legal name, your name, and work email. Use a domain email (hello@yourbrand.com) — Meta prioritizes these.
3. Inside Business Settings, go to Business Info and fill in: legal business name (must match GST / Certificate of Incorporation exactly), address, phone, website URL.
4. Go to People → Add and add yourself as an admin (if you aren't already).

2. Start Business Verification (optional but start early)

Verification is optional to start sending, but required for: higher messaging limits, marketing templates at scale, and the green-tick badge. It takes 1-5 business days, so kick it off now and continue with setup.

1. Business Settings → Security Center → Start verification.
2. Upload: Certificate of Incorporation / GST certificate, a recent utility bill showing the business address, and (optional) your business bank statement header.
3. Verify domain ownership: add a DNS TXT record Meta gives you, or upload an HTML file to your root domain. Shopify: Settings → Domains → DNS settings → Add TXT record. This step is the fastest path to verification.
4. Provide a callable business phone number. Meta may call to confirm.

3. Create a Meta App in the Developer Console

The Meta App is the technical bridge between your Business Portfolio and the Cloud API endpoints. Think of it as the API client that owns your permissions.

1. Go to developers.facebook.com/apps and log in with the same Facebook account that admins your Business Portfolio.
2. Click Create App.
3. Use-case: pick Other → click Next.
4. App type: pick Business → Next.
5. App name: something like "Acme WhatsApp Sender". Contact email: your business email.
6. Business Portfolio: select the Portfolio you created in Step 1. Critical — if you skip this, your app won't be able to own a WABA later.
7. Click Create App. Enter your Facebook password to confirm.

4. Add WhatsApp product to the app

1. On your new app's dashboard, scroll to Add products to your app.
2. Find WhatsApp → click Set up.
3. Meta creates a scratchpad WABA with a test phone number for you. You'll replace this with your real number in Step 7.
4. You're now on the WhatsApp → API Setup page. Leave this tab open — you'll come back to it.

5. Switch the app from Development to Live modeThe #1 mistake new users make.

To flip the app to Live:

1. In the Meta app dashboard, find the toggle in the top bar that says App Mode: Development. Click it.
2. You'll be prompted to complete App setup requirements. Typically two blockers:
   • Privacy Policy URL — paste https://yourstore.com/policies/privacy-policy (Shopify auto-generates this). Must be a live public URL.
   • App Icon — upload a 1024×1024 PNG of your logo.
   • Category — pick "Business and Pages".
   • Business Use (if asked) — select "Support my own business."
3. Hit Save. The toggle now flips to Live.

6. Create a WhatsApp Business Account (WABA)

A WABA is the billing and compliance entity that owns your phone number, templates, and quality ratings. One Business Portfolio can own multiple WABAs (e.g. one per brand).

1. Go to Business Settings → Accounts → WhatsApp Accounts → Add → Create a new WhatsApp account.
2. Name it (this is internal, not customer-facing — e.g. "Acme WA").
3. Assign your Meta App (the one you created in Step 3) to this WABA. Critical — without this link, API calls won't resolve.
4. Assign people: add yourself as Admin.

7. Add and verify your phone number

1. Go to your Meta App → WhatsApp → API Setup → Add phone number.
2. Business display name: the name customers will see (e.g. "Acme Store"). 2-30 characters. Cannot be a personal name unless you're a solo founder, cannot exactly match the phone number format.
3. Category: pick the closest match (Retail, Apparel, Food & Beverage, etc.).
4. Phone number: full E.164 format (+91XXXXXXXXXX). Same format Meta expects for recipients too.
5. Verification method: SMS or Voice call. Pick Voice if the number is a landline or IVR.
6. Enter the 6-digit OTP Meta sends. Verified.

8. Set the 6-digit 2-Factor Authentication PIN

Meta prompts you for a 6-digit PIN during number verification. This PIN protects the number from being stolen and re-registered elsewhere.

1. When prompted, enter any 6 digits you'll remember.
2. Write it down. Store it in a password manager (1Password, Bitwarden, etc.). You will need this PIN again if you later migrate the number, change WABAs, or re-verify.

9. Business display name and profile

1. After number verification, your display name enters a review queue. Most names approve in 1-24 hours.
2. Upload a profile picture (square, ≥ 640×640) in API Setup → Profile. This is the avatar customers see.
3. Fill in the About field (bio text, up to 139 chars).
4. Set the Address, Description, Email, Website — these appear in the business info panel in WhatsApp.

10. Find your WABA ID and Phone Number ID

You need two IDs to configure Alintro:

1. WABA ID: Business Settings → Accounts → WhatsApp Accounts → click your WABA → copy the number next to the name (looks like 1048192734827361).
2. Phone Number ID: in your Meta App → WhatsApp → API Setup page, find the "From" dropdown — the Phone Number ID is shown under your verified number (looks like 398273401827365). NOT the same as your phone number itself.

11. Generate a permanent access token via System User

The token shown on the API Setup page is a temporary 24-hour token. For production you need a permanent token bound to a System User — it doesn't expire even if you log out or rotate passwords.

11a. Create the System User

1. Business Settings → Users → System Users → Add.
2. Name: alintro-sender (or any label).
3. Role: Admin. (Employee role does not work for WhatsApp.)
4. Click Create System User.

11b. Assign assets to the System User

1. Click the new System User → Add Assets.
2. Asset type: Apps. Select your Meta App. Toggle Manage app ON. Save.
3. Click Add Assets again. Asset type: WhatsApp Accounts. Select your WABA. Toggle Full Control (both View and Manage). Save.

11c. Generate the token

1. On the System User page → Generate New Token.
2. App: select your Meta App.
3. Token expiration: Never. (Default is 60 days — change it.)
4. Permissions — tick exactly these two:
   • whatsapp_business_messaging — send messages
   • whatsapp_business_management — manage templates, phone numbers, profile
5. Click Generate Token. Copy it immediately — Meta shows it only once. Paste into your password manager.

12. Paste credentials into Alintro

1. Open your Shopify store → Apps → Alintro (or install from the App Store if you haven't).
2. Navigate to Gateways → Add Gateway → WhatsApp Meta Cloud API.
3. Paste:
   • WABA ID (from Step 10)
   • Phone Number ID (from Step 10)
   • Permanent Access Token (from Step 11c)
4. Click Test connection. Alintro sends a test template to your admin phone. On success you'll see "Test message sent." On failure, the full Meta API error is shown — cross-reference with the error table below.

13. Register message templates

WhatsApp requires every business-initiated message to be a pre-approved template. Only within a 24-hour window after a customer messages you can you send free-form text.

13a. Template categories — pick the right one

13b. Submit a template

1. In Alintro → Templates → New Template. Or in Meta: Business Settings → WhatsApp Accounts → Message Templates → Create Template.
2. Pick Category (Utility / Marketing / Authentication).
3. Pick Language (en, en_US, hi, etc.). You can have the same template in multiple languages.
4. Header (optional): Text, Image, Video, or Document. Max 60 chars for text header.
5. Body: up to 1,024 chars. Use {{1}}, {{2}} for variables. Alintro auto-maps these to your Shopify placeholders.
6. Footer (optional): up to 60 chars.
7. Buttons (optional): Call-to-Action (URL / phone) or Quick Reply.
8. Sample values: Meta requires realistic sample text for each variable. Use real-looking values — "Ramesh Kumar" for a name, "#1042" for an order number. "Test" or "xxx" will get you rejected.
9. Submit. Utility/Auth usually approve in minutes.

13c. Common rejection reasons

• Using a URL shortener (bit.ly, tinyurl) — Meta demands the real destination domain.
• Marketing content in a Utility category template.
• All-caps promotional words ("BUY NOW!!!").
• Missing opt-in language for marketing templates ("Reply STOP to unsubscribe").
• Unrealistic sample values in the variables.
• Asking for sensitive data (credit card, full SSN, password).

14. (Optional) Subscribe to delivery status webhooks

If you want Alintro to update the message status (sent → delivered → read → failed) in real time, enable Meta webhooks.

1. Alintro auto-generates a webhook callback URL and verify token when you save the gateway. Copy them from Gateways → WhatsApp Meta → Webhook.
2. In Meta App → WhatsApp → Configuration → Webhook → Edit.
3. Paste the Callback URL and Verify Token. Click Verify and Save.
4. Subscribe to the messages field. This includes status updates.

15. Send your first real message

1. In your Shopify store, place a test order (draft order or a ₹1 product).
2. Within a few seconds, the admin phone should receive the Order Confirmation template on WhatsApp.
3. Go to Alintro → Message History and verify status = delivered.

Common errors + exact fixes

If Alintro shows a Meta error code, find it here:

Pre-launch checklist

Before you turn on real-customer notifications, verify:

• App mode badge reads "Live" (not Development).
• Privacy Policy URL is live and reachable.
• Phone number verified and display name approved.
• 2FA PIN is stored in a password manager.
• System User has both whatsapp_business_messaging and whatsapp_business_management scopes.
• System User is assigned the WABA (not just the App).
• Permanent token expiration is set to Never.
• At least one template is in "Approved" status.
• Test order from Shopify successfully delivers a WhatsApp message to admin phone.
• Quality Rating on your number is High (green).
• Profile picture, business description, and website are filled in.

FAQ