mod_voipms

Introduction

This is a Prosody module to map JIDs to DIDs on VoIP.ms and support sending/receiving SMS/MMS.

Once configured, users receiving SMS messages to their DID numbers will receive an XMPP message from their server with the message content and may send SMS by repling directly to these messages or by crafting similar destination JIDs.

For this to work, the following are required through VoIP.ms:

• a valid account and DID
• Enable API calls for the DID
• Set user/password for the DID
• Set the Webhook URI for the DID
• Allow API calls from the Prosody Server IP address (or hostname)

Configuration

The voipms_api_username and voip_api_password are specific to the VoIP.ms account and may be set or configured through the VoIP.ms web site, through the API Configuration.

The voipms_query_key is a token or secret that you create in your local prosody module configuration and include later in the Webhook on the VoIP.ms web site.

The voipms_jid_map is a local mapping of DIDs owned by the account described by voipms_api_username and the local XMPP accounts to which messages from those numbers will be sent or received. This is used in the incoming XMPP message’s JID for messages received and is used as the sending number when replying to SMS messages received by that JID.

Sample module configuration:

VirtualHost "sms.example.com"
modules_enabled = {
    "voipms";
}
voipms_api_username = john@example.com
voipms_api_password = abcd1234
voipms_query_key = some_query_key
voipms_jid_map = {
        ["your_jid@your_domain.com"] = { "+10234567890" },
        ["your_jid2@your_domain.com"] = { "+10123456789", "+10573647583" }
}

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

Troubleshooting

Long API passwords can result in voipms: Failed to send sendSMS: invalid_credentials despite being correct. This was witnessed in using an obnoxiously long password (>128 characters). It may be necessary to use less than 32 characters, but no extensive testing was done.

If your Prosody configuration is only exposing the defualt ports, it may be necessary to include the port number in the Webhook URL:

https://sms.example.com:5281/voipms?key=some_query_key

If messages are being recieved but you are unable to reply or send SMS messages, double check that the IP address or host name of the Prosody server is in the list of IP addresses allowed to call the API. See Enable IP Adresess in the API Configuration. Separate multiple addresses with commas. Ranges of IPs are also supported.

Additional Troubleshooting

If there are problems sending messages from Prosody to SMS numbers, you can test the pieces standalone using bash and curl, for example:

endpoint="https://voip.ms/api/v1/rest.php"
method='sendSMS'
body='test message'
curl -G "${endpoint}" \
             --data-urlencode "api_username=${api_username}" \
             --data-urlencode "api_password=${api_password}" \
             --data-urlencode "method=${method}" \
             --data-urlencode "did=${from_number}" \
             --data-urlencode "dst=${dst_number}" \
             --data-urlencode "message=${body}"

Note: Make sure to set values for api_username, api_password, from_number, and dst_number.

This is a quick way to diagnose authentication or account issues in communicating with VoIP.ms but make sure the system making the call is in the allowed IP list and to provide the other details needed.

If there are problems in receiving SMS messages via Prosody, check the Webhook URI value to make sure the same value is provided there for the key as is provided in the module coniguration voipms_query_key. Also check that the port used in the Webhook API is the correct port. A default installation will need port 5281 specified explicitly. Common setups that make use of port 80 or 443 will not need to specify a port.

If after enabling the module the Upload HTTP or HTTP File Share plugins stop allowing uploads, set an explicit virutal host entry for the module in question directly in the component section of the prosody.cfg.lua, for example:

Component "upload.example.com" "http_file_share"
    http_paths = {
        file_share = "/"
    }

sudo prosodyctl install --server=https://modules.prosody.im/rocks/ mod_voipms