Feature: support bi-directional sms messaging using available gateways. (#1351)

Author: beesaferoot

docs/integrations-guide/textbee.md

@@ -35,6 +35,7 @@ TextBee allows you to use your own Android device as an SMS gateway, providing u
 3. Click **Generate API Key**
 4. Copy the API key - you'll need this for MPM configuration
 5. Note your **Device ID** from the dashboard or app
+6. (Optional) To enable incoming SMS, create a **Webhook Subscription** for the `MESSAGE_RECEIVED` event and copy the **Webhook Secret**
 
 ## Step 4: Enable TextBee Plugin in MPM
 
@@ -51,9 +52,21 @@ TextBee allows you to use your own Android device as an SMS gateway, providing u
 3. Enter the following credentials:
    - **API Key**: Paste the API key from Step 3
    - **Device ID**: Enter your device ID from Step 3
+   - **Webhook Secret** (optional): Paste the webhook secret from Step 3 to enable incoming SMS
 4. Click **Save** to store the configuration
 5. The plugin will validate your credentials automatically
 
+### Incoming SMS (Optional)
+
+To receive incoming SMS from customers, you need to configure a webhook in the TextBee dashboard:
+
+1. In the TextBee dashboard, navigate to **Webhooks**
+2. Create a new webhook subscription for the `MESSAGE_RECEIVED` event
+3. Set the webhook URL to: `https://your-mpm-domain/api/textbee-sms-gateway/callback/{company-id}/incoming-messages`
+   - Replace `{company-id}` with your MPM company ID
+4. Copy the webhook secret and paste it in the MPM TextBee configuration
+5. Incoming SMS will now be stored and processed by MPM
+
 ## Step 6: Select TextBee as Your SMS Gateway
 
 1. Navigate to **Settings** → **Configuration** → **Main Settings**

docs/usage-guide/sms.md

@@ -34,6 +34,7 @@ TextBee allows you to use your own Android device as an SMS gateway, providing u
 
 - Up to 98% cost savings
 - Uses your own Android device
+- Bidirectional SMS (send and receive)
 - Free plan: 300 messages/month
 - Pro plan: 5,000 messages/month
 

src/backend/app/Events/SmsStoredEvent.php

@@ -2,6 +2,7 @@
 
 namespace App\Events;
 
+use App\Models\Sms;
 use Illuminate\Foundation\Events\Dispatchable;
 use Illuminate\Queue\SerializesModels;
 
@@ -11,8 +12,9 @@
  * Dispatch this event to asynchronously store an SMS.
  * A corresponding listener will send the event.
  *
- * @property string $sender  The sender of the SMS.
- * @property string $message The message content of the SMS.
+ * @property string   $sender  The sender of the SMS.
+ * @property string   $message The message content of the SMS.
+ * @property Sms|null $sms     The SMS model instance, if available.
  */
 class SmsStoredEvent {
     use Dispatchable;
@@ -21,5 +23,6 @@ class SmsStoredEvent {
     public function __construct(
         public string $sender,
         public string $message,
+        public ?Sms $sms = null,
     ) {}
 }

src/backend/app/Http/Controllers/SmsController.php

@@ -183,7 +183,7 @@ public function store(StoreSmsRequest $request): ApiResource {
         $sms = $this->smsService->createSms($smsData);
 
         match ($this->smsService->checkMessageType($message)) {
-            $this->smsService::FEEDBACK => event(new SmsStoredEvent($sender, $message)),
+            $this->smsService::FEEDBACK => event(new SmsStoredEvent($sender, $message, $sms)),
             $this->smsService::TICKET => $this->commentService->storeComment($sender, $message),
             default => new ApiResource($sms),
         };

src/backend/app/Plugins/AfricasTalking/Http/Controllers/AfricasTalkingCallbackController.php

@@ -29,15 +29,15 @@ public function incoming(Request $request): JsonResponse {
         $senderId = $sender ? $sender->id : null;
 
         $smsData = [
-            'receiver' => $phoneNumber,
+            'receiver' => $address->phone ?? $phoneNumber,
             'body' => $message,
             'sender_id' => $senderId,
             'direction' => Sms::DIRECTION_INCOMING,
             'status' => Sms::STATUS_DELIVERED,
         ];
 
-        $this->smsService->createSms($smsData);
-        event(new SmsStoredEvent($phoneNumber, $message));
+        $sms = $this->smsService->createSms($smsData);
+        event(new SmsStoredEvent($phoneNumber, $message, $sms));
 
         return response()->json(['status' => 'success']);
     }

src/backend/app/Plugins/AfricasTalking/Listeners/SmsListener.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace App\Plugins\AfricasTalking\Listeners;
+
+use App\Events\SmsStoredEvent;
+use App\Listeners\SmsListener as GlobalSmsListener;
+use App\Models\MpmPlugin;
+use App\Services\MainSettingsService;
+
+class SmsListener {
+    public function __construct(
+        private GlobalSmsListener $globalSmsListener,
+        private MainSettingsService $mainSettingsService,
+    ) {}
+
+    public function handle(SmsStoredEvent $event): void {
+        $mainSettings = $this->mainSettingsService->getAll()->first();
+
+        if ($mainSettings?->sms_gateway_id !== MpmPlugin::AFRICAS_TALKING) {
+            return;
+        }
+
+        $this->globalSmsListener->handle($event);
+    }
+}

src/backend/app/Plugins/AfricasTalking/Providers/EventServiceProvider.php

@@ -2,9 +2,15 @@
 
 namespace App\Plugins\AfricasTalking\Providers;
 
+use App\Events\SmsStoredEvent;
+use App\Plugins\AfricasTalking\Listeners\SmsListener;
 use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
 
 class EventServiceProvider extends ServiceProvider {
+    protected $listen = [
+        SmsStoredEvent::class => [SmsListener::class],
+    ];
+
     /**
      * Register any events for your application.
      */

src/backend/app/Plugins/SparkMeter/Listeners/SmsListener.php

@@ -2,7 +2,7 @@
 
 namespace App\Plugins\SparkMeter\Listeners;
 
-use App\Models\Meter\Meter;
+use App\Events\SmsStoredEvent;
 use App\Plugins\SparkMeter\Exceptions\SparkAPIResponseException;
 use App\Plugins\SparkMeter\Models\SmCustomer;
 use App\Plugins\SparkMeter\Services\CustomerService;
@@ -56,8 +56,7 @@ public function onSmsStored(string $sender, string $message): void {
         }
     }
 
-    public function handle(string $sender, string $message): void {
-        // TODO: Uncomment this when spark-meter package is refactored with device->meter approach
-        // $this->onSmsStored($sender, $message);
+    public function handle(SmsStoredEvent $event): void {
+        $this->onSmsStored($event->sender, $event->message);
     }
 }

src/backend/app/Plugins/SparkMeter/Services/CustomerService.php

@@ -529,7 +529,7 @@ static function ($q) use ($phoneNumber) {
 
         return $this->smCustomer->newQuery()->with(['site', 'mpmPerson.devices.device'])->where(
             'mpm_customer_id',
-            $person->id
+            $person?->id
         )->first();
     }
 }

src/backend/app/Plugins/SteamaMeter/Listeners/SmsListener.php

@@ -2,6 +2,7 @@
 
 namespace App\Plugins\SteamaMeter\Listeners;
 
+use App\Events\SmsStoredEvent;
 use App\Plugins\SteamaMeter\Models\SteamaCustomer;
 use App\Plugins\SteamaMeter\Services\SteamaCustomerService;
 use App\Plugins\SteamaMeter\Services\SteamaSmsFeedbackWordService;
@@ -35,8 +36,7 @@ public function onSmsStored(string $sender, string $message): void {
         }
     }
 
-    public function handle(string $sender, string $message): void {
-        // TODO: Uncomment this when steamaco-meter package is refactored with device->meter approach
-        // $this->onSmsStored($sender, $message);
+    public function handle(SmsStoredEvent $event): void {
+        $this->onSmsStored($event->sender, $event->message);
     }
 }