WhatsApp Integration

Overview

ZenTraq integrates with the WhatsApp Business API to let you communicate with leads and customers directly from the CRM.

Setup

Prerequisites

• A WhatsApp Business Account (WABA) with Meta
• A verified phone number registered with WhatsApp Business API
• A Meta Business Manager account
• An access token from Meta's Cloud API

Configuration

1. Go to Settings → WhatsApp Configuration
2. Enter:
   • Phone Number ID — From Meta Business Manager
   • WhatsApp Business Account ID — Your WABA ID
   • Access Token — Permanent token from Meta
   • Webhook Verify Token — For receiving incoming messages
3. Click Save & Verify
4. Test by sending a test message

Webhook Setup

For receiving incoming messages, configure your webhook in Meta:

• Callback URL: https://your-api-domain/api/whatsapp/webhook
• Verify Token: The token you set in step 2
• Subscribe to: messages, message_delivery_updates, message_reads

How WhatsApp Messaging Works

24-Hour Session Window

WhatsApp Business API has a messaging window rule:

• Session messages (free text): Can only be sent within 24 hours of the customer's last message
• Template messages (pre-approved): Can be sent anytime, regardless of window status

Messaging Flow

Customer messages you → 24-hour window opens → You can send free text
Window expires (no customer reply) → You can only send templates
You send template → Customer replies → 24-hour window re-opens

Sending Messages

From a Lead/Contact Page

1. Open any lead or contact
2. Click the WhatsApp icon
3. The chat panel opens on the right side
4. Type your message and hit Send

Window Status Indicator

• 🟢 Window Open — You can send free text messages
• 🟡 Window Closed — Use a template message to initiate

Template Messages

When the window is closed:

1. Click Send Template button
2. Select an approved template from the list
3. Fill in variable placeholders (e.g., customer name, amount)
4. Click Send Template

Message Templates

What Are Templates?

Templates are pre-approved message formats registered with Meta. They must be approved before use (typically takes 24-48 hours).

Creating Templates

1. Go to Settings → WhatsApp → Templates
2. Click + New Template
3. Fill in:
   • Template name (no spaces, lowercase)
   • Category (Marketing, Utility, Authentication)
   • Language
   • Body text with variables: 1, 2, etc.
   • Optional: Header (text/image/document), Footer, Buttons
4. Submit for Meta approval

Common Templates

Template	Use Case
welcome_message	Greet new leads
appointment_reminder	Remind about scheduled meetings
follow_up	Re-engage cold leads
invoice_sent	Notify about new invoice
payment_reminder	Overdue payment notification
booking_confirmation	Confirm a booking/order
delivery_update	Shipment status update

Opt-In Management

Why Opt-In Matters

WhatsApp requires explicit consent before messaging customers. ZenTraq tracks opt-in status per contact.

Opt-In States

• Opted In — Customer consented to receive messages
• Opted Out — Customer requested no messages
• Unknown — No explicit consent recorded

Managing Opt-In

1. On the WhatsApp chat panel, click Opt-In Status
2. Toggle to Opted In (records consent timestamp and source)
3. Opted-out contacts cannot receive messages

Features

Chat History

• Full conversation history stored in CRM
• Search through past messages
• Media attachments (images, documents, audio)
• Message status: Sent → Delivered → Read

Unread Count

• Badge shows unread messages per lead
• Total unread count in sidebar
• Click to jump to the conversation

Multi-Account Support

If you have multiple WhatsApp numbers (e.g., Sales, Support):

• Configure multiple WhatsApp accounts in Settings
• Select which account to send from
• Incoming messages route to the correct account

Media Sharing

Send and receive:

• Images (product photos, brochures)
• Documents (PDFs, quotes, invoices)
• Audio messages
• Location

Troubleshooting

Messages Not Delivering

1. Window closed — Send a template first
2. Token expired — Refresh access token in Settings
3. Phone number not registered — Verify in Meta Business Manager
4. Template not approved — Check status in Meta
5. Opt-in missing — Enable opt-in for the contact

Not Receiving Incoming Messages

1. Webhook not configured — Check Meta webhook settings
2. Wrong verify token — Must match what's in ZenTraq settings
3. Service not running — Check communication service health

Template Rejected

Common rejection reasons:

• Contains prohibited content
• Missing required opt-out option
• Too promotional for "Utility" category
• Variable placeholders formatted incorrectly

Tips

• Respond quickly — Messages within the 24-hour window don't cost extra
• Use templates strategically — Keep the window open for follow-ups
• Personalize templates — Use variables for customer name, product, amount
• Track delivery — Check message status (sent/delivered/read) for engagement
• Bulk templates — Send template messages to multiple leads for campaigns