WhatsApp Integration — Setup Guide

VocaLoop sends WhatsApp messages (your WhatsApp template with the project fill link) through the Meta WhatsApp Business Cloud API — Meta's official, free-to-start API. This guide walks you from zero to a working test message.

Looking for SMS instead? See the Twilio SMS integration guide.

What you'll end up with

Three values to paste into Integrations → WhatsApp in VocaLoop:

Prerequisites

• A Facebook account (to log in to Meta's developer tools).

• A phone with WhatsApp installed (to receive your test messages).

• For production later: a phone number not already registered on the WhatsApp consumer app, and a verified Meta business.

Step 1 — Create a Meta developer account and app

1. Go to developers.facebook.com and log in with your Facebook account. If prompted, complete developer registration (verify email/phone).

2. Open My Apps → Create App.

3. When asked for a use case, choose Other, then app type Business.

4. Give the app a name (e.g. VocaLoop Notifications) and create it. If you don't have a Meta Business Portfolio yet, the wizard creates one for you.

Step 2 — Add the WhatsApp product

1. On the app dashboard, find the WhatsApp product card and click Set up.

2. Select (or create) the Business Portfolio to attach it to.

3. You now have a WhatsApp Business Account (WABA) with a free test phone number provided by Meta — enough to develop and verify the integration without registering your own number.

Step 3 — Collect the three credentials

Open WhatsApp → API Setup in the left menu of your app dashboard. This one page shows everything VocaLoop needs:

1. Phone number ID — shown under the "From" phone number selector. Copy the ID, not the phone number itself.

2. WhatsApp Business Account ID — shown just below the Phone number ID.

3. Temporary access token — click Generate access token at the top.

⚠️ The token from API Setup expires after ~24 hours. It's fine for a first test; for anything ongoing, create a permanent token (Step 4).

Add your own phone as an allowed recipient

While you're on API Setup: under the "To" field, choose Manage phone number list and add the WhatsApp number you'll send tests to. Meta's test number can only message up to 5 verified recipients — you'll get error 131030 if you send to anyone else.

Step 4 — Create a permanent access token (recommended)

Temporary tokens die daily. A System User token doesn't expire:

1. Go to business.facebook.com/settings (Meta Business Suite → Settings).

2. Users → System users → Add. Name it (e.g. vocaloop-bot), role Admin.

3. Open the new system user → Assign assets → Apps → select your app → enable Manage app (full control).

4. Click Generate new token:

   • App: your app

   • Expiration: Never

   • Permissions: check whatsapp_business_messaging and

   whatsapp_business_management

5. Copy the token immediately — Meta shows it only once.

Step 5 — Configure VocaLoop

1. Log in to VocaLoop and open Settings → Integrations (Settings in the left sidebar, or go to /settings/integrations).

2. On the WhatsApp card, fill in:

   • Phone number ID — from Step 3

   • Business account ID — from Step 3

   • Access token — the permanent token from Step 4

3. Click Save. The card shows a green Configured badge.

Your token is encrypted at rest and shown masked (••••abcd) from now on. When you edit other fields later, leave the masked token as-is to keep the stored one — only paste a new value when rotating the token.

Step 6 — Verify with a test send

1. Message the sender number first. VocaLoop sends free-project text messages, and WhatsApp only delivers those inside a 24-hour customer service window — i.e. the recipient must have messaged your business number within the last 24 hours. From your phone, send any message (e.g. "hi") to the test number shown on the API Setup page.

2. In VocaLoop, open a project → Templates → WhatsApp, write/save a template, and use the test send with your phone number (international format, e.g. +919876543210).

3. The message should arrive on your phone within seconds. If VocaLoop shows a provider error instead, check the table below.

Going to production

The Meta test number is for development only. To send from your own number:

1. API Setup → Add phone number — register a number that has never been (or is no longer) on the consumer WhatsApp app; verify it via SMS/voice code.

2. Complete Business verification in Business Suite → Settings → Business info (legal documents required). Unverified businesses are limited to 250 business-initiated conversations / 24 h; verification unlocks 1k and scales up with quality rating.

3. Set a display name and profile for the number.

4. Update the Phone number ID in VocaLoop to the new number's ID (the WABA ID and token stay the same).

Also note: messages outside a 24-hour window require pre-approved template messages (created under WhatsApp Manager → Message templates). VocaLoop currently sends free-project text, so recipients must have messaged you first — fine for reply-to-request flows, worth knowing for cold sends.

Troubleshooting

Security notes

• The access token is a full-power credential for your WABA — treat it like a password. VocaLoop encrypts it at rest (Fernet, ENCRYPTION_KEY in the root .env) and masks it in every API response.

• Self-hosting: set a real ENCRYPTION_KEY in .env before saving integrations. If you rotate that key, saved configs can no longer be decrypted and must be re-entered.

• Rotate the token by pasting a new value over the masked one and saving.