Skip to content

Commit

Permalink
[features] add messages reading guide
Browse files Browse the repository at this point in the history
  • Loading branch information
capcom6 committed Jan 4, 2025
1 parent 727080e commit 2b4e0a0
Show file tree
Hide file tree
Showing 3 changed files with 30 additions and 0 deletions.
28 changes: 28 additions & 0 deletions docs/features/reading-messages.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Reading Messages

The app not only allows receiving incoming messages in real-time via webhooks but also enables reading previously received messages using the same webhook.

## How it works

To read messages, please follow these steps:

1. Register the `sms:received` webhook as described in the [Webhooks](../features/webhooks.md) guide if you haven't done so already.
2. Determine the Device ID of the device you want to read messages from by calling the `GET /devices` endpoint:
```
curl -u <username>:<password> https://api.sms-gate.app/3rdparty/v1/devices
```
3. Send a request with `deviceId` and period to the `POST /messages/inbox/export` endpoint:
```
curl -u <username>:<password> \
-H "Content-Type: application/json" \
-d '{ "deviceId": "<device-id>", "since": "2024-01-01T00:00:00Z", "until": "2024-12-31T23:59:59Z" }' \
https://api.sms-gate.app/3rdparty/v1/messages/inbox/export
```
4. After receiving the request, the device will send `sms:received` webhooks for each message in the inbox for the specified period.
## Notes
* The webhook will be sent for each message independently, so the order of messages is not guaranteed.
* It is recommended to split long periods into shorter ones to avoid excessive load on your webhook receiver.
* The export webhooks retry policy is the same as described in the [Webhooks](../features/webhooks.md) guide.
* The ID for incoming messages is generated based on the content of the message and is not guaranteed to be unique.
1 change: 1 addition & 0 deletions docs/features/webhooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Webhooks offer a powerful mechanism to receive real-time notifications of events
Currently, the following event is supported:

- `sms:received` - Triggered when an SMS is received by the device. The payload for this event includes:
* `messageId`: The ID of the SMS message. The ID is generated based on the content of the message and is not guaranteed to be unique.
* `message`: The content of the SMS message.
* `phoneNumber`: The phone number that sent the SMS.
* `simNumber`: The SIM card number that received the SMS. May be `null` on some Android devices.
Expand Down
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ nav:
- Features:
- Multi-SIM Support: features/multi-sim.md
- Webhooks: features/webhooks.md
- Reading Messages: features/reading-messages.md
- Logging: features/logging.md
- Pricing: pricing.md
- Privacy:
Expand Down

0 comments on commit 2b4e0a0

Please sign in to comment.