diff --git a/docs/config.md b/docs/config.md index fa599388..353a9d03 100644 --- a/docs/config.md +++ b/docs/config.md @@ -814,6 +814,7 @@ ntfy tier add \ --message-limit=10000 \ --message-expiry-duration=24h \ --email-limit=50 \ + --call-limit=10 \ --reservation-limit=10 \ --attachment-file-size-limit=100M \ --attachment-total-size-limit=1G \ @@ -854,6 +855,22 @@ stripe-webhook-key: "whsec_ZnNkZnNIRExBSFNES0hBRFNmaHNka2ZsaGR" billing-contact: "phil@example.com" ``` +## Phone calls +ntfy supports phone calls via [Twilio](https://www.twilio.com/) as a phone call provider. If phone calls are enabled, +users can verify and add a phone number, and then receive phone calls when publish a message with the `X-Call` header. +See [publishing page](publish.md#phone-calls) for more details. + +To enable Twilio integration, sign up with [Twilio](https://www.twilio.com/), purchase a phone number (Toll free numbers +are the easiest), and then configure the following options: + +* `twilio-account` is the Twilio account SID, e.g. AC12345beefbeef67890beefbeef122586 +* `twilio-auth-token` is the Twilio auth token, e.g. affebeef258625862586258625862586 +* `twilio-from-number` is the outgoing phone number you purchased, e.g. +18775132586 +* `twilio-verify-service` is the Twilio Verify service SID, e.g. VA12345beefbeef67890beefbeef122586 + +After you have configured phone calls, create a [tier](#tiers) with a call limit, and then assign it to a user. +Users may then use the `X-Call` header to receive a phone call when publishing a message. + ## Rate limiting !!! info Be aware that if you are running ntfy behind a proxy, you must set the `behind-proxy` flag. diff --git a/docs/publish.md b/docs/publish.md index 2491671f..98f3e876 100644 --- a/docs/publish.md +++ b/docs/publish.md @@ -2718,7 +2718,7 @@ On ntfy.sh, this feature is only supported to [ntfy Pro](https://ntfy.sh/app) pl curl \ -u :tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2 \ -H "Call: +12223334444" \ - -d "Your garage seems to be on fire. You should probably check that out, and call 0118 999 881 999 119 725 3 for help." \ + -d "Your garage seems to be on fire. You should probably check that out." \ ntfy.sh/alerts ``` @@ -2727,7 +2727,7 @@ On ntfy.sh, this feature is only supported to [ntfy Pro](https://ntfy.sh/app) pl ntfy publish \ --token=tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2 \ --call=+12223334444 \ - alerts "Your garage seems to be on fire. You should probably check that out, and call 0118 999 881 999 119 725 3 for help." + alerts "Your garage seems to be on fire. You should probably check that out." ``` === "HTTP" @@ -2737,14 +2737,14 @@ On ntfy.sh, this feature is only supported to [ntfy Pro](https://ntfy.sh/app) pl Authorization: Bearer tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2 Call: +12223334444 - Your garage seems to be on fire. You should probably check that out, and call 0118 999 881 999 119 725 3 for help. + Your garage seems to be on fire. You should probably check that out. ``` === "JavaScript" ``` javascript fetch('https://ntfy.sh/alerts', { method: 'POST', - body: "Your garage seems to be on fire. You should probably check that out, and call 0118 999 881 999 119 725 3 for help.", + body: "Your garage seems to be on fire. You should probably check that out.", headers: { 'Authorization': 'Bearer tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2', 'Call': '+12223334444' @@ -2755,7 +2755,7 @@ On ntfy.sh, this feature is only supported to [ntfy Pro](https://ntfy.sh/app) pl === "Go" ``` go req, _ := http.NewRequest("POST", "https://ntfy.sh/alerts", - strings.NewReader("Your garage seems to be on fire. You should probably check that out, and call 0118 999 881 999 119 725 3 for help.")) + strings.NewReader("Your garage seems to be on fire. You should probably check that out.")) req.Header.Set("Call", "+12223334444") req.Header.Set("Authorization", "Bearer tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2") http.DefaultClient.Do(req) @@ -2770,7 +2770,7 @@ On ntfy.sh, this feature is only supported to [ntfy Pro](https://ntfy.sh/app) pl Authorization = "Bearer tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2" Call = "+12223334444" } - Body = "Your garage seems to be on fire. You should probably check that out, and call 0118 999 881 999 119 725 3 for help." + Body = "Your garage seems to be on fire. You should probably check that out." } Invoke-RestMethod @Request ``` @@ -2778,7 +2778,7 @@ On ntfy.sh, this feature is only supported to [ntfy Pro](https://ntfy.sh/app) pl === "Python" ``` python requests.post("https://ntfy.sh/alerts", - data="Your garage seems to be on fire. You should probably check that out, and call 0118 999 881 999 119 725 3 for help.", + data="Your garage seems to be on fire. You should probably check that out.", headers={ "Authorization": "Bearer tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2", "Call": "+12223334444" @@ -2794,11 +2794,24 @@ On ntfy.sh, this feature is only supported to [ntfy Pro](https://ntfy.sh/app) pl "Content-Type: text/plain\r\n" . "Authorization: Bearer tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2\r\n" . "Call: +12223334444", - 'content' => 'Your garage seems to be on fire. You should probably check that out, and call 0118 999 881 999 119 725 3 for help.' + 'content' => 'Your garage seems to be on fire. You should probably check that out.' ] ])); ``` +Here's what a phone call from ntfy sounds like: + + + +Audio transcript: + +> You have a notification from ntfy on topic alerts. +> Message: Your garage seems to be on fire. You should probably check that out. End message. +> This message was sent by user phil. It will be repeated up to three times. + ## Authentication Depending on whether the server is configured to support [access control](config.md#access-control), some topics may be read/write protected so that only users with the correct credentials can subscribe or publish to them. diff --git a/docs/static/audio/ntfy-phone-call.mp3 b/docs/static/audio/ntfy-phone-call.mp3 new file mode 100644 index 00000000..0cace65f Binary files /dev/null and b/docs/static/audio/ntfy-phone-call.mp3 differ diff --git a/docs/static/audio/ntfy-phone-call.ogg b/docs/static/audio/ntfy-phone-call.ogg new file mode 100644 index 00000000..cbbf6b60 Binary files /dev/null and b/docs/static/audio/ntfy-phone-call.ogg differ