mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs. diff --git a/mod_voipms/README.md b/mod_voipms/README.md new file mode 100644 --- /dev/null +++ b/mod_voipms/README.md @@ -0,0 +1,51 @@ +--- +labels: +- 'Stage-Alpha' +- 'Type-Web' +summary: Send and receive SMS/MMS via VoIP.ms APIs. +rockspec: + build: + modules: + mod_voipms: mod_voipms.lua +... + +Introduction +============ + +This is a Prosody module to map JIDs to DIDs on VoIP.ms and support sending/receiving SMS/MMS. + +Configuration +============= + +| option | type | default | +|-----------------------|--------|---------| +| voipms\_api\_username | string | nil | +| voipms\_api\_password | string | nil | +| voipms\_query\_key | string | nil | +| voipms\_jid\_map | table | nil | +``` +VirtualHost "sms.example.com" +modules_enabled = { + "voipms"; +} +voipms_api_username = john@example.com -- E-mail registered with VoIP.ms +voipms_api_password = abcd1234 -- API password configured in VoIP.ms +voipms_query_key = some_query_key -- query param 'key' part of your URL callback +voipms_jid_map = { + ["your_jid@your_domain.com"] = "+1234567890" +} +``` + +HTTP +==== + +The module is served on Prosody's default HTTP ports at the path /voipms. More details on configuring HTTP modules in Prosody can be found in the HTTP documentation. + +VoIP.ms Webhook URL +=================== + +This module receives the VoIP.ms Webhook URL (POST) at the /voipms endpoint. It uses the sendSMS/sendMMS GET methods against the VoIP.ms APIs. This is an example webhook to use in VoIP.ms: + +``` +https://sms.example.com/voipms?key=some_query_key +``` diff --git a/mod_voipms/mod_voipms.lua b/mod_voipms/mod_voipms.lua new file mode 100644 --- /dev/null +++ b/mod_voipms/mod_voipms.lua @@ -0,0 +1,166 @@ +local http = require "net.http" +local json = require "util.json" +local st = require "util.stanza" + +local api_username = module:get_option_string("voipms_api_username") +local api_password = module:get_option_string("voipms_api_password") +local query_key = module:get_option("voipms_query_key") +local jid_map = module:get_option("voipms_jid_map") or {} +local rest_endpoint = "https://voip.ms/api/v1/rest.php" + +if not api_username or not api_password or not query_key then + module:log("error", "Missing required config values (voipms_api_username, voipms_api_password, voipms_query_key)") + return +end + +module:depends("http") + +local function normalize_number(num) + if not num then return nil end + if num:sub(1, 1) ~= "+" then + return "+1" .. num + end + return num +end + +local function extract_query_key(event) + return (event.request.url.query or ""):match("key=([^&]+)") +end + +module:provides("http", { + route = { + ["POST"] = function(event) + local req = event.request + local body = req.body or "" + + if extract_query_key(event) ~= query_key then + module:log("warn", "Unauthorized webhook: missing or invalid key") + return { status_code = 403 } + end + + local json_payload, err = json.decode(body) + if not json_payload then + module:log("warn", "Invalid JSON: %s", err or "unknown error") + return { status_code = 400 } + end + + local payload = json_payload.data and json_payload.data.payload + if not payload then + module:log("warn", "Missing payload in JSON") + return { status_code = 400 } + end + + local from = payload.from and payload.from.phone_number + local to_list = payload.to or {} + local to = #to_list > 0 and to_list[1].phone_number or nil + + if not from or not to then + module:log("warn", "Missing phone numbers (from: %s, to: %s)", tostring(from), tostring(to)) + return { status_code = 400 } + end + + local normalized_to = normalize_number(to) + local target_jid = nil + + for jid, did in pairs(jid_map) do + if normalize_number(did) == normalized_to then + target_jid = jid + break + end + end + + if not target_jid then + module:log("warn", "No JID mapping for DID %s", normalized_to) + return { status_code = 404 } + end + + local normalized_from = normalize_number(from) + local message_text = payload.text or "" + + local message = st.message({ + from = normalized_from .. "@" .. module.host, + to = target_jid, + type = "chat" + }):tag("body"):text(message_text):up() + + if payload.media and #payload.media > 0 then + for _, media_item in ipairs(payload.media) do + if media_item.url then + message_text = message_text .. "\n" .. media_item.url + message:tag("x", { xmlns = "jabber:x:oob" }) + :tag("url"):text(media_item.url):up():up() + end + end + end + + module:send(message) + module:log("info", "Delivered SMS from %s to %s", normalized_from, target_jid) + + return { status_code = 204 } + end + } +}) + +module:hook("message/bare", function(event) + local stanza = event.stanza + if stanza.attr.type ~= "chat" then return end + + local from_jid = stanza.attr.from + local to_jid = stanza.attr.to + local body = stanza:get_child_text("body") + if not body or body == "" then return end + + local from_number = jid_map[from_jid] + if not from_number then + module:log("warn", "No DID mapping for JID %s", from_jid) + return + end + + local to_number = to_jid:match("^([^@]+)") + if not to_number then + module:log("warn", "Malformed JID in message.to: %s", to_jid) + return + end + + to_number = normalize_number(to_number) + + local media_urls = {} + for line in body:gmatch("[^\r\n]+") do + if line:match("^https?://") then + table.insert(media_urls, line) + end + end + + local method = (#media_urls > 0) and "sendMMS" or "sendSMS" + local query = { + api_username = api_username, + api_password = api_password, + method = method, + did = from_number, + dst = to_number, + message = body + } + + if method == "sendMMS" then + for i, url in ipairs(media_urls) do + query["media_url[" .. (i - 1) .. "]"] = url + end + end + + local query_str = http.formencode(query) + + http.request(rest_endpoint .. "?" .. query_str, { + method = "GET"; + }, function(response_body, code) + if code == 200 then + local resp, err = json.decode(response_body) + if not resp or resp.status ~= "success" then + module:log("error", "Failed to send %s: %s", method, err or (resp and resp.status) or "unknown") + else + module:log("info", "Sent %s from %s to %s", method, from_number, to_number) + end + else + module:log("error", "HTTP error sending %s: code %s", method, tostring(code)) + end + end) +end)

---
labels:
- 'Stage-Beta'
summary: 'XEP-0357: Cloud push notifications'
---

# Introduction

This module enables support for sending "push notifications" to clients
that need it, typically those running on certain mobile devices.

As well as this module, your client must support push notifications (the
apps that need it generally do, of course) and the app developer's push
gateway must be reachable from your Prosody server (this happens over a
normal XMPP server-to-server 's2s' connection).

# Details

Some platforms, notably Apple's iOS and many versions of Android, impose
limits that prevent applications from running or accessing the network
in the background. This makes it difficult or impossible for an XMPP
application to remain reliably connected to a server to receive
messages.

In order for messaging and other apps to receive notifications, the OS
vendors run proprietary servers that their OS maintains a permanent
connection to in the background. Then they provide APIs to application
developers that allow sending notifications to specific devices via
those servers.

When you connect to your server with an app that requires push
notifications, it will use this module to set up a "push registration".
When you receive a message but your device is not connected to the
server, this module will generate a notification and send it to the push
gateway operated by your application's developers). Their gateway will
then connect to your device's OS vendor and ask them to forward the
notification to your device. When your device receives the notification,
it will display it or wake up the app so it can connect to XMPP and
receive any pending messages.

This protocol is described for developers in [XEP-0357: Push
Notifications].

For this module to work reliably, you must have [mod_smacks],
[mod_mam] and [mod_carbons] also enabled on your server.

Some clients, notably Siskin and Snikket iOS need some additional
extensions that are not currently defined in a standard XEP. To support
these clients, see [mod_cloud_notify_extensions].

# Configuration

  Option                                 Default          Description
  -------------------------------------- ---------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  `push_notification_important_body`     `New Message!`   The body text to use when the stanza is important (see above), no message body is sent if this is empty
  `push_max_errors`                      `16`             How much persistent push errors are tolerated before notifications for the identifier in question are disabled
  `push_max_devices`                     `5`              The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached)
  `push_max_hibernation_timeout`         `259200` (72h)   Number of seconds to extend the smacks timeout if no push was triggered yet (default: 72 hours)
  `push_notification_with_body` (\*)     `false`          Whether or not to send the real message body to remote pubsub node. Without end-to-end encryption, enabling this may expose your message contents to your client developers and OS vendor. Not recommended.
  `push_notification_with_sender` (\*)   `false`          Whether or not to send the real message sender to remote pubsub node. Enabling this may expose your contacts to your client developers and OS vendor. Not recommended.

(\*) There are privacy implications for enabling these options.[^1]

# Internal design notes

App servers are notified about offline messages, messages stored by
[mod_mam] or messages waiting in the smacks queue. The business rules
outlined
[here](//mail.jabber.org/pipermail/standards/2016-February/030925.html)
are all honored[^2].

To cooperate with [mod_smacks] this module consumes some events:
`smacks-ack-delayed`, `smacks-hibernation-start` and
`smacks-hibernation-end`. These events allow this module to send out
notifications for messages received while the session is hibernated by
[mod_smacks] or even when smacks acknowledgements for messages are
delayed by a certain amount of seconds configurable with the
[mod_smacks] setting `smacks_max_ack_delay`.

The `smacks_max_ack_delay` setting allows to send out notifications to
clients which aren't already in smacks hibernation state (because the
read timeout or connection close didn't already happen) but also aren't
responding to acknowledgement request in a timely manner. This setting
thus allows conversations to be smoother under such circumstances.

The new event `cloud-notify-ping` can be used by any module to send out
a cloud notification to either all registered endpoints for the given
user or only the endpoints given in the event data.

The config setting `push_notification_important_body` can be used to
specify an alternative body text to send to the remote pubsub node if
the stanza is encrypted or has a body. This way the real contents of the
message aren't revealed to the push appserver but it can still see that
the push is important. This is used by Chatsecure on iOS to send out
high priority pushes in those cases for example.

# Compatibility

**Note:** This module should be used with Lua 5.2 and higher. Using it
with Lua 5.1 may cause push notifications to not be sent to some
clients.

  ------- ----------------------
  trunk   Works as of 25-06-13
  13.0    Works
  0.12    Works
  ------- ----------------------

[^1]: The service which is expected to forward notifications to
    something like Google Cloud Messaging or Apple Notification Service

[^2]: [business_rules.md](//hg.prosody.im/prosody-modules/file/tip/mod_cloud_notify/business_rules.md)