From 761327c95efe4b494db539ba16c6fe345e1a475a Mon Sep 17 00:00:00 2001 From: Aleksandr Soloshenko Date: Fri, 7 Jun 2024 16:59:07 +0700 Subject: [PATCH] [webhooks] add getting started for webhooks --- docs/getting-started/local-server.md | 5 ++- docs/getting-started/private-server.md | 3 +- docs/getting-started/public-cloud-server.md | 5 ++- docs/getting-started/webhooks.md | 40 +++++++++++++++++++++ docs/index.md | 6 ++-- mkdocs.yml | 9 +++++ 6 files changed, 63 insertions(+), 5 deletions(-) create mode 100644 docs/getting-started/webhooks.md diff --git a/docs/getting-started/local-server.md b/docs/getting-started/local-server.md index 7393af5..b27aab5 100644 --- a/docs/getting-started/local-server.md +++ b/docs/getting-started/local-server.md @@ -18,5 +18,8 @@ This mode is ideal for sending messages from a local network. 5. To send a message from within the local network, execute a `curl` command like the following. Be sure to replace ``, ``, and `` with the actual values provided in the previous step: ```sh - curl -X POST -u : -H "Content-Type: application/json" -d '{ "message": "Hello, world!", "phoneNumbers": ["79990001234", "79995556677"] }' http://:8080/message + curl -X POST -u : \ + -H "Content-Type: application/json" \ + -d '{ "message": "Hello, world!", "phoneNumbers": ["+79990001234", "+79995556677"] }' \ + http://:8080/message ``` diff --git a/docs/getting-started/private-server.md b/docs/getting-started/private-server.md index df80a88..d397268 100644 --- a/docs/getting-started/private-server.md +++ b/docs/getting-started/private-server.md @@ -21,7 +21,8 @@ To enhance privacy, you can host a private server within your own infrastructure - Define `gateway.private_token` as the access token for device registration in private mode. Ensure this token matches the one on the devices set to private mode. 2. Start the server in Docker with the following command: ```sh - docker run -p 3000:3000 -v $(pwd)/config.yml:/app/config.yml capcom6/sms-gateway:latest + docker run -p 3000:3000 -v $(pwd)/config.yml:/app/config.yml \ + capcom6/sms-gateway:latest ``` 3. Configure your reverse proxy, enable SSL, and modify your firewall settings to permit Internet access to the server. diff --git a/docs/getting-started/public-cloud-server.md b/docs/getting-started/public-cloud-server.md index 4a3a36f..8ce44b2 100644 --- a/docs/getting-started/public-cloud-server.md +++ b/docs/getting-started/public-cloud-server.md @@ -18,5 +18,8 @@ Use the cloud server mode when dealing with dynamic or shared device IP addresse 5. To send a message via the cloud server, perform a `curl` request with a command similar to the following, substituting `` and `` with the actual values obtained in step 4: ```sh - curl -X POST -u : -H "Content-Type: application/json" -d '{ "message": "Hello, world!", "phoneNumbers": ["79990001234", "79995556677"] }' https://sms.capcom.me/api/3rdparty/v1/message + curl -X POST -u : \ + -H "Content-Type: application/json" \ + -d '{ "message": "Hello, world!", "phoneNumbers": ["+79990001234", "+79995556677"] }' \ + https://sms.capcom.me/api/3rdparty/v1/message ``` diff --git a/docs/getting-started/webhooks.md b/docs/getting-started/webhooks.md new file mode 100644 index 0000000..e33e215 --- /dev/null +++ b/docs/getting-started/webhooks.md @@ -0,0 +1,40 @@ +# Getting Started + +## Webhooks + +Webhooks can be utilized to get notifications of incoming SMS messages. + +Follow these steps to set up webhooks: + +1. Set up your own HTTP server with a valid SSL certificate to receive webhooks. For testing purposes, [webhook.site](https://webhook.site) can be useful. +2. Register your webhook with an API request: + + ```sh + curl -X POST -u : \ + -H "Content-Type: application/json" \ + -d '{ "id": "unique-id", "url": "https://webhook.site/", "event": "sms:received" }' \ + http://:8080/webhooks + ``` + +3. Send an SMS to the device. +4. The application will dispatch POST request to the specified URL with a payload such as: + + ```json + { + "event": "sms:received", + "payload": { + "message": "Received SMS text", + "phoneNumber": "+79990001234", + "receivedAt": "2024-06-07T11:41:31.000+07:00" + } + } + ``` + +5. To deregister a webhook, execute a `curl` request using the following pattern: + + ```sh + curl -X DELETE -u : \ + http://:8080/webhooks/unique-id + ``` + +*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. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 18d47ea..94f8926 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ Logo -Android SMS Gateway turns your Android smartphone into an SMS gateway. It's a lightweight application that allows you to send SMS messages programmatically via an API. This makes it ideal for integrating SMS functionality into your own applications or services. +Android SMS Gateway turns your Android smartphone into an SMS gateway. It's a lightweight application that allows you to send SMS messages programmatically via an API and receive webhooks on incoming SMS. This makes it ideal for integrating SMS functionality into your own applications or services.

@@ -21,14 +21,16 @@ Android SMS Gateway turns your Android smartphone into an SMS gateway. It's a li - **Message expiration:** The application allows setting an expiration time for messages. Messages will not be sent if they have expired. - **Random delay between messages:** Introduces a random delay between sending messages to avoid mobile operator restrictions. - **Private server support:** The application allows for the use of a backend server in the user's infrastructure for enhanced security. +- **Webhooks on incoming SMS:** The application allows setting up webhooks to be sent to a specified URL whenever an SMS is received. ## Ideal For - Notifications - Alerts - Two-factor authentication codes +- Receiving incoming SMS -Android SMS Gateway offers a convenient and reliable solution for sending notifications, alerts, or two-factor authentication codes. +Android SMS Gateway offers a convenient and reliable solution for sending notifications, alerts, or two-factor authentication codes, and also allows you to receive webhooks when an SMS is received. *Note*: It is not recommended to use this for batch sending due to potential mobile operator restrictions. diff --git a/mkdocs.yml b/mkdocs.yml index 33bf6fa..84b0dd6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,6 +35,7 @@ nav: - Public Cloud Server: getting-started/public-cloud-server.md - Private Server: getting-started/private-server.md - Custom Gateway Setup: getting-started/custom-gateway.md + - Webhooks: getting-started/webhooks.md - Integration: - API: integration/api.md - Pricing: pricing.md @@ -61,3 +62,11 @@ plugins: remove_comments: true cache_safe: true - social +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences