Support & Troubleshooting: Triage, Routing & Escalation
This guide provides a structured approach to diagnosing and resolving common issues across all CRM modules. When something goes wrong, a methodical triage process saves time and prevents guesswork. Follow the first-checks protocol before raising an escalation — most issues can be resolved at the first-line support level without requiring developer involvement.
Important Policy Reminder: Never delete records, force-clear statuses, or modify database entries directly to resolve issues. Always use the correct system workflow to correct state. Data deletions to fix process errors break audit trails, financial records, and reporting accuracy.
First 5 Checks for Any Issue
- Confirm the user's role and permissions for the relevant module
- Confirm the required module is enabled under Setup > Modules
- Confirm date, time, and timezone settings are consistent across the account
- Confirm all gateway or integration credentials (SMTP, SMS, payment) are valid
- Reproduce the issue once with a test record and capture a screenshot before escalating
Issue Routing Matrix
Use this matrix to identify the correct first-check and escalation path for any reported issue. Always complete the first-check steps yourself before escalating.
| Issue Type | Check First | Likely Cause | Escalate To |
|---|---|---|---|
| Lead creation failing | Role permission for Create Leads | Permission not granted or required fields missing | CRM Admin |
| Lead conversion failing | Required fields on lead profile | Missing email, name, or required field | CRM Admin |
| SMS not delivering | SMS gateway credentials + E.164 phone format | API key expired, balance depleted, or invalid number format | System Admin |
| Email not delivering or bouncing | SMTP credentials + SPF/DKIM DNS records | Authentication error or domain reputation issue | System Admin |
| Appointment slots not available | Provider schedule + holiday/blackout dates | Working hours not set or blackout date blocking | Operations Manager |
| Appointment reminder not sent | Gateway config + client contact details | Gateway misconfigured or missing phone/email on client profile | System Admin |
| Payment failing or not recorded | Gateway mode (test vs live) + webhook config | Test keys active in live mode, or webhook not receiving callbacks | Finance Admin |
| Invoice status not updating after payment | Payment gateway webhook URL and secret | Webhook failed to reach CRM or secret mismatch | Finance Admin |
| Social leads not appearing in CRM | Webhook verification + token validity | OAuth token expired or webhook URL changed | Integration Owner |
| Chatbot not capturing lead data | Field mapping in chatbot flow builder | Mapping not saved or required field missing from flow | CRM Admin |
| Report showing empty or wrong data | Date filters, status filters, permissions | Filters too narrow or draft records excluded | CRM Admin |
| Form submissions not creating records | Form destination mapping configuration | Mapping not saved or required CRM field missing from mapping | CRM Admin |
Escalation Protocol
If the first-check steps do not resolve the issue, escalate using this protocol:
- Document the issue: Record the exact error message or behaviour, the steps taken before it occurred, the user role affected, the module involved, and any screenshots or log entries. Vague escalations waste resolution time.
- Identify the escalation owner: Use the routing matrix above to identify who should receive the escalation. Route to CRM Admin for permissions, configuration, and data issues. Route to System Admin for gateway, server, or integration issues. Route to Finance Admin for payment, invoice, or refund issues.
- Set a severity level: Define severity based on business impact:
- Critical: Production payments failing, all users locked out, data loss occurring — resolve immediately.
- High: A key workflow is broken for multiple users (e.g. SMS failing for all sends) — resolve within 2 hours.
- Medium: A workflow is degraded but a workaround exists — resolve within same business day.
- Low: Minor display issue or non-critical configuration question — resolve within 48 hours.
- Apply the fix and test: The escalation owner applies the resolution. Confirm the fix works end-to-end using a test record that reproduces the original issue. Do not close the escalation based only on the fix being applied — verify the outcome.
- Document the resolution: Record what was found, what was changed, and how it was verified. Update the settings change log if a configuration change was made.
Self-Service Diagnostics by Module
Leads
- Cannot create: Check Leads: Create permission on your role.
- Cannot convert: Ensure all required fields are filled on the lead profile.
- Follow-up not reminding: Verify lead follow-up automation is active and cron is running.
Communications (SMS/Email)
- SMS failing: Validate E.164 phone format and API key balance. Check gateway logs.
- Email bouncing: Run SPF/DKIM check on your sending domain. Review SMTP error codes in the delivery log.
- Merge tags blank: Confirm source fields are populated on recipient records before sending.
Appointments
- No available slots: Check provider working hours and holiday dates.
- Wrong time shown: Align account and server timezone settings.
- Reminder not sent: Test notification gateway and confirm client has valid contact details.
Invoices & Payments
- Invoice not delivered: Verify billing email and SMTP settings.
- Payment not linking: Check gateway webhook URL and secret.
- Refund unavailable: Confirm payment is in a refundable state and you have the required permission.
Intake Forms
- Submissions not appearing: Confirm form is published and the correct URL was shared.
- No CRM record created: Review and save destination field mapping in form settings.
Social & Chatbot
- No leads from social: Re-verify webhook and re-authorise the channel integration.
- Chatbot not saving data: Check chatbot flow field mapping — ensure all nodes are saved.
Tip: For recurring issues, check whether a recent settings change or module update may have introduced the problem. Review the settings change log and compare the timeline of changes against when the issue first appeared. This is the fastest path to root-cause identification for post-change issues.