Skip to main content

Troubleshooting & FAQ

This page covers common issues and how to resolve them when working with PulseChat.

1. Chat Doesn't Appear in Sidebarโ€‹

Symptoms:

  • No "Chat" menu item in the admin sidebar.

Checks:

  1. Module enabled?

    • Go to Setup > Modules.
    • Ensure PulseChat is Active.

  2. Staff permissions?

    • Your role must have the view capability for PulseChat.
    • Check Setup > Staff > Roles and confirm:
      • view under PulseChat is enabled for your role.

  3. PulseChat enabled option?

    • In PulseChat settings, ensure:
      • pulsechat_enabled is set to Yes.

2. Transport Issues (Messages Slow or Not Real-Time)โ€‹

Symptoms:

  • Messages appear only after page refresh or with delays.
  • Typing indicators / read receipts are inconsistent.

Checks:

  1. Look at the transport bar at the top of the chat:

    • "Pusher WebSockets -- instant delivery" (blue) or
    • "Built-in Polling -- messages refresh every ~3s" (green).

  2. If using Pusher:

    • Confirm Pusher credentials (App ID/Key/Secret/Cluster) in Perfex settings.
    • Ensure firewall is not blocking pusher.com.
    • Check Pusher dashboard for errors or connection limits.

  3. If using Polling:

    • Some delay (a few seconds) is normal; this is expected behavior.

  4. To switch transport:

    • Go to PulseChat Settings > Real-time Transport.
    • Choose pusher, polling, or auto.
    • Save and reload the chat page.

3. Files Won't Uploadโ€‹

Symptoms:

  • Upload fails silently or with an error.

Checks:

  1. Allowed file types

    • Ensure the extension is allowed in pulsechat_allowed_file_types.

  2. Max size

    • File size must be within the pulsechat_max_file_size_mb limit.

  3. Permissions

    • Verify modules/pulsechat/uploads/ is writable.

  4. Error logs

    • Check Perfex logs and server error logs for upload-related messages.

4. Clients Can't See or Use Chatโ€‹

Symptoms:

  • Staff can use PulseChat; clients cannot see any chat widget.

Checks:

  1. Client chat enabled?

    • Ensure pulsechat_clients_enabled is set to Yes in settings.

  2. Client portal hooks

    • PulseChat injects a widget into the client portal via init_chat.php.
    • Ensure there are no overrides or template customizations removing this.

  3. Permissions

    • Only logged-in contacts can use client chat; anonymous visitors won't see it.

5. Omnichannel Messages Not Arrivingโ€‹

Symptoms:

  • WhatsApp/Telegram/Email messages aren't appearing in Channels.

Checks:

  1. Omnichannel enabled?

    • pulsechat_channels_enabled = Yes.

  2. Channel config

    • For each channel type:
      • WhatsApp: token, phone ID, webhook URL configured in Meta.
      • Telegram: bot token and webhook URL configured via BotFather.
      • Email: IMAP settings correct, SSL/ports correct, credentials valid.

  3. Webhooks

    • Confirm provider webhooks are pointing to your ChannelWebhook/webhook.php endpoint.
    • Check logs for failed signature verifications.

  4. Email polling

    • Ensure Perfex cron is running.
    • pulsechat_cron_email_poll will not run without after_cron_run.

6. AI Buttons Not Workingโ€‹

Symptoms:

  • AI toolbar is visible but:
    • Clicking Draft/Suggest/Rewrite/Translate does nothing, or
    • Toasts show "AI not configured" or HTTP errors.

Checks:

  1. Settings

    • pulsechat_ai_enabled = Yes.
    • Provider selected (openai or anthropic).
    • Correct API key entered for the selected provider.
    • AI feature toggles (Auto-Reply, Suggestions, Rewrite, Translate, Sentiment) enabled as desired.

  2. Network

    • Ensure your server can reach:
      • https://api.openai.com
      • https://api.anthropic.com
    • Check for firewall/proxy blocks or DNS issues.

  3. Error text

    • Many errors return:
      • "OpenAI API key not configured."
      • "Text is required."
      • HTTP status with provider error message.

  4. AI logs

    • Look at pc_ai_logs for more details:
      • action_type, model, error (if captured), token counts.

7. Database Errors (Undefined Constants)โ€‹

Symptoms:

  • Errors like "Undefined constant TABLE_PC_MESSAGES".

Checks:

  1. Ensure the latest PulseChat code is deployed:
    • pulsechat.php defines TABLE_PC_* constants.
  2. Fallbacks in Pulsechat_model:
    • The model defines core table constants if they're not already defined.
  3. If you still see this:
    • Confirm there aren't duplicate/old copies of the module in other paths.

8. Still Stuck?โ€‹

If you've tried the above and still can't resolve the issue:

  1. Collect:
    • Exact error messages.
    • Relevant logs (PHP error logs, Perfex logs).
    • Screenshots of the relevant settings screens.
  2. Contact support with:
    • Your Perfex version.
    • PulseChat version.
    • Any customization you've done (override views, modified code, etc.).

This information will make it much easier to diagnose and fix the problem quickly.