Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:This document outlines the key mechanisms and tools available for troubleshooting issues within the QashierWise backend. The system employs structured logging, custom exceptions, frontend error feedback, and dedicated testing scripts to diagnose and resolve problems related to WhatsApp API interactions, data validation, and webhook processing.
The primary areas for troubleshooting include API communication failures with Meta, validation errors during template management, and issues with receiving incoming WhatsApp messages. The tools described here are essential for developers to identify the root cause of failures, from configuration problems to unexpected API responses.
Logging
The application utilizes Laravel's configurable logging system to record events, errors, and debugging information. The primary configuration is located in config/logging.php.
Sources: config/logging.php, app/Services/TemplateService.php
Logging Configuration
The default logging channel is a stack that directs logs to a single daily log file. A separate channel is configured for deprecation notices.
| Channel Name | Driver | Path | Level |
|---|---|---|---|
stack | stack | - | debug |
single | single | storage/logs/laravel.log | debug |
daily | daily | storage/logs/laravel.log | debug |
deprecations | stack | - | debug |
null | monolog | - | debug |
Sources: config/logging.php:20-77
This diagram shows the flow of log messages from the application to the log file.
Sources: config/logging.php:20-77
Usage Examples
The TemplateService provides clear examples of how logging is used to trace operations and record failures. Informational logs are used for successful operations, while error logs capture detailed context when an API call fails.
Successful Operation Logging:
// app/Services/TemplateService.php:510-514
Log::info('Template created successfully', [
'template_id' => $responseData['id'] ?? null,
'name' => $data['name']
]);
Error Logging:
// app/Services/TemplateService.php:520-525
Log::error('Template creation failed', [
'name' => $data['name'],
'error' => $errorMessage,
'response' => $errorData
]);
This ensures that both successful and failed API interactions are recorded, providing a clear audit trail for debugging.
API Error Handling
The system has a robust error handling strategy for external API calls, particularly for interactions with the WhatsApp Business Management API. This involves structured backend responses and clear frontend feedback.
Backend Error Response
In services like TemplateService, API calls to external services are wrapped in try...catch blocks. When an error occurs (e.g., an HTTP client error or an exception), the service logs the detailed error and returns a standardized JSON object to the frontend.
This diagram illustrates the error handling flow within the TemplateService.
This ensures that the frontend always receives a predictable response format, whether the operation succeeded or failed.
Sources: app/Services/TemplateService.php:499-538
Frontend Error Display
The frontend, built with Alpine.js, is designed to consume the standardized error responses from the backend and display them to the user.
In the template management view, the templatesManager component has dedicated state variables for API errors, such as apiError, editApiError, and deleteApiError.
// resources/views/dashboard/templates.blade.php:1210-1212
// API Error Display
<div x-show="apiError" x-transition class="mb-4 p-3 bg-red-50 border border-red-200 rounded-lg">
<p class="text-sm text-red-600" x-text="apiError"></p>
</div>
When a backend call fails, the error message from the JSON response is assigned to one of these state variables, making it visible in the modal. This provides immediate, contextual feedback to the user. A similar pattern is used for the WhatsApp account connection page, where errors from the Facebook Embedded Signup flow are handled and displayed as toast notifications.
// resources/views/dashboard/whatsapp-account.blade.php:484-487
handleSignupError(errorData) {
this.connecting = false;
this.showToast(`Connection failed: ${errorData?.error_message || 'Unknown error'}`, 'error');
},
Sources: resources/views/dashboard/templates.blade.php:1198-1215, resources/views/dashboard/whatsapp-account.blade.php:483-488
Webhook Troubleshooting
To diagnose issues with receiving incoming WhatsApp messages, the test_webhook_message.php script provides a powerful local testing tool. It simulates a webhook event from Meta and sends it to the application's webhook endpoint.
Script Workflow
The script performs the following actions:
- Finds an Active Account: It queries the database for an active
WhatsAppAccountto use for the test. - Generates a Payload: It constructs a JSON payload that mimics a real incoming text message from a user.
- Sends a POST Request: It sends the payload to the local
/api/whatsapp/webhookendpoint. - Verifies Results: It checks the database to confirm that a new
WhatsAppContactandWhatsAppMessagehave been created. - Provides a Checklist: It outputs a checklist for deploying to a live environment.
This flowchart illustrates the script's execution path.
Sources: test_webhook_message.php
At the end of its execution, the script provides a helpful checklist for ensuring the production environment is correctly configured.
Checklist untuk Mode Live:
1. ☐ Pastikan webhook URL di Meta: https://api.qashierwise.com/api/whatsapp/webhook
2. ☐ Pastikan field 'messages' sudah di-subscribe di Meta webhook
3. ☐ Pastikan WHATSAPP_WEBHOOK_VERIFY_TOKEN di .env sama dengan di Meta
4. ☐ Pastikan App Mode di Meta sudah 'Live' (bukan Development)
5. ☐ Pastikan phone_number_id di database sama dengan yang di Meta
Sources: test_webhook_message.php:90-95
Custom Exceptions
The application defines custom exceptions to handle specific error scenarios gracefully. An example is WhatsAppTokenInvalidException.
This exception is likely thrown when the WhatsApp access token is missing or invalid, allowing a global exception handler to catch it and return a specific, user-friendly error message, potentially guiding the user to reconnect their account.
Sources: app/Exceptions/WhatsAppTokenInvalidException.php
Validation Logic
A common source of errors is invalid data submitted to the API. The TemplateService includes a comprehensive set of validation methods to catch these issues before making an external API call. This is a form of proactive troubleshooting.
The following validation rules are enforced for WhatsApp message templates:
| Field | Validation Rule | Error Message |
|---|---|---|
name | Required, must be ^[a-z0-9_]+$ | Template name is required or Template name can only contain lowercase letters, numbers, and underscores |
body | Required, max 1024 characters | Body text is required or Body text cannot exceed 1024 characters |
footer | Optional, max 60 characters | Footer text cannot exceed 60 characters |
buttons | Cannot mix QUICK_REPLY and CTA types | Cannot mix quick reply buttons with call-to-action buttons |
buttons | Max 10 QUICK_REPLY buttons | Maximum 10 quick reply buttons allowed |
buttons | Max 2 CTA (URL, PHONE_NUMBER) buttons | Maximum 2 call-to-action buttons allowed |
body variables | Should be sequential (e.g., {{1}}, {{2}}) | (Warning) Variable placeholders should be sequential... |
These rules are validated in the backend before any request is sent to Meta's API, providing fast and specific feedback. The robustness of this validation is ensured by property-based tests.
Sources: app/Services/TemplateService.php:50-280, tests/Unit/Services/TemplateServicePropertyTest.php