[features] add article dedicated to multi-SIM support

docs/faq/general.md

@@ -2,19 +2,7 @@
 
 ## How can I send an SMS using the second SIM card?
 
-To send an SMS using a non-default SIM card, you can specify the SIM card slot number in the `simNumber` field of request. For instance, the following request will send an SMS using the second SIM card:
-
-```sh
-curl -X POST \
-    -u <username>:<password> \
-    -H 'content-type: application/json' \
-    https://api.sms-gate.app/3rdparty/v1/message \
-    -d '{
-        "message": "Hello from SIM2",
-        "phoneNumbers": ["79990001234"],
-        "simNumber": 2
-    }'
-```
+Please refer to the [Multi-SIM Support](../features/multi-sim.md#webhooks) feature documentation.
 
 ## Does the app require power saving mode to be turned off to function without interruptions?
 
@@ -59,17 +47,23 @@ Yes, starting from [1.6.1](https://github.com/capcom6/android-sms-gateway/releas
 
 ## How can I avoid mobile operator restrictions?
 
-The application provides two features to help you avoid mobile operator restrictions:
+The application provides several features to help you avoid mobile operator restrictions:
 
 ### Random delay between messages
 
-You can introduce a random delay between messages by specifying a minimum and maximum delay time. The application will then randomly select a delay within this range for each message sent. This helps to reduce the likelihood of messages being flagged as spam by simulating a more human-like sending pattern. This option is available in the "Messages" section of the device's settings and is named "Delay between messages".
+You can introduce a random delay between messages by specifying a minimum and maximum delay time. The application will then randomly select a delay within this range for each message sent. This helps to reduce the likelihood of messages being flagged as spam by simulating a more human-like sending pattern. This option is available in the "Messages" section of the app's settings and is named "Delay between messages".
 
 It's important to note that this delay is applied only to individual messages, not for recipients in a single message. When you send a message to multiple recipients, the delay is not applied between each recipient of that message.
 
 ### Limiting the number of messages sent per period
 
-The app offers a feature to restrict the number of messages sent within a specified period—be it a minute, hour, or day. You can find this option under the "Limits" section in the device settings. When the limit is reached, the app will pause sending messages until the limit period resets. It's important to note that this feature should not be used for time-sensitive messages, such as sending authorization codes, where delays could cause issues.
+The app offers a feature to restrict the number of messages sent within a specified period—be it a minute, hour, or day. You can find this option under the "Limits" section in the "Messages" section of the app's settings. When the limit is reached, the app will pause sending messages until the limit period resets. It's important to note that this feature should not be used for time-sensitive messages, such as sending authorization codes, where delays could cause issues.
+
+### SIM rotation
+
+For devices with multiple SIM cards, the application supports SIM rotation to distribute the load across different mobile operators. This feature helps avoid reaching sending limits on a single SIM card and reduces the risk of being flagged for high-volume sending. Please refer to [Multi-SIM Support](../features/multi-sim.md#sim-card-rotation) for more information.
+
+By combining these features—random delays, message limits, and SIM rotation—you can significantly reduce the risk of triggering mobile operator restrictions while maintaining efficient message delivery.
 
 ## How to hide messages on device?
 

docs/features/multi-sim.md

@@ -0,0 +1,51 @@
+# Multi-SIM Support
+
+The app offers the following features to support devices with multiple SIM cards:
+
+* **Sending API**: Select the specific SIM card for sending SMS messages in your API requests.
+* **Webhooks**: Receive SIM card information for incoming messages.
+* **Rotation**: Utilize a feature to rotate between multiple SIM cards.
+
+## Sending API
+
+To send an SMS using a specific SIM card, provide the SIM card slot number in the `simNumber` field of your request. For example, the following request will send an SMS using the second SIM card:
+
+```sh
+curl -X POST \
+    -u <username>:<password> \
+    -H 'Content-Type: application/json' \
+    https://api.sms-gate.app/3rdparty/v1/message \
+    -d '{
+        "message": "Hello from SIM2, Dr. Turk!",
+        "phoneNumbers": ["+19162255887"],
+        "simNumber": 2
+    }'
+```
+
+## Webhooks
+
+To receive SMS messages, use the [Webhooks](./webhooks.md) feature. The `sms:received` event payload includes a `simNumber` field to identify which SIM card received the message.
+
+## SIM Card Rotation
+
+<div align="center">
+    <img src="/assets/features-sim-rotation.png" alt="SIM rotation option">
+</div>
+
+When the `simNumber` is not specified in the request, you can configure which SIM card will be used to send messages on the device. This option is located in the "Settings" tab under the "Messages" section.
+
+Available options:
+
+* **OS Default**: The app will not select any SIM card, delegating this to the default messaging app.
+* **Round Robin**: The app will rotate between SIM cards in a round-robin fashion.
+* **Random**: The app will select a SIM card at random for each message.
+
+## Troubleshooting
+
+If you encounter issues with multi-SIM functionality:
+
+1. Ensure that your device supports multiple SIM cards and that they are properly installed.
+2. Verify that the app has the necessary permissions to access and use all SIM cards.
+3. Check the app's logs for any error messages related to SIM card access or usage.
+
+For further assistance, please contact our [support team](mailto:[email protected]).

docs/index.md

@@ -15,7 +15,7 @@ SMS Gateway for Android turns your Android smartphone into an SMS gateway. It's
 - **Support for Android 5.0 and above:** The application is compatible with Android 5.0 and later versions.
 - **Message status tracking:** Monitor the status of sent messages in real-time.
 - **Automatic startup:** The application starts running as soon as your device boots up.
-- **Support for multiple SIM cards:** The application supports devices with multiple SIM cards.
+- **Support for multiple SIM cards:** The application supports devices with [multiple SIM cards](./features/multi-sim.md).
 - **Multipart messages:** The application supports sending long messages with auto-partitioning.
 - **End-to-end encryption:** The application provides end-to-end encryption by encrypting message content and recipients' phone numbers before sending them to the API and decrypting them on the device.
 - **Message expiration:** The application allows setting an expiration time for messages. Messages will not be sent if they have expired.

docs/installation.md

@@ -12,6 +12,7 @@ Grant the following permissions for full functionality:
 
 - **SEND_SMS**: Essential for sending SMS messages.
 - **READ_PHONE_STATE**: Allows SIM card selection, if utilized.
+- **RECEIVE_SMS**: Required for receiving SMS messages and sending `sms:received` webhook.
 
 ## Installing from APK
 

docs/integration/cli.md

@@ -54,7 +54,7 @@ smsgate send [options] 'Message content'
 | --------------------------- | ------------------------------------------------------------------------------------------ | ------------- | ----------------------- |
 | `--id`                      | Message ID, will be generated if not provided                                              | empty         | `zXDYfTmTVf3iMd16zzdBj` |
 | `--phone`, `--phones`, `-p` | Phone number, can be used multiple times or with comma-separated values                    | **required**  | `+19162255887`          |
-| `--sim`                     | SIM card slot number, if empty, the default SIM card will be used                          | empty         | `2`                     |
+| `--sim`                     | SIM card slot number, if empty, the device's SIM rotation option will be used              | empty         | `2`                     |
 | `--ttl`                     | Time-to-live (TTL), if empty, the message will not expire<br>Conflicts with `--validUntil` | empty         | `1h30m`                 |
 | `--validUntil`              | Valid until, if empty, the message will not expire<br>Conflicts with `--ttl`               | empty         | `2024-12-31T23:59:59Z`  |
 

mkdocs.yml

@@ -43,8 +43,9 @@ nav:
       - API: integration/api.md
       - Webhooks: features/webhooks.md
   - Features:
-      - Logging: features/logging.md
+      - Multi-SIM Support: features/multi-sim.md
       - Webhooks: features/webhooks.md
+      - Logging: features/logging.md
   - Pricing: pricing.md
   - Privacy:
       - Policy: privacy/policy.md