Skip to content

Commit 4819449

Browse files
capcom6capcom6
committed
[getting-started] refresh cloud server docs
1 parent dd0825b commit 4819449

File tree

4 files changed

+147
-33
lines changed

4 files changed

+147
-33
lines changed

‎docs/assets/cloud-server-arch.png

-60.5 KB
Binary file not shown.

‎docs/assets/features-ping-settings.png

4.68 KB
Loading

‎docs/features/sending-messages.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,13 +42,16 @@ Authorization: Basic <credentials>
4242

4343
## Message Processing Stages 🏗️
4444

45+
The steps apply to [Cloud](../getting-started/public-cloud-server.md) and [Private](../getting-started/private-server.md) modes. For [Local](../getting-started/local-server.md) mode, server-side step 2 is skipped.
46+
4547
1. **API Submission**
4648
The external app makes a `POST` request to the `/messages` endpoint.
4749

4850
2. **Server Processing**
4951
1. Validate payload.
5052
2. Add message to the queue.
51-
3. Provide messages to the device sorted by priority and enqueue time.
53+
3. Send a push notification to the device.
54+
4. Provide messages to the device, sorted by priority and enqueue time.
5255

5356
3. **Device Handling**
5457
1. Receive messages from the server.

‎docs/getting-started/public-cloud-server.md

Lines changed: 143 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,149 @@
1-
# Getting Started
2-
3-
## Cloud Server
4-
5-
<div align="center">
6-
<img src="/assets/cloud-server-arch.png" alt="Architecture of the Cloud Server mode">
7-
</div>
8-
9-
Use the cloud server mode when dealing with dynamic or shared device IP addresses. The best part? No registration, email, or phone number is required to start using it.
10-
11-
1. Launch the app on your device.
12-
2. Toggle the `Cloud Server` switch to the "on" position.
13-
3. Tap the `Online` button located at the bottom of the screen to connect to the cloud server.
14-
4. In the `Cloud Server` section, the credentials for basic authentication will be displayed.
15-
<div align="center">
16-
<img src="/assets/cloud-server.png" alt="Example settings for Cloud Server mode">
17-
</div>
18-
5. To send a message via the cloud server, perform a `curl` request with a command similar to the following, substituting `<username>` and `<password>` with the actual values obtained in step 4:
19-
20-
```sh
21-
curl -X POST -u <username>:<password> \
22-
-H "Content-Type: application/json" \
23-
-d '{ "message": "Hello, world!", "phoneNumbers": ["+79990001234", "+79995556677"] }' \
24-
https://api.sms-gate.app/3rdparty/v1/message
1+
# Getting Started 🚀
2+
3+
## Cloud Server ☁️
4+
5+
Use Cloud Server mode when your device has dynamic or shared IP addresses. Start immediately—no registration, email, or phone number required.
6+
7+
### Key Features ⚡
8+
9+
- 🌐 No registration required
10+
- 🔄 Hybrid push-pull architecture
11+
- ⏱️ Dynamic and shared device IP support
12+
- 🔒 Basic authentication
13+
14+
### Requirements ⚠️
15+
- Requires Google Play Services for push notifications
16+
- Needs active internet connection
17+
18+
### Message Flow 📨
19+
20+
```mermaid
21+
sequenceDiagram
22+
participant API
23+
participant Server
24+
participant FCM
25+
participant Device
26+
27+
API->>Server: POST /messages
28+
Server->>Server: Store in DB
29+
30+
par Push Notification Flow
31+
Server->>FCM: Send push notification
32+
FCM->>Device: Deliver FCM message
33+
Device->>Server: Get messages
34+
Server->>Device: Return messages
35+
and Scheduled Polling
36+
loop Every 15 minutes
37+
Device->>Server: Get messages (polling)
38+
Server->>Device: Return messages
39+
end
40+
end
41+
42+
Device->>Device: Process SMS
43+
Device->>Server: Report message status
44+
Server->>API: Webhook notification (optional)
45+
```
46+
47+
=== "Push Notification 🔔"
48+
```mermaid
49+
graph LR
50+
A[API Request] --> B[Server]
51+
B --> C[FCM]
52+
C --> D[Device]
53+
D --> E[Retrieve Messages]
54+
```
55+
56+
- Instant delivery via Firebase
57+
- Primary message channel
58+
59+
=== "Scheduled Polling ⏰"
60+
```mermaid
61+
graph LR
62+
A[Device] --> B{Every 15min}
63+
B --> C[Check Server]
64+
C --> D[Get Messages]
2565
```
2666

27-
### Password Management
67+
- Fallback mechanism
68+
- Ensures message delivery
69+
70+
=== "Custom Ping 📡"
71+
<center>
72+
<img src="/assets/features-ping-settings.png" alt="Custom Ping settings interface">
73+
</center>
74+
75+
- Configurable check interval
76+
- May increase battery consumption
77+
78+
### How to Use 🛠️
79+
80+
1. **Activate Cloud Mode**
81+
Launch app → Toggle "Cloud Server"
82+
83+
2. **Go Online**
84+
Tap the "Offline" button → Becomes "Online"
85+
86+
3. **Get Credentials**
87+
They will be generated by the server.
88+
<center>
89+
<img src="/assets/cloud-server.png" alt="Cloud Server credentials screenshot"/>
90+
</center>
91+
92+
93+
94+
4. **Send Message**
95+
96+
=== "cURL"
97+
```bash
98+
curl -X POST -u "username:password" \
99+
-H "Content-Type: application/json" \
100+
-d '{"message":"Hello World","phoneNumbers":["+79990001234"]}' \
101+
https://api.sms-gate.app/3rdparty/v1/messages
102+
```
103+
104+
=== "Python"
105+
```python
106+
import requests
107+
108+
response = requests.post(
109+
"https://api.sms-gate.app/3rdparty/v1/messages",
110+
auth=("username", "password"),
111+
json={
112+
"message": "Hello World",
113+
"phoneNumbers": ["+79990001234"]
114+
}
115+
)
116+
```
117+
118+
=== "JavaScript"
119+
```javascript
120+
fetch('https://api.sms-gate.app/3rdparty/v1/messages', {
121+
method: 'POST',
122+
headers: {
123+
'Authorization': 'Basic ' + btoa('username:password'),
124+
'Content-Type': 'application/json'
125+
},
126+
body: JSON.stringify({
127+
message: "Hello World",
128+
phoneNumbers: ["+79990001234"]
129+
})
130+
});
131+
```
132+
133+
#### Password Management 🔐
134+
135+
!!! danger "Security Requirements"
136+
- :material-form-textbox-password: Minimum 14 characters
137+
- :material-text: No reuse of previous passwords is recommended
138+
- :material-clock-alert: Changes take immediate effect
28139

29-
To change your account password, follow these steps:
140+
**Update Steps**:
30141

31-
1. Open the app and navigate to the "Settings" tab
32-
2. Locate the "Cloud Server" section
33-
3. In "Credentials" section, tap the "Password" item and enter new password
34-
4. Changes will be applied immediately
142+
1. :gear: Settings → Cloud Server
143+
2. :material-key: Credentials → Password
144+
3. :material-form-textbox-password: Enter new password
145+
4. :material-check: Confirm changes
35146

36-
#### Requirements
147+
---
37148

38-
* Password must be at least 14 characters long
149+
[:material-book-open: Full API Documentation](https://capcom6.github.io/android-sms-gateway)

0 commit comments

Comments
 (0)