Feature/mms support foundation

README.md

@@ -203,6 +203,37 @@ This mode is ideal for sending messages from a local network.
       send --phones '+19162255887,+19162255888' 'Hello, doctors!'
     ```
 
+6. To enqueue an MMS message using JSON (text + media metadata):
+
+    ```sh
+    curl -X POST -u <username>:<password> \
+      -H "Content-Type: application/json" \
+      -d '{
+        "phoneNumbers": ["+19162255887"],
+        "mmsMessage": {
+          "text": "Hello with media",
+          "attachments": [
+            {
+              "mimeType": "image/jpeg",
+              "filename": "photo.jpg",
+              "data": "<base64-encoded-bytes>"
+            }
+          ]
+        }
+      }' \
+      http://<device_local_ip>:8080/message
+    ```
+
+7. To enqueue an MMS message using multipart/form-data:
+
+    ```sh
+    curl -X POST -u <username>:<password> \
+      -F "phoneNumbers=+19162255887" \
+      -F "text=Hello with image" \
+      -F "file=@/path/to/photo.jpg;type=image/jpeg" \
+      http://<device_local_ip>:8080/message
+    ```
+
 ### Cloud Server
 
 <div align="center">
@@ -264,6 +295,34 @@ Follow these steps to set up webhooks:
     }
     ```
 
+   Incoming MMS webhooks use the `mms:received` event and include media metadata:
+
+    ```json
+    {
+      "event": "mms:received",
+      "payload": {
+        "messageId": "mms_123",
+        "transactionId": "tx_123",
+        "phoneNumber": "+19162255887",
+        "attachments": [
+          {
+            "id": "part_1",
+            "mimeType": "image/jpeg",
+            "filename": "photo.jpg",
+            "size": 2048,
+            "width": 800,
+            "height": 600,
+            "durationMs": null,
+            "sha256": "<sha256>",
+            "downloadUrl": "/media/part_1?expires=<timestamp>&token=<signature>"
+          }
+        ]
+      }
+    }
+    ```
+
+   Use the signed `downloadUrl` path with basic auth credentials to fetch stored media.
+
 5. To deregister a webhook, execute a `curl` request using the following pattern:
 
     ```sh
@@ -275,6 +334,10 @@ For cloud mode the process is similar, simply change the URL to https://api.sms-
 
 *Note*: Webhooks are transmitted directly from the device; therefore, the device must have an outgoing internet connection. As the requests originate from the device, incoming messages remain inaccessible to us.
 
+*Known MMS limitation*: MMS transmission depends on carrier APN/mobile-data configuration and OEM telephony behavior; when delivery fails, API/message states report platform MMS error codes (e.g. invalid APN, network, HTTP, or retry-required).
+
+*Carrier troubleshooting note (Phonero / Norway / Pixel)*: if MMS delivery fails on Pixel devices, ensure mobile data is enabled for the SIM used to send messages, reset APN settings to carrier defaults, reboot the phone, and verify MMS/APN values with Phonero support (Phonero uses Telenor network infrastructure).
+
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 

app/build.gradle

@@ -115,6 +115,7 @@ dependencies {
     implementation 'androidx.preference:preference-ktx:1.2.1'
 
     implementation("com.aventrix.jnanoid:jnanoid:2.0.0")
+    implementation("com.klinkerapps:android-smsmms:5.2.6")
 
     implementation("androidx.room:room-ktx:$room_version")
     annotationProcessor("androidx.room:room-compiler:$room_version")
@@ -132,4 +133,4 @@ dependencies {
     testImplementation("junit:junit:4.13.2")
     androidTestImplementation("androidx.test.ext:junit:1.1.3")
     androidTestImplementation("androidx.test.espresso:espresso-core:3.4.0")
-}
+}