Masafah SMS Integration for Odoo

Summary

This module integrates the Masafah SMS provider (client.almasafa.ly) with Odoo. It allows you to configure your Masafah account within Odoo and use it as your default SMS provider, routing messages through Masafah's API instead of Odoo's default IAP SMS service.

Description

The Masafah SMS Integration module overrides Odoo's standard SMS sending mechanism. By configuring and setting a Masafah account as the 'Default SMS Provider', all outgoing SMS messages (sent individually or via mass mailing/batch features) will be sent using your Masafah credentials and credit balance. If no default Masafah account is active, Odoo will revert to its standard SMS sending behaviour (typically using IAP credits).

Key Features

• Direct Masafah Integration: Send SMS via the official Masafah API.
• Default Provider Override: Seamlessly replaces Odoo's IAP SMS when configured as default.
• Single & Batch Sending: Handles both individual SMS and Odoo's batch/mass SMS features (sending one-by-one via API).
• Account Management: Configure and store credentials for one or more Masafah accounts.
• Balance Check: View your current Masafah balance (package, spent, remaining) directly within the account configuration in Odoo.
• Connection Testing: Verify API credentials and connectivity.
• IAP Fallback: Odoo's standard SMS sending is used if no default Masafah account is set.

Dependencies

• Odoo Modules: iap, sms, phone_validation
• Python Libraries: requests (usually included with Odoo)

Installation

1. Download: Obtain the masafah_sms module folder.
2. Place in Addons: Copy the masafah_sms folder into your Odoo custom addons directory.
3. Update Apps List: Restart Odoo, activate developer mode, and go to Apps -> Update Apps List.
4. Install: Search for "Masafah SMS Integration" and click "Install".

Configuration

Configure your Masafah SMS account details within Odoo:

1. Navigate to Settings → Technical → Masafah SMS.
   (Alternative path based on menu structure: Settings → General Settings → Masafah SMS)
   
2. Click Create to add a new account configuration.
   
3. Fill in the required details:
   • Account Name: A recognizable name (e.g., "Masafah Main Account").
   • API Username: Your Masafah API username.
   • API Password: Your Masafah API password.
   • Sender ID: The Sender ID approved for your Masafah account.
   • Authentication URL: The Masafah API endpoint for authentication (defaults provided).
   • SMS API URL: The Masafah API endpoint for sending SMS (defaults provided).
   • Balance API URL: The Masafah API endpoint for checking balance (defaults provided).
   • Default SMS Provider: Crucially, check this box to make this account the active provider for sending SMS. Only one account should be marked as default.
4. Test Connection: Click the Test Authentication button to verify your Username/Password and Auth URL.
5. Check Balance:
   • The Account Balance section displays the last checked balance details (Package, Spent, Balance) and the time of the check.
   • Click the Refresh Balance button (🔄 icon) next to the balance display to fetch the latest balance information from Masafah.
6. Save the configuration.

Usage

• Automatic Sending: Once a Masafah account is saved and marked as the Default SMS Provider, any SMS sent from Odoo (e.g., via Contact form, Sales Order confirmation, SMS Marketing app) will automatically use this account.
  
• Balance Monitoring: Periodically check the balance on the configuration screen using the Refresh Balance button to ensure sufficient credits.
• Logs: Sent message history and status can be viewed in the standard Odoo Settings -> Technical -> Email -> SMS Messages menu.

Important Notes

• The Masafah API used by this module sends messages one recipient at a time. Therefore, even when using Odoo's batch sending features, the module will make individual API calls for each recipient in the batch.
• Ensure your Masafah account has sufficient balance and is active.

Technical Details

• The module defines a masafah.sms.account model inheriting from iap.account to store credentials and manage the connection.
• It implements the necessary methods (_send_sms, _send_sms_batch) required by Odoo's SMS framework (leveraging iap.account features) to route messages through the configured default Masafah account.
• API communication uses the requests Python library. Error handling and logging are included for troubleshooting.