diff --git a/docs/faq/webhooks.md b/docs/faq/webhooks.md index e3d27fa..b0bcbce 100644 --- a/docs/faq/webhooks.md +++ b/docs/faq/webhooks.md @@ -125,6 +125,23 @@ Use this build when: - Never expose insecure builds to public networks - This build bypasses Android's cleartext traffic restrictions +## Why do I receive multiple delivery reports for a single message? 📨 + +When sending SMS messages longer than the standard character limits (160 characters for GSM/7-bit encoding or 70 characters for Unicode), the message is automatically split into multiple parts by the carrier. + +Each message part is: + +- Sent independently by the carrier +- Processed separately at the network level +- Delivered with its own confirmation receipt + +You'll receive separate `sms:delivered` events for each part, but they share the same: + +- `messageId` (links all parts to the original message) +- `phoneNumber` (recipient) + +See also: [Multipart Message Behavior](../features/webhooks.md#multipart-message-behavior) + ## Still Having Issues? :material-chat-question: Visit our [Support Forum](https://github.com/capcom6/android-sms-gateway/discussions) :material-forum: or contact us at [support@sms-gate.app](mailto:support@sms-gate.app) :material-email: diff --git a/docs/features/webhooks.md b/docs/features/webhooks.md index 21bdfe2..c2ad8fd 100644 --- a/docs/features/webhooks.md +++ b/docs/features/webhooks.md @@ -218,6 +218,24 @@ For webhooks within private networks: 4. **Insecure Build Variant** (Not Recommended) For local development and testing, use the [insecure build variant](../faq/webhooks.md#using-http-webhooks-in-local-development) that allows communication over HTTP without SSL. +## Multipart Message Behavior 📨 + +When sending SMS messages longer than the standard limits (160 characters for GSM‑7 or 70 characters for UCS‑2/Unicode), the app automatically splits the message into multiple parts before transmission. This multipart behavior affects webhook delivery in specific ways: + +| Event | Behavior | +| --------------- | ------------------------------------------------------------------------------------------------- | +| `sms:received` | Triggered once after all parts of an incoming multipart message are received and assembled | +| `sms:sent` | Triggered once when all parts of the outgoing message are successfully sent | +| `sms:delivered` | Triggered once **for each individual part** of the message | +| `sms:failed` | Triggered once if any part of the message fails to send or deliver; other parts may still succeed | + +!!! tip "Handling Multipart Delivery Reports" + To avoid processing duplicate deliveries in your webhook handler: + + - Use `messageId` to group related delivery reports + - Deduplicate based on `id` + - Consider the message fully delivered when you receive delivery confirmations for all expected parts + ## Security Considerations 🔐 - **Review Registered Webhooks Periodically**: Regularly audit your webhook URLs to guard against unauthorized or stale endpoints; the app also shows periodic reminders for this review. @@ -331,6 +349,7 @@ The signing key is randomly generated at first request and can be changed in **S ## See Also 📚 - [FAQ](../faq/webhooks.md) +- [Status Tracking](../features/status-tracking.md) - [Private Webhook Certificate Setup](../services/ca.md#private-webhook-certificate) - [API Documentation](https://capcom6.github.io/android-sms-gateway/#/Webhooks)