Search Knowledge Base Articles

Unified Messaging — Overview & module guide

Module: Unified Messaging v3.8.0

Unified inbox for Facebook, Instagram, WhatsApp and Web Chat in BIXCRM

How to use in BIXCRM (daily operations)

  1. Sign in to the admin area with a role that includes Unified Messaging permissions.
  2. Open Unified Messaging (sidebar) or search for Unified Messaging in the admin menu.
  3. Start on the Dashboard (if available) to see open tasks, pending approvals, and KPIs.
  4. Review Settings after upgrades — new options may need defaults for your company.
  5. Create or import master data first; most modules block transactions until masters exist.
  6. Run the main business flow (create → submit → approve → post/complete) using the screens listed in Admin menu below.
  7. Use Reports / Analytics screens to reconcile stock, finance, compliance, or SLA metrics.
  8. For integrations (API, EDI, gateways, tax), confirm credentials in Settings and monitor logs or webhook delivery screens.
  9. Train staff with role-based access — give approvers approve permissions only, operators create/edit on their area.
  10. If something fails overnight, check BIXCRM cron ran and open the module log / failed queue screen if present.

Admin menu — where to work

Open the Unified Messaging section in the admin sidebar. Screens your staff may use (depending on role):

  • AI Knowledge Base
  • Analytics
  • Audit Logs
  • Automation Rules
  • Block List
  • Bot Flows
  • Channels
  • Conversations
  • Inbox
  • Operations
  • Outgoing Queue
  • Quick Replies
  • Scheduled messages
  • Settings
  • Setup Wizard
  • Ticket Priority Critical
  • Ticket Priority High
  • Ticket Priority Low
  • Ticket Priority Medium
  • Unified Messaging AI Settings
  • Unified Messaging Analytics
  • Unified Messaging Audit Logs
  • Unified Messaging Automation
  • Unified Messaging Block List
  • Unified Messaging Channels
  • Unified Messaging Export
  • Unified Messaging Inbox
  • Unified Messaging Meta Templates
  • Unified Messaging Outgoing Queue
  • Unified Messaging Settings
  • Unified Messaging Templates
  • Web Chat Widget
  • Webhook failures
  • WhatsApp Templates

Detailed guide — features, workflows, API & FAQ

Features

  • Unified inbox with channel filters, staff assignment, CRM linking
  • Web chat widget with AI assistant (DeepSeek, Groq, OpenRouter, Together, OpenAI)
  • Meta webhook integration with HMAC signature validation
  • Async AI replies via cron queue
  • Auto-assign (round robin / default staff)
  • Media download for WhatsApp & Messenger
  • Outbound media send (image, video, PDF) from inbox
  • WhatsApp template message sending with optional components JSON
  • WhatsApp interactive button messages (CSAT)
  • Failed message retry queue (no duplicate rows on retry)
  • Widget rate limiting & domain allowlist
  • Encrypted AI API keys at rest
  • SLA first-response timers with breach alerts
  • CSAT surveys on conversation resolve
  • Analytics dashboard with CSAT and SLA metrics
  • SSE real-time inbox updates (toggle in Settings)
  • WebSocket real-time via Pusher / Soketi (optional alternative to SSE)
  • Business hours with away auto-reply (web chat + Meta channels)
  • Bulk inbox actions (status, assign, mark read, archive)
  • Agent performance analytics chart
  • Visual WhatsApp template parameter builder
  • Starred conversations, My conversations filter, manual CRM link

Phase 4–6 (v2.9.0 – v3.1.1)

  • AI Knowledge Base (RAG) — FAQs, PDF/TXT upload, vector + keyword search
  • Multi-provider embeddings — OpenAI, OpenRouter, Together, Custom (Auto fallback for DeepSeek/Groq chat)
  • Human handoff rules — trigger phrases pause AI, auto-assign staff
  • Bot flow builder — greeting → questions → handoff
  • Sentiment detection — keyword, AI, or hybrid modes with staff alerts
  • AI usage analytics — token counts and estimated cost
  • Inbox filters — sentiment label, AI paused only, resume AI button
  • WhatsApp multi-product list — send catalog product lists from inbox
  • Smart adaptive polling — slower updates when browser tab is hidden (SSE off)

Phase 2 (v2.7.0)

  • Automation rules engine — keyword triggers for auto-reply, assign, tag, lead, status, spam/block
  • Multi-step SLA escalation — configurable steps after first-response breach
  • Outgoing queue UI — view/retry/dismiss failed sends
  • Spam & block list — block by external ID, phone, or email
  • Conversation merge — bulk merge from inbox
  • WhatsApp 24h window badge — session status in inbox header
  • Per-channel business hours — override global away auto-reply per channel

Phase 3 (v2.8.0)

  • Meta template catalog sync — pull approved WhatsApp templates from Business Account
  • Template builder preview — visual preview + inbox picker from synced catalog
  • WhatsApp catalog products — sync and send single product messages
  • WhatsApp Flows — inbound nfm_reply and order message handling
  • Instagram story replies — story reply and mention detection
  • Voice message playback — inline audio player in inbox
  • Read receipts — delivered/read ticks on outbound messages

Setup

Web Chat

  1. Unified Messaging → Web Chat Widget
  2. Configure AI provider + API key
  3. Copy embed code to your website

Meta Channels (WhatsApp / FB / IG)

  1. Create Meta App at developers.facebook.com
  2. Unified Messaging → Channels → Add Channel
  3. Enter App ID, App Secret (required for webhook HMAC), Access Token, Page/Phone IDs
  4. Set webhook URL: {crm_url}/unified_messaging/unified_messaging_webhook/receive/{channel_id}
  5. Use the channel's Verify Token from channel settings

SLA & CSAT

  1. Unified Messaging → Settings
  2. Set first-response SLA minutes (default 15)
  3. Enable CSAT and customize the survey question
  4. Surveys are sent automatically when a conversation is marked resolved

Business Hours

  1. Unified Messaging → Settings → Business Hours
  2. Enable business hours, set start/end times and active days
  3. Customize the away message shown on the widget when outside hours
  4. Enable web chat and/or Meta channel away auto-replies

Widget Security

  • Allowed Domains: restrict which sites can use the widget
  • Rate Limit: max requests/minute per IP (default 30)
  • Max Message Length: default 2000 chars

Cron

Ensure BIXCRM cron runs — processes:

  • AI reply queue
  • Failed send retries
  • SLA breach checks
  • Offline session cleanup
  • Auto-resolve stale conversations (+ CSAT survey)

API Endpoints (Admin)

EndpointMethodDescription
-------------------------------
conversationsGETList conversations (filters: assigned, starred, tag, etc.)
conversation/{id}GET/POSTView/update conversation (status, assign, tags, star)
sendPOSTSend text message
send_mediaPOSTSend image/video/PDF (multipart file)
search_crmGETSearch leads/customers for manual CRM link
create_leadPOSTCreate CRM lead from contact
create_ticketPOSTCreate support ticket
send_templatePOSTSend WhatsApp template (optional components JSON)
analyticsGETMessage analytics + CSAT + SLA + agent performance
streamGETSSE real-time updates (inbox)
export_conversationsGETCSV export (filtered)
export_ai_insightsGETCSV export of AI insights (days param)
export_conversation/{id}GETSingle conversation transcript CSV
schedule_sendPOSTSchedule outbound message (conversation_id, body, scheduled_at)
snoozePOSTSnooze/unsnooze conversation (conversation_id, preset or until)
add_notePOSTAdd internal note
resume_aiPOSTResume AI after handoff (conversation_id)
send_catalog_product_listPOSTSend WhatsApp multi-product list
bulk_updatePOSTBulk status/assign/mark read/archive
merge_conversationsPOSTMerge source conversations into target (target_id, source_ids)
block_contactPOSTBlock contact from conversation (conversation_id, optional reason)
meta_templatesGETSynced Meta templates + catalog products for channel
send_catalog_productPOSTSend WhatsApp catalog product (conversation_id, product_id)
link_crmPOSTLink contact to CRM

Real-Time Updates

When um_realtime_mode is set to SSE (default), the inbox uses Server-Sent Events. Choose WebSocket (Pusher/Soketi) for lower-latency push via a Pusher-compatible broker, or Polling only to disable push streams.

WebSocket (Pusher / Soketi)

  1. Unified Messaging → Settings → Real-time inbox mode → WebSocket
  2. Enter Pusher App ID, Key, Secret (or Soketi credentials)
  3. For self-hosted Soketi/Reverb: set custom host + port (default 6001)
  4. Ensure your WebSocket server is reachable from staff browsers and the CRM server can POST events to it

Changelog

v3.8.0 (Phase 13 — Operations Dashboard & Tag Automation)

  • Operations dashboard: webhook metrics, queue stats, team routing overview, staff workload
  • Daily inbound vs webhook failure chart with 7/30/90-day filter
  • Automation runs breakdown by trigger type (including tag added)
  • Automation tag_added event trigger when conversation tags change
  • Inbox Snoozed only filter (+ deep link from Operations)
  • System Health DB version check updated for migration 380

v3.7.0 (Phase 12 — Webhook Reliability & Event Automation)

  • Webhook failure queue: failed Meta payloads stored for cron auto-retry (3 attempts) or manual replay
  • Webhook Failures admin page + System Health pending count
  • Automation event triggers: conversation resolved, SLA breach, no staff reply
  • Trigger type selector on automation rules with deduplicated event firing
  • Cron evaluates no-reply rules for conversations waiting on inbound messages

v3.6.0 (Phase 11 — Agent Workflow & Automation Completion)

  • Automation logs: date/rule/action filters, pagination, CSV export
  • Quick replies: channel filter on create/edit, merge tags {contact_name} {staff_name} {channel_name}, inbox bar filtered by channel
  • Conversation snooze (1h / 4h / tomorrow) with cron wake-up notification
  • Scheduled outbound messages: compose scheduler, admin list, cron processor
  • Per-channel AI prompt and custom context overrides
  • Global default team + assignment method on Settings page
  • Automation assign_staff accepts round_robin and load_balance

v3.5.0 (Phase 10 — Automation Logs & Exports)

  • Automation execution log (um_automation_logs) with logs UI and 30-day stats on rules page
  • New automation actions: pause AI, trigger handoff, notify staff
  • AI Insights CSV export from Analytics page
  • Single conversation transcript CSV export from inbox chat header
  • System Health DB version check updated for migration 350

v3.4.0 (Phase 9 — AI Insights & WhatsApp Flow UI)

  • AI Insights section on Analytics: handoffs, sentiment alerts, bot flows, token charts
  • Sentiment distribution bar chart and AI actions breakdown
  • WhatsApp Flow responses rendered as structured tables in inbox
  • WhatsApp Order messages shown with line items in inbox
  • Fixed appendMessages receipt render bug

v3.3.0 (Phase 8 — WebSocket Real-Time)

  • Real-time mode selector: SSE, WebSocket (Pusher/Soketi), or polling only
  • Pusher-protocol broadcast on new messages (private-um-inbox channel)
  • Private channel auth endpoint for staff inbox permission
  • Inbox auto-fallback to polling if WebSocket connection fails
  • System Health shows WebSocket configuration status

v3.2.0 (Phase 7 — Operations & SLA)

  • Channel-specific SLA escalation steps UI (per-channel override with reset to global)
  • Global SLA escalation editor: add/remove steps dynamically
  • System Health diagnostics page (AI, embeddings, queue, cron hints)
  • One-click embedding API test from health page
  • Channel delete cleans up custom SLA steps

v3.1.1 — Multi-provider embeddings

  • Per-provider embedding URLs and default models: OpenAI, OpenRouter, Together, Custom
  • Embedding provider setting (Auto or explicit) with fallback when chat provider has no embeddings API (DeepSeek, Groq)
  • Settings UI shows embedding status and provider-specific hints

v3.1.0 (Phase 6 — Advanced Enterprise)

  • Vector embedding RAG: chunked knowledge + cosine similarity search
  • Reindex embeddings action on AI Knowledge Base page
  • AI/hybrid sentiment classification (configurable mode)
  • Inbox filters: sentiment label + AI paused only
  • WhatsApp multi-product list messages (catalog product_list)
  • Smart adaptive polling when SSE is disabled (tab visibility aware)

v3.0.0 (Phase 5 — Enterprise Polish)

  • Inbox sentiment + AI paused badges in list and chat header
  • Resume AI API and UI after human handoff
  • Bot flow collected answers in conversation detail panel
  • AI conversation summary moved to async cron queue
  • Knowledge base search uses keyword relevance scoring
  • Sentiment alert: assign specific staff member in settings
  • Analytics: estimated AI cost (configurable rate per 1K tokens)

v2.9.0 (Phase 4 — AI Enterprise)

  • AI Knowledge Base (RAG): FAQ entry + PDF/TXT document upload for AI context
  • Human handoff rules: trigger phrases pause AI, auto-assign staff, send confirmation
  • Conversation summary: AI-generated internal note on resolve
  • Sentiment detection: negative customer alerts for staff
  • Bot flow builder: greeting → questions → handoff (per channel or global)
  • AI usage analytics: token counts and AI-assisted resolution metrics
  • Enhanced Meta channel AI pipeline (sentiment, handoff, flows before cron queue)

v2.8.0 (Phase 3 — WhatsApp & Meta Enterprise)

  • Meta WhatsApp template catalog sync + preview UI
  • Inbox template picker from synced catalog with visual preview
  • Catalog product sync and send from inbox
  • WhatsApp Flow responses and order message handling
  • Instagram story reply/mention detection
  • Voice message audio player in inbox
  • Read receipt ticks (sent/delivered/read) on outbound messages

v2.7.0 (Phase 2 — Automation & Workflow)

  • Automation rules engine with inbound triggers
  • Multi-step SLA escalation configuration
  • Outgoing queue admin UI with manual retry
  • Block list management and inbox block action
  • Conversation merge (bulk + API)
  • WhatsApp 24-hour session badge and send guard
  • Per-channel business hours override

v2.6.0 (Phase 1 — Enterprise Foundation)

  • Setup Wizard (5-step guided onboarding)
  • Meta OAuth connect + automatic token refresh via cron
  • Activity Log / Audit viewer with CSV export
  • Granular permissions: Analytics, Audit, AI, Export
  • Channel Teams (per-channel staff assignment pool)
  • Load Balance assignment (fewest open conversations)
  • Improved ticket creation modal (department, priority, contact)
  • Complete Urdu language file

v2.5.0

  • Starred conversations (star toggle + filter)
  • My conversations / assigned staff filter
  • Manual CRM link picker (search leads & customers)
  • Outbound media send from inbox (JPEG, PNG, WebP, MP4, PDF)
  • Meta channel away auto-reply during business hours off-time
  • SSE toggle in Settings
  • Quick reply shortcut expansion (type /shortcut in compose)
  • Improved media rendering (video/file links in inbox)
  • Complete uninstall cleanup for all module tables

v2.4.0

  • Business hours settings with widget availability and away auto-reply
  • Bulk inbox actions: resolve, pending, open, assign, mark read, archive
  • Agent performance bar chart in analytics
  • Visual WhatsApp template parameter builder (syncs to components JSON)

v2.3.0

  • Per-channel SLA minutes and escalation staff on breach
  • Internal conversation notes (staff-only)
  • Conversation tags with inbox filter
  • WhatsApp template modal UI (name, language, components JSON)
  • CSV export for filtered conversations
  • Dashboard widget: SLA breaches + CSAT average

v2.2.0

  • SLA first-response timers with inbox badges and breach notifications
  • CSAT surveys on resolve (web chat + WhatsApp interactive buttons)
  • WhatsApp template components JSON support
  • Send retry duplicate message fix
  • Analytics: CSAT average and SLA breach counts

v2.1.0

  • Analytics dashboard with Chart.js (messages, channels, direction, status)
  • SSE real-time inbox updates
  • Helper unit tests for widget domain validation

v2.0.0

  • Security: webhook HMAC, widget rate limit, encrypted AI keys
  • Async AI queue via cron
  • Auto-assign, staff UI, CRM actions
  • Media, templates, retries, analytics

v1.3.0

  • Multi-provider free AI (DeepSeek, Groq, etc.)

v1.0.0

  • Initial release

Features

Unified inbox for Facebook, Instagram, WhatsApp and Web Chat in BIXCRM

  • Unified inbox with channel filters, staff assignment, CRM linking
  • Web chat widget with AI assistant (DeepSeek, Groq, OpenRouter, Together, OpenAI)
  • Meta webhook integration with HMAC signature validation
  • Async AI replies via cron queue
  • Auto-assign (round robin / default staff)
  • Media download for WhatsApp & Messenger
  • **Outbound media send** (image, video, PDF) from inbox
  • WhatsApp template message sending with optional components JSON
  • WhatsApp interactive button messages (CSAT)
  • Failed message retry queue (no duplicate rows on retry)
  • Widget rate limiting & domain allowlist
  • Encrypted AI API keys at rest
  • SLA first-response timers with breach alerts
  • CSAT surveys on conversation resolve
  • Analytics dashboard with CSAT and SLA metrics
  • SSE real-time inbox updates (toggle in Settings)
  • **WebSocket real-time** via Pusher / Soketi (optional alternative to SSE)
  • Business hours with away auto-reply (web chat + Meta channels)
  • Bulk inbox actions (status, assign, mark read, archive)
  • Agent performance analytics chart

Permissions

Granular staff capabilities are registered on activation. Assign them under Setup → Staff → Roles for the Unified Messaging capability group.

Typical capabilities include view, create, edit, delete, plus module-specific actions (approve, export, settings, API access).

Cron Jobs

Background tasks (if enabled) run through BIXCRM's main cron. Example crontab (every 5 minutes):

* * * * * php /path/to/bixcrm/index.php cron/index > /dev/null 2>&1

Check module settings for scheduled jobs (alerts, sync, reports, retention).

After activation — configuration checklist

  1. Go to Setup → Modules and activate Unified Messaging.
  2. If prompted, click Upgrade Database or reload admin — migrations run automatically.
  3. Assign permissions under Setup → Staff → Roles.
  4. Open the module menu and configure settings.
  5. BIXCRM 3.0+
  6. PHP 7.4+ (8.1+ recommended)
  7. MySQL 5.7+ / MariaDB 10.3+ (InnoDB)
  8. PHP extensions: mysqli, json, mbstring, curl, fileinfo

Staff permissions (from module)

Assign under Setup → Staff → Roles. Each feature can expose different actions:

FeatureActions
Unified Messaging Inbox
um_inbox		view, create, edit, delete
Unified Messaging Channels
um_channels		view, create, edit, delete
Unified Messaging Templates
um_templates		view, create, edit, delete
Unified Messaging Settings
um_settings		view, edit
Unified Messaging Analytics
um_analytics		view
Unified Messaging Audit Logs
um_audit		view, export
Unified Messaging AI Settings
um_ai		view, edit
Unified Messaging Export
um_export		view
Unified Messaging Automation
um_automation		view, create, edit, delete
Unified Messaging Outgoing Queue
um_queue		view, edit
Unified Messaging Block List
um_blocked		view, create, delete
Unified Messaging Meta Templates
um_meta_templates		view, edit

One-time setup (first time only)

  1. Setup → Modules → activate Unified Messaging.
  2. Setup → Staff → Roles → assign Unified Messaging permissions (view, create, edit, delete, approve, export, settings as needed).
  3. Open Unified Messaging → Settings and complete company defaults, prefixes, integrations, and notification options.
  4. Create master data (warehouses, products, templates, accounts, routes, etc.) before processing live transactions.
  5. Enable BIXCRM cron (php /path/to/bixcrm/index.php cron/index) for sync, retries, alerts, and scheduled jobs.
  6. Optionally enable REST API / webhooks in module settings if you integrate external systems.

BIXCRM Knowledge Base — usage guide generated from module README and documentation.

Did you find this article useful?