WhatsApp inbox#

The Inbox is where your business talks to leads on WhatsApp. It is shared: whoever on the team handles the reply, the conversation and its full history belong to the lead in the CRM — not to someone's personal phone.

Who this is for#

• Sales agents — answer replies, send follow-ups, share templates.

• Managers — watch response coverage across the team.

• Admins — connect the WhatsApp number and manage approved templates.

• Difficulty: Medium

• Time: 15 minutes

• Prerequisites: WhatsApp is connected for your business (Settings → Connections → WhatsApp / Messaging) and the conversations plan feature. Templates must be approved before you can start a conversation outside the reply window.

What is on the screen#

• Left rail — every lead with a conversation (most recent first), with an unread count for new inbound messages.
• Thread — the messages with that lead, oldest to newest. Opening a conversation marks the inbound messages as read.
• Composer — where you write. It has two modes: free-form and template.

The 24-hour window (the one rule to remember)#

WhatsApp only lets a business send free-form messages within 24 hours of the lead's last message. Outside that window, every message you start must be an approved template.

Steps#

1. Open the inbox#

1. In the sidebar open WhatsApp → Inbox (/admin/conversations).

Expected result: the conversation list loads with unread counts on the leads who replied.

2. Read and reply#

1. Click a conversation. The thread opens with the full history.
2. Type in the composer if the window is open, or pick a template if it is not.
3. Send.

Expected result: your message is delivered through your business WhatsApp number. The CRM only shows the message as sent after the provider confirms it — there is no fake "sent" bubble.

3. Send a template properly#

1. Switch the composer to template mode.
2. Choose an approved template from the list.
3. Fill in each variable (the template's placeholders, for example the lead's first name or your booking URL).
4. Watch the live preview; if a required variable is missing, the send is blocked and the preview highlights it.

Expected result: the template sends with the values you set. Templates are re-checked against Meta's approval status at the moment you hit send — if a template was paused by Meta, the CRM tells you instead of failing silently.

4. Work the channel guardrails#

• The composer only offers channels the lead actually has (a phone number) and that your business has switched on.
• If the lead replied STOP (or "unsubscribe" / "do not message"), the CRM records an opt-out on the lead and messaging automations stop for them.

Expected result: you cannot accidentally message someone who opted out — the system blocks it and logs it.

Other WhatsApp screens#

Templates screen in one minute#

• Meta-managed rows come from your WhatsApp Business account: category, status and quality are synced from Meta (a "sync from Meta" action refreshes them; local edits are flagged as diverging).
• Local-only templates are legacy rows that never went to Meta — good for internal reference, but they cannot be sent as Meta templates.
• The builder walks through the six numbered template sections (header, body, buttons…) with a live bubble preview, and maps positional variables ({{1}}, {{2}}…) to CRM tokens such as lead.first_name, business.booking_url or appointment.date.
• Creating/editing templates requires the WhatsApp templates permission (whatsapp.templates.manage, manager or above).

Expected result#

Every WhatsApp conversation your business has is visible in one shared place, replies are attributed to the lead, and Meta's rules (24-hour window, approved templates, opt-outs) are enforced by the interface instead of being tribal knowledge.

Common mistakes#

• Typing free text outside 24 hours. It will be rejected. Use a template (and plan ahead next time).
• Deleting a template that is still linked to automations. Automations referencing a paused/removed template skip or fail — check the automation before removing anything.
• Expecting instant "sent". The bubble appears when the provider confirms; a slow send shows no bubble yet, not a failure.
• Filling variables loosely. The preview is exact — what it shows is what the customer sees. Check names and dates.
• Ignoring the opt-out. STOP is permanent until the lead messages again; the CRM enforces it. Do not try to work around it from another channel.

Troubleshooting#

Technical details#

• Inbox page: App\Filament\Pages\Conversations (nav label Inbox), plan feature conversations. Shows the last 100 conversations with unread inbound counts.
• Send path: sendMessage dispatches SendLeadMessage; the LeadMessage row is created only after the provider confirms. Template sends use WhatsAppTemplateService::approvedForTenant + WhatsAppVariableResolver::resolveAll (missing tokens block the send) and re-check approval at send time.
• 24-hour window: getOutsideReplyWindowProperty — no inbound WhatsApp, or last inbound older than 24 hours. Provider error for window violations: 131047.
• Opt-outs: WhatsAppMessageService::maybeOptOut — exact keyword match, normalized; keywords from automation.whatsapp_optout_keywords (defaults: stop, unsubscribe, do not message); sets leads.whatsapp_opted_out_at with source inbound_keyword and writes an activity entry.
• Message log: App\Filament\Resources\WhatsAppMessageResource (delivery/read via delivered_at, read_at, provider_status on LeadMessage).
• Templates: App\Filament\Resources\WhatsAppTemplateResource gates management behind whatsapp.templates.manage; Meta-managed rows carry meta_template_id.

Related guides#

• Message templates — template rules in depth.
• WhatsApp automations — send_whatsapp automations.
• Lead 360 view — Open conversation from any lead.
• Notifications — alerts when leads reply.