WhatsApp

Section: Marketing & Communication
URL: /admin/whatsapp

Overview

WhatsApp is a full-featured messaging hub inside CRMConnect, built on the WhatsApp Business API (WABA / Meta Cloud API). It covers the complete lifecycle of WhatsApp communication: real-time two-way chat with leads and clients, automated chatbot flows, mass-messaging campaigns with approved templates, contact groups for audience segmentation, and a standalone contact directory for bulk outreach — all with granular role-based permissions per sub-module.

Business value

• Who uses it: Sales reps (chat), marketing (campaigns, bots), CRM admins (numbers, templates, groups)
• Key benefit: Consolidate every WhatsApp touchpoint — individual conversations, bulk campaigns, and automated responses — in one place linked to CRM records.
• Metrics it influences: Response time, lead conversion rate, campaign delivery/read rate, support deflection

Typical use cases:

• Sales rep chats with a lead directly from the CRM; the conversation is linked to the lead record and logged automatically
• Marketing sends a promotional campaign to a filtered group of contacts using a Meta-approved message template
• A chatbot answers FAQs outside business hours and routes the conversation to the right staff member based on the reply
• Proposals and invoices are sent to clients over WhatsApp with a single click via action-based template integration

Sub-modules at a glance

1. Chat (Interaction)

URL: /admin/whatsapp/interaction
Permission: whatsapp_chat → view

The main chat interface. Staff can open any conversation thread, send free-form messages or templates, attach media, use quick replies, and assign conversations to colleagues. Each conversation is linked to a CRM lead or client record.

Key concepts

Common actions

1. Open a conversation — click a thread in the left panel to load the message history.
2. Send a message — type in the composer and press send; use the attachment icon for media.
3. Insert a quick reply — type / or click the quick-reply icon to select a predefined message.
4. Send a template — click the template icon to pick an approved WABA template when outside the 24-hour session window.
5. Assign conversation — use the assignment control in the header to hand off to another staff member.
6. Send a proposal via WhatsApp — from the proposal preview menu, click "Send Proposal on WhatsApp"; the system automatically opens or creates the interaction and sends the configured action template.

Action-based template integration

Certain CRM actions can automatically send a WhatsApp template when configured in Settings → WhatsApp → Template per action:

• Proposal sent — template is sent when a proposal is dispatched via the WhatsApp action button.
• Additional action triggers (invoice, estimate, etc.) follow the same pattern.

2. Bots

URL: /admin/whatsapp/bots
Permission: whatsapp_bot → view / create / edit / delete

WhatsApp Bots are automated conversation agents that respond to incoming messages based on a visual flow designed in the Drawflow drag-and-drop editor. Bots support multiple types (keyword triggers, menu-based, AI-assisted) and can reference approved WABA templates for structured responses.

Key concepts

Common actions

1. List bots — /admin/whatsapp/bots shows all bots with name, type, status, and quick actions.
2. Create a bot — click Add Bot, fill in the name, type, and optional template; save to create the record.
3. Design the flow — click the Flow Editor icon to open the Drawflow canvas (/admin/whatsapp/bots/botflow/{id}); drag nodes, connect them, configure each node's message or template, then save.
4. Activate / deactivate — use the toggle on the list row (AJAX call to change_active_status); only one bot needs to be active per trigger scope to avoid conflicts.
5. Duplicate a bot — use the duplicate action to clone a bot's configuration and flow as a starting point for a new one.
6. Edit settings — click edit to update name, type, template binding, or attached media file.
7. Delete bot file — remove the media attachment from a bot without deleting the bot itself.

Flow editor notes

• The editor uses Drawflow (same engine as Marketing Automation).
• Flow JSON is stored in the flow_data column and saved via updateFlow.
• header_params, body_params, and footer_params are JSON arrays that map template variables to dynamic values.

3. Campaigns

URL: /admin/whatsapp/campaigns
Permission: whatsapp_campaign → view / create / edit / delete

WhatsApp Campaigns allow sending a single WABA-approved template message to a large list of recipients (leads, client contacts, or contact groups) in one operation. Delivery and read status are tracked per recipient.

Key concepts

Common actions

1. View all campaigns — /admin/whatsapp/campaigns lists campaigns with status and delivery metrics.
2. Create a campaign — click New Campaign, select the sender number, template, recipient type (leads / contacts / group), pick individual recipients or an entire group, optionally attach a file, then save.
3. Edit a campaign — open an existing campaign before it runs to adjust recipients or template mapping.
4. View campaign report — click a campaign name to see the detail view with delivered %, read %, and the per-recipient log.
5. Pause / Resume — use the pause/resume control on the campaign detail view to halt or continue sending.
6. Delete a campaign — removes the campaign record and its per-recipient data.
7. Delete campaign file — remove the media attachment without deleting the campaign.
8. Filter leads for campaign — use get_filtered_leads (AJAX) to narrow the recipient list by lead criteria before saving.

Campaign analytics

The campaign detail view (/admin/whatsapp/campaigns/view/{id}) shows:

• Total recipients selected vs. total in CRM (as %)
• Delivered count and delivered %
• Read count and read %

4. Groups

URL: /admin/whatsapp/groups
Permission: whatsapp_groups → view / create / edit / delete

Groups are named collections of Bulk Contacts used to segment audiences for campaigns. A contact can belong to multiple groups; a group can be targeted as the recipient list for a campaign.

Common actions

1. List groups — /admin/whatsapp/groups shows all groups with name and contact count.
2. Create a group — click Add Group, enter a name and optional description, save.
3. Edit a group — click edit on any row to update the group name.
4. Delete a group — removes the group; contacts are not deleted, only the group assignment.

5. Bulk Contacts

URL: /admin/whatsapp/BulkContacts
Permission: whatsapp_contacts → view / create / edit / delete

Bulk Contacts is a standalone WhatsApp-specific contact directory, separate from the CRM's leads and clients. Contacts here are the recipients available for campaigns and groups. Phone number uniqueness is enforced.

Key concepts

CSV import format

The import expects a comma-separated file with columns in this order (header row is skipped):

If a phone number already exists, the import skips creating a new record and only assigns the selected groups to the existing contact.

Common actions

1. List contacts — /admin/whatsapp/BulkContacts shows all contacts with their group memberships.
2. Add a contact — click Add Contact, fill in phone number (required, unique), name, and optional fields; assign to one or more groups; save.
3. Edit a contact — update any field or change group assignments.
4. Delete a contact — removes the contact and its group associations.
5. Import from CSV — use the Import button, upload a CSV file, optionally pre-select groups to assign to all imported contacts, then confirm.
6. Bulk delete — select multiple contacts via checkboxes and use the bulk delete action.
7. Bulk assign groups — select multiple contacts and assign them to one or more groups in a single operation.

6. Templates

URL: /admin/whatsapp/templates
Permission: whatsapp_template → view / create / edit / load_template

Templates are Meta-approved WABA message templates required for initiating conversations and for campaign messages. The Templates sub-module syncs with the Meta Graph API to list, create, and manage templates directly from CRMConnect.

Key concepts

Template models

The Template Models page (/admin/whatsapp/templates/template_models) provides one-click creation of standard templates in Meta for:

• Proposal
• Invoice
• Proforma invoice
• Storno (credit note)
• Estimate

Click Load to Meta on any model to submit it for Meta approval. Once approved, the template becomes available for campaigns, bots, and action-based sends.

Common actions

1. View templates — lists all templates synced from Meta with their approval status.
2. Create a template — define header, body, footer, category, language, and submit to Meta for approval.
3. Edit a template — update a draft or rejected template and resubmit.
4. Delete a template — removes the local record and deletes from Meta.
5. Load a template model — use the Template Models page to submit a predefined document template to Meta with one click (requires load_template permission).
6. Get template mapping — when selecting a template in the campaign or bot form, the parameter mapping UI loads automatically via AJAX to display the required variable fields.

7. Quick Replies

URL: /admin/whatsapp/QuickReplies
Permission: quickreplies → view / create / edit / delete

Quick Replies are short named text snippets that chat agents can insert into a conversation instantly. They reduce response time for frequently asked questions or standard greetings.

Common actions

1. List quick replies — /admin/whatsapp/QuickReplies shows all saved replies with name and message preview.
2. Add a quick reply — click Add, enter a name (the shortcut label) and the full message text; save.
3. Edit a quick reply — update the name or message text.
4. Delete a quick reply — removes the shortcut; it will no longer appear in the chat composer.
5. Use in chat — in the Interaction view, click the quick-reply icon or type the shortcut to insert the full message text into the composer.

8. Numbers

URL: /admin/whatsapp/numbers
Permission: whatsapp_numbers → view

Lists all WhatsApp Business phone numbers connected to CRMConnect via the Meta Cloud API. For each number the system fetches and caches the business profile from Meta (profile picture, about text, address, vertical, email, websites).

Key concepts

Numbers are added and configured in Settings → WhatsApp, not through this list view. This page is a read-only overview of active connections.

9. Connection

URL: /admin/whatsapp/connection
Access: Admin only

The Connection page shows the WhatsApp Cloud API integration status and provides the interface for entering or updating the Meta credentials (Access Token, Phone Number ID, Business Account ID, Webhook configuration). Only administrators can access this page.

10. Activity Log

URL: /admin/whatsapp/activity_log

A chronological audit trail of all WhatsApp actions performed within CRMConnect — messages sent and received, campaign dispatches, bot triggers, template sends, and system events. Useful for compliance review and troubleshooting delivery issues.

Permissions reference

Source: crm-connect-main/app/modules/whatsapp/controllers/ · Updated: 2026-06-03