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: Delegate roster management to an external service
...

*NOTE: THIS MODULE IS RELEASED UNDER THE MOZILLA PUBLIC LICENSE VERSION 2.*

Normally the XMPP server will store and maintain the users' contact
rosters. This module lets you delegate roster management to an external
service.

Prosody will make an HTTP request to fetch the roster from the external
service. The service will need to notify Prosody whenever a user's roster
changes, so that Prosody can fetch a new roster for that user.

## Configuring this module

This module relies on `mod_storage_memory` and `mod_block_subscriptions`.

In `.parts/prosody/etc/prosody/prosody.cfg.lua`, where your particular
`VirtualHost` is being configured, add the following:

``` lua
modules_enabled = {
    "http_roster_admin",
    "block_subscriptions",
    "storage_memory",
    "http_files"
}
modules_disabled = {
     -- Prosody will get the roster from the backend app,
     -- so we disable the default roster module.
    "roster"
}
storage = { roster = "memory" }
http_roster_url = "http://localhost/contacts/%s" -- %s will be replaced by an URL-encoded username
```

The `http_roster_url` parameter needs to be configured to point to the
URL in the backend application which returns users' contacts rosters.

In this URL, the pattern `%s` is replaced by an URL-encoded username.

When the user *john* then connects to Prosody, and `http_roster_url` is
set to “http://app.example.org/contacts/%s”, then Prosody will make a
GET request to http://app.example.org/contacts/john

## Protocol

### Fetching rosters (Prosody to web app)

Prosody considers the web application to always hold the most accurate and up-to-date
version of the user's roster. When a user first connects, Prosody fetches the roster
from the web application and caches it internally.

Prosody will make a GET request to the URL specified in Prosody's configuration parameter
'http_roster_url'. In this URL, the pattern '%s' is replaced by an URL-encoded username.

For example, when the user 'john' connects to Prosody, and http_roster_url is set
to "http://app.example.com/contacts/%s", Prosody will make a GET request to "http://app.example.com/contacts/john".

The web app must return a JSON object, where each key is the JID of a contact, and the corresponding
value is data about that contact.

If the user 'john' has friends 'marie' and 'michael', the web app would return a HTTP '200 OK' response
with the following contents:

``` json
{
    "marie@example.com": {
        "name": "Marie"
    },

    "michael@example.com": {
        "name": "Michael"
    }
}
```

### Notifying Prosody of roster changes

The external service needs to notify Prosody whenever a user's roster
changes. To do this, it must make an HTTP POST request to either:

- http://localhost:5280/roster_admin/refresh
- https://localhost:5281/roster_admin/refresh

Make sure that the "http_files" module is enabled in Prosody's configuration,
for the above URLs to served.

Ports 5280/5281 can be firewalled and the web server (i.e. Apache or Nginx)
can be configured to reverse proxy those URLs to for example
https://example.org/http-bind.

The contents of the POST should be a JSON encoded array of usernames whose
rosters have changed.

For example, if user ‘john’ became friends with ‘aaron’, both john’s
contact list and aaron’s contact lists have changed:

``` json
["john", "aaron"]
```

When the operation is complete Prosody will reply with a summary of the
operation - a JSON object containing:

- **status**: either “ok” (success) or “error” (operation completely failed)
- **message**: A human-readable message (for logging and debugging purposes)
- **updated**: The number of rosters successfully updated
- **errors**: The number of rosters that failed to update

Example:

``` json
{
    "status":  "ok",
    "message": "roster update complete",
    "updated": 2,
    "errors":  0
}
```

Prosody may also return status codes `400` or `500` in case of errors (such
as a missing/malformed body).