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)

---
summary: Simplify setup of Converse.js
depends:
- 'mod\_bosh'
- 'mod\_websocket'
provides:
- http
title: 'mod\_conversejs'
rockspec:
  build:
    copy_directories:
    - templates
---

Introduction
============

This module simplifies setup of [Converse.js](https://conversejs.org/)
by serving it from Prosodys internal [http server][doc:http] along with
generated configuration to match the local VirtualHost. It becomes
available on an URL like `https://example.com:5281/conversejs`

Configuration
=============

The module uses general Prosody options for basic configuration. It
should just work after loading it.

``` {.lua}
modules_enabled = {
    -- other modules...
    "conversejs";
}
```

Authentication
--------------

[Authentication settings][doc:authentication] are used determine
whether to configure Converse.js to use `login` or `anonymous` mode.

Connection methods
------------------

mod_conversejs also determines the [BOSH][doc:setting_up_bosh] and
[WebSocket][doc:websocket] URL automatically, see their respective
documentation for how to configure them. Both connection methods are
loaded automatically.

Auto-loading of `mod_bosh` or `mod_websocket` can be prevented by adding
it to `modules_disabled` but note that at least one of them must be
allowed for Converse.js to work.

HTTP
----

The module is served on Prosody's default HTTP ports at the path
`/conversejs`. More details on configuring HTTP modules in Prosody can
be found in our [HTTP documentation](http://prosody.im/doc/http).

## Templates

The HTML and JS can be customized either by editing the included
`template.html` and `template.js` files or configuring your own like:

```lua
conversejs_html_template = "/path/to/my-template.html"
conversejs_js_template = "/path/to/my-template.js"
```

The HTML template uses Prosodys
[`util.interpolation`][doc:developers:util:interpolation] template 
library while the JS template has `%s` where generated settings are 
injected.

Other
-----

To pass [other Converse.js
options](https://conversejs.org/docs/html/configuration.html), or
override the derived settings, one can set `conversejs_options` like
this:

``` {.lua}
conversejs_options = {
    debug = true;
    view_mode = "fullscreen";
}
```

Note that the following options are automatically provided, and
**overriding them may cause problems**:

-   `authentication` *based on Prosody's authentication settings*
-   `bosh_service_url`
-   `websocket_url`
-   `discover_connection_methods` *Disabled since we provide this*
-   `assets_path`
-   `allow_registration` *based on whether registration is enabled*
-   These settings are set to the current `VirtualHost`:
    -   `jid`
    -   `default_domain`
    -   `domain_placeholder`
    -   `registration_domain`

`mod_bosh` and/or `mod_websocket` are automatically enabled if available
and the respective endpoint is included in the generated options.

## Loading resources

By default the module will load the main script and CSS from
cdn.conversejs.org. For privacy or performance reasons you may want to
load the scripts from somewhere else.

To use a local distribution or build of Converse.js set
conversejs_resources to the local path of "dist" directory:

``` {.lua}
conversejs_resources = "/usr/src/conversejs/dist";
```

To use a different web server or CDN simply use the conversejs_cdn
option:

``` {.lua}
conversejs_cdn = "https://cdn.example.com"
```

To select a specific version of Converse.js, you may override the version:

``` {.lua}
conversejs_version = "5.0.0"
```

Note that versions other than the default may not have been tested with this module, and may include incompatible changes.

Finally, if you can override all of the above and just specify links directly to the CSS and JS files:

``` {.lua}
conversejs_script = "https://example.com/my-converse.js"
conversejs_css = "https://example.com/my-converse.css"
```

Additional tags
---------------

To add additional tags to the module, such as custom CSS or scripts, you may use the conversejs_tags option:

``` {.lua}
conversejs_tags = {
        -- Load custom CSS
        [[<link rel="stylesheet" href="https://example.org/css/custom.css">]];

        -- Load libsignal-protocol.js for OMEMO support (GPLv3; be aware of licence implications)
        [[<script src="https://cdn.conversejs.org/3rdparty/libsignal-protocol.min.js"></script>]];
}
```

The example above uses the `[[` and `]]` syntax simply because it will not conflict with any embedded quotes.

Custimizing the generated PWA options
-------------------------------------

``` {.lua}
conversejs_name = "Service name" -- Also used as the web page title
conversejs_short_name = "Shorter name"
conversejs_description = "Description of the service"
conversejs_manifest_icons = {
	{
	    src = "https://example.com/logo/512.png",
    	sizes = "512x512",
	},
	{
    	src = "https://example.com/logo/192.png",
	    sizes = "192x192",
	},
	{
    	src = "https://example.com/logo/192.svg",
	    sizes = "192x192",
	},
	{
	    src = "https://example.com/logo/512.svg",
    	sizes = "512x512",
	},
}
conversejs_pwa_color = "#397491"
```

Compatibility
=============

  Prosody version   state
  ----------------- ---------------
  0.9               Does not work
  0.10              Should work
  0.11              Works
  trunk             Works