WhatsApp Business — Setup Guide

Everything you need to connect your WhatsApp Business number and put it to work, from a fresh Meta account to a live number that answers your customers automatically.

The integration uses the official Meta WhatsApp Cloud API. Each organisation connects one WhatsApp Business number; once connected, every message your customers send lands in your dashboard, and everything you send goes out from your own number.

01 How it works

Once your number is connected:

• Incoming messages from customers appear in your Conversations inbox in real time: text, images, voice notes, documents, locations and more.
• An installed agent (a configurable bot) can answer each conversation automatically: take orders, book appointments, answer FAQs. You can take over any chat yourself at any time.
• Message templates let you reach customers outside WhatsApp's 24-hour reply window, and campaigns send an approved template to whole contact lists, whether one-off, scheduled or recurring.
• A REST API lets your own software read conversations and send messages programmatically.

There are two ways to connect, covered next: one-click signup with Facebook (recommended, no technical steps) or a manual setup where you bring your own Meta app credentials.

02 What you need from Meta

WhatsApp Business numbers are managed by Meta, so a few things live on their side:

• A Meta Business Portfolio (Business Manager) that is verified; business verification is required to move past the free test number and to raise messaging limits.
• A phone number for the business that is not already active on the WhatsApp / WhatsApp Business consumer apps. You may start with Meta's free test number while trying things out.

If you use the Connect with Facebook button (§3) that is all you need: the signup dialog creates or picks your WhatsApp Business Account and number for you, and no credentials ever need to be copied.

Only for manual setup (§4) do you additionally need your own Meta developer app, and you will collect three values from it:

03 Option A: Connect with Facebook (one click)

The fastest path: everything is provisioned for you.

1. Open Settings → WhatsApp in the dashboard.
2. Click Connect with Facebook. A Facebook window opens where you log in and pick (or create) your business, WhatsApp Business Account and phone number, all inside Meta's own guided flow.
3. Finish the dialog. That's it. The platform completes the connection automatically in the background: it registers your number for messaging, subscribes to incoming messages, and starts your free trial.

No tokens, webhooks or IDs to copy. Within a few seconds the setup page shows your number as connected, and messages sent to it start appearing in your inbox.

04 Option B: Manual setup

Use this when you want to wire up a Meta app you control directly. This is the full walkthrough from a fresh Meta app to a working number.

Step 1: Create the app, WABA and phone number (Meta side)

1. Go to developers.facebook.com → My Apps → Create App → Business.
2. Add the WhatsApp product.
3. Under WhatsApp → API Setup, note the Phone Number ID and the WhatsApp Business Account ID. Add and verify your production phone number (or use the provided test number to start).

Step 2: Generate a permanent access token (System User)

The token shown on Meta's API Setup page is short-lived (~24 hours). For production you need a permanent token from a System User:

1. Business Settings → Users → System Users → Add (create a System User with the Admin role).
2. Add Assets → assign the app and the WABA to that System User with full control.
3. Generate new token, select the app, and grant the permissions whatsapp_business_messaging and whatsapp_business_management.
4. Copy the token; Meta will not show it again.

Step 3: Enter credentials in the dashboard

On Settings → WhatsApp fill the manual form and Save:

On save, the credentials are validated live against Meta. If anything is rejected, the form tells you why. On success your number's display name is pulled in automatically and your free trial starts. The Webhook Secret is optional but recommended: it lets the platform verify that incoming webhook traffic genuinely comes from Meta.

Step 4: Configure the webhook (Meta side)

The webhook is how Meta delivers your customers' messages to the platform.

1. Back on Settings → WhatsApp, find the Webhook Configuration panel. It shows two values generated for your account: a Callback URL and a Verify Token.
2. In Meta: WhatsApp → Configuration → Webhook → Edit. Paste the Callback URL and Verify Token exactly as shown, then click Verify and Save.
3. Under Webhook fields, subscribe to messages (incoming messages + delivery/read receipts), message_template_status_update (template approval updates), and calls (optional, if you use WhatsApp calling).

Step 5: Verify it works

• Send a WhatsApp message to your business number from any phone. It should appear in the Conversations inbox within seconds.
• The setup page should show your number as connected, with your business name and trial days remaining.
• With no agent installed yet, incoming messages are stored but nothing replies. Install an agent (§6) to auto-answer.

05 The Conversations inbox

Every customer who messages your number gets a conversation thread, updated in real time:

• All message types are supported: text, images, video, voice notes, documents, locations, shared contacts, button/list replies and reactions.
• Delivery status: your outgoing messages show sent / delivered / read, just like the WhatsApp app.
• Bot ↔ human handoff: each conversation is answered by the active agent by default. Switch a conversation to human mode to take over yourself; the bot stays silent on that thread until you hand it back.
• Archiving: finished conversations can be archived out of the main list.

06 Agents: automatic replies

An agent is a ready-made bot you install on your number to answer conversations automatically. Pick one that matches your business:

Customer Support (FAQs & ticket capture), E-Commerce (product catalogue & orders), Appointment Booking, Restaurant (menu & orders), Real Estate, Healthcare, Hospitality, Education, Lead Generation, Surveys, Invoicing, Tournaments, Church, and a simple Echo agent for testing your connection.

Installing an agent

1. Open WhatsApp → Agents in the dashboard and browse the catalogue.
2. Install the one you want. Free agents install instantly; paid agents are a one-time purchase (via PesePay) first.
3. Configure it from its settings panel: add your products, services, FAQs, opening hours or whatever the agent works with. Sensible defaults are pre-filled.
4. Activate it. The active agent picks up every new conversation automatically.

You can install several agents but one is active at a time. Remember you can always take over any individual conversation by switching it to human mode; the agent handles the rest.

07 Message templates & auto-send rules

Outside the 24-hour customer service window, WhatsApp only allows pre-approved template messages. Templates are short, reusable messages (with optional variables like a customer's name or order number) that Meta reviews before you can send them.

• Create & submit templates from the dashboard (or start from the curated suggestions offered with each agent). Submission goes to Meta for review.
• Approval status is tracked automatically; you'll see each template move through PENDING → APPROVED (or REJECTED) as Meta reviews it. Only approved templates can be sent.

Auto-send rules send an approved template for you, without you lifting a finger:

• Inactivity: re-engage customers whose conversation has gone quiet for a number of minutes/hours you choose. Rules can apply to all conversations or only those handled by a specific agent.
• Event: send a template when something happens in an agent, e.g. an order is placed or an appointment is booked, with the details filled into the template's variables.

08 Campaigns: bulk template sends

Campaigns send an approved template to a whole contact list:

• Send now or schedule: scheduled campaigns launch automatically at the chosen time (within a minute).
• Recurring: set a campaign to repeat daily, weekly or monthly from a contact group; each run is materialised automatically. Times are in the Africa/Harare timezone.
• Per-recipient tracking: each campaign reports how many messages were sent and how many failed.

09 Subscription & trial

• Free trial: starts automatically the moment your number connects. The trial length and days remaining are shown on the setup page.
• Monthly subscription: when the trial ends, subscribe monthly to keep the integration active. Current pricing is shown in the dashboard.
• Expiry: if the trial or subscription lapses, the integration pauses until you renew. Manage everything under WhatsApp → Subscription.

10 REST API

Integrate WhatsApp into your own software. Base path: /api/v1/whatsapp/. Authenticate every request with your API key in the X-API-KEY header. Generate keys from the API Keys page in the dashboard. All endpoints are scoped to your organisation's connected number.

Example: send a text message

curl -X POST https://sms.localhost.co.zw/api/v1/whatsapp/conversations/<id>/send/ \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"body": "Thanks! Your order is on its way."}'

{"status": "sent", "message_id": "..."}

Example: send a template message

curl -X POST https://sms.localhost.co.zw/api/v1/whatsapp/conversations/<id>/send-template/ \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"template_name": "order_update", "language": "en", "components": [...]}'

Sends can only target existing conversations (customers who have messaged you). Text sends within the 24-hour window; use send-template beyond it. If link shortening (LinksAPI) is enabled for your organisation, links in outgoing text are shortened automatically for click analytics.

11 Troubleshooting

Still stuck? Contact support from the dashboard and include your business number and roughly when the problem started.