WhatsApp Module – Settings

WhatsApp Module – Full Settings (3-Step Configuration Flow)

The WhatsApp Module in Biz1 is a fully configurable communication system that allows an organization to connect WhatsApp, manage credits, send documents, and communicate with customers and groups directly from the platform.

The WhatsApp Settings are implemented as a 3-step configuration flow. These steps define how WhatsApp works technically and operationally inside the system. Without completing these settings, the WhatsApp page cannot connect, send messages, or use templates.

This document provides a full long description of the WhatsApp settings flow, including where it appears, what each step does, all configuration details, and how it is used by the WhatsApp page.

1. WhatsApp Settings – Overall Purpose

The 3-step WhatsApp settings flow is responsible for configuring:

Credits & subscriptions (how many WhatsApp messages can be sent)
Message templates (what content is sent with documents)
Provider connection (how Biz1 connects to WhatsApp)

These settings directly power the WhatsApp page (dashboard/whatsappweb), which is where users actually chat with customers and groups.

In short:

Settings define capability → WhatsApp page uses that capability

2. Where the WhatsApp Settings Appear

The WhatsApp settings are accessed from Admin Settings.

Location:

dashboard/admin/settings
Trigger:

Clicking “Whatsapp” in the Settings sidebar opens the WhatsApp settings modal.
Modal ID:

#modal_whatsapp
Visibility condition:

The WhatsApp settings appear only when the WhatsApp module is enabled for the organization
($whatsapp_lists_module == '1').
Access:

Typically available to organization owners or users with admin/settings permissions.

When opened, the modal automatically loads all relevant WhatsApp data by calling
whatsapp_data_display().

3. WhatsApp Settings Flow – High-Level Structure

The settings are organized into three sequential steps, shown with a progress indicator:

Select Whatsapp plan (Step 1/3)
Whatsapp Templates (Step 2/3)
WhatsApp Provider (Step 3/3)

Each step builds on the previous one.

STEP 1 – Select Whatsapp Plan (Full Deep Description)

Purpose of Step 1

Step 1 defines how many WhatsApp messages the organization can send.

WhatsApp messaging in Biz1 is credit-based. Every outgoing WhatsApp message consumes credits from an active package. These credits are purchased via WhatsApp subscription plans.

This step serves two purposes:

Showing available WhatsApp plans
Showing already purchased packages (“My packages”)

Step 1 UI Overview

Title: Select Whatsapp plan
Progress indicator: 1/3
Help icon
Close button
Plan cards section
My packages table
Add a subscription button
Next button

Available Plan Cards

The plan cards show what WhatsApp plans are available for purchase.

Plans are loaded from the email_sms_plans table
Only rows with type = 'whatsapp' are shown

Each plan card displays:

Type / Data: number of WhatsApp messages (e.g. 500, 1000)
Validity: duration of the plan (e.g. 1 month)
Price: cost of the plan

These cards are informational until a subscription is added.

Add a Subscription

Clicking “Add a subscription” opens a sub-modal where the user:

Selects one of the WhatsApp plans
Completes payment or confirmation
Submits the purchase

On success:

A new record is inserted into email_sms_plans_paid
The My packages table refreshes automatically

My Packages (Very Important)

The My packages table shows all WhatsApp credits currently owned by the organization.

Each row represents a purchased WhatsApp package.

Key fields:

Type: whatsapp
Price: price paid
Data: total message credits purchased
Left Message: remaining messages (Data − used)
Validity: validity period
Date: creation or expiry date

How credits are used

Every time:

A user sends a WhatsApp message
An automation sends a WhatsApp message
A document is sent via WhatsApp

The system decreases “Left Message” from the active package.

If Left Message = 0, WhatsApp sending may be blocked or limited.

Navigation from Step 1

Next → moves to Whatsapp Templates (Step 2)
Close → exits settings modal

STEP 2 – Whatsapp Templates (Full Deep Description)

Purpose of Step 2

Step 2 defines what content is sent when documents are shared via WhatsApp.

WhatsApp Templates are structured message templates used when sending:

Proposals
Purchase orders
Invoices
Receipts
Delivery notes
And other document types

Without templates, document-based WhatsApp messages cannot be formatted correctly.

Step 2 UI Overview

Title: Whatsapp Templates
Progress indicator: 2/3
Help icon
Close button
Add template button
Templates table
Back / Next navigation

Adding or Editing Templates

Users can:

Add a new WhatsApp template
Edit an existing template
Delete templates

Each template defines:

Template ID
Template name
Message body
Which document types it applies to

Templates are stored in the whatsapp_templates table and are ordered by position.

How Templates Are Used

When a document is sent via WhatsApp from anywhere in Biz1:

The system detects the document type
It looks up the matching template in whatsapp_templates
The message content is applied
The WhatsApp message is sent using that template

This applies to:

Manual sends
Automated sends
System-generated document messages

Navigation from Step 2

Back → returns to Step 1 – Select Whatsapp plan
Next → moves to Step 3 – WhatsApp Provider

STEP 3 – WhatsApp Provider (Full Deep Description)

Purpose of Step 3

Step 3 defines how Biz1 connects to WhatsApp itself.

This is the technical connection layer. Without a provider configured, the WhatsApp page cannot:

Load chats
Send messages
Receive messages

Supported Providers

Biz1 supports multiple WhatsApp providers, including:

Green API
Message Bird
Whapi
Higents (for selected organizations)

The selected provider determines how messages are sent and received.

Green API (Most Common Case)

When Green API is selected:

One or more instances can be configured
Each instance represents a WhatsApp number

Instance configuration includes:

idInstance
apiTokenInstance
Mobile number
Default instance flag
Authorization status

Multiple instances allow:

Multiple WhatsApp numbers
Load balancing
Team-based usage

Saving Provider Configuration

When the provider and instances are saved:

Settings are stored at user/organization level
The WhatsApp page immediately uses this configuration

Navigation from Step 3

Back → returns to Step 2 – Whatsapp Templates
No Next (this is the final step)
Closing the modal completes configuration

Relationship with the WhatsApp Page (Critical)

The WhatsApp page (dashboard/whatsappweb) depends entirely on these settings.

Step 1 → Credits

Controls whether messages can be sent and how many.

Step 2 → Content

Controls what message templates are used when documents are sent.

Step 3 → Connection

Controls how Biz1 connects to WhatsApp and which number is used.

If any step is missing or incomplete:

WhatsApp page may not load chats
Messages may fail
Documents may not send

End-to-End Usage Flow

Admin opens Settings → Whatsapp
Step 1: reviews plans, buys packages, checks remaining credits
Step 2: configures templates for document sending
Step 3: selects provider and saves WhatsApp connection
Users open WhatsApp page
Chats load using provider
Messages consume credits
Documents use templates

Final Summary

The WhatsApp Full Settings (3-Step Flow) is the foundation of the WhatsApp Module in Biz1.

Step 1 controls credits
Step 2 controls message structure
Step 3 controls technical connectivity

Together, these steps ensure that the WhatsApp page works reliably, securely, and at scale.