Mercurial > prosody-modules

annotate mod_voipms/README.md @ 6562:5da6fb562df9 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_unified_push: Fix push error handling (fixes #2000) Use the error object that send_iq() passes as an argument to it's reject callback instead of attempting and failing to do the parsing in the callback itself.
author kmq
date Mon, 06 Jul 2026 14:23:57 +0200
parents 6015477b6dec
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6299
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
1 ---
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
2 labels:
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
3 - 'Stage-Alpha'
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
4 - 'Type-Web'
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
5 summary: Send and receive SMS/MMS via VoIP.ms APIs.
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
6 rockspec:
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
7 build:
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
8 modules:
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
9 mod_voipms: mod_voipms.lua
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
10 ...
6308
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
11
6299
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
12 Introduction
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
13 ============
6308
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
14
6299
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
15 This is a Prosody module to map JIDs to DIDs on VoIP.ms and support sending/receiving SMS/MMS.
6308
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
16
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
17 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.
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
18
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
19 For this to work, the following are required through VoIP.ms:
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
20
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
21 - a valid account and DID
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
22 - Enable API calls for the DID
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
23 - Set user/password for the DID
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
24 - Set the Webhook URI for the DID
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
25 - Allow API calls from the Prosody Server IP address (or hostname)
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
26
6299
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
27 Configuration
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
28 =============
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
29
6300
8689f49d21ef mod_voipms: Updates
Menel <menel@snikket.de>
parents: 6299
diff changeset
30 | option | type | default | description
8689f49d21ef mod_voipms: Updates
Menel <menel@snikket.de>
parents: 6299
diff changeset
31 |-----------------------|--------|---------|------------|
6308
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
32 | voipms\_api\_username | string | nil | E-mail address used at voip.ms
6300
8689f49d21ef mod_voipms: Updates
Menel <menel@snikket.de>
parents: 6299
diff changeset
33 | voipms\_api\_password | string | nil | API password (not login password)
8689f49d21ef mod_voipms: Updates
Menel <menel@snikket.de>
parents: 6299
diff changeset
34 | voipms\_query\_key | string | nil | Key to secure service (part of webhook)
8689f49d21ef mod_voipms: Updates
Menel <menel@snikket.de>
parents: 6299
diff changeset
35 | voipms\_jid\_map | table | nil | JID -> DIDs mapping
6308
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
36
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
37 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].
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
38
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
39 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.
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
40
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
41 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.
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
42
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
43 Sample module configuration:
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
44
6299
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
45 ```
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
46 VirtualHost "sms.example.com"
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
47 modules_enabled = {
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
48 "voipms";
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
49 }
6300
8689f49d21ef mod_voipms: Updates
Menel <menel@snikket.de>
parents: 6299
diff changeset
50 voipms_api_username = john@example.com
8689f49d21ef mod_voipms: Updates
Menel <menel@snikket.de>
parents: 6299
diff changeset
51 voipms_api_password = abcd1234
8689f49d21ef mod_voipms: Updates
Menel <menel@snikket.de>
parents: 6299
diff changeset
52 voipms_query_key = some_query_key
6299
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
53 voipms_jid_map = {
6308
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
54 ["your_jid@your_domain.com"] = { "+10234567890" },
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
55 ["your_jid2@your_domain.com"] = { "+10123456789", "+10573647583" }
6299
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
56 }
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
57 ```
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
58
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
59 HTTP
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
60 ====
6308
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
61
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
62 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.
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
63
6299
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
64 VoIP.ms Webhook URL
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
65 ===================
6308
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
66
6299
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
67 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:
6308
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
68
6299
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
69 ```
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
70 https://sms.example.com/voipms?key=some_query_key
5cf5ee23b361 mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs.
Chaz <menel@snikket.de>
parents:
diff changeset
71 ```
6308
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
72
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
73 Troubleshooting
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
74 ===============
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
75
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
76 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.
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
77
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
78 If your Prosody configuration is only exposing the defualt ports, it may be necessary to include the port number in the Webhook URL:
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
79
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
80 ```
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
81 https://sms.example.com:5281/voipms?key=some_query_key
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
82 ```
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
83
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
84 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.
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
85
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
86
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
87 Additional Troubleshooting
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
88 ==========================
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
89
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
90 If there are problems sending messages from Prosody to SMS numbers, you can test the pieces standalone using bash and curl, for example:
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
91
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
92 ```bash
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
93 endpoint="https://voip.ms/api/v1/rest.php"
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
94 method='sendSMS'
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
95 body='test message'
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
96 curl -G "${endpoint}" \
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
97 --data-urlencode "api_username=${api_username}" \
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
98 --data-urlencode "api_password=${api_password}" \
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
99 --data-urlencode "method=${method}" \
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
100 --data-urlencode "did=${from_number}" \
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
101 --data-urlencode "dst=${dst_number}" \
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
102 --data-urlencode "message=${body}"
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
103 ```
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
104
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
105 Note: Make sure to set values for `api_username`, `api_password`, `from_number`, and `dst_number`.
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
106
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
107 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.
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
108
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
109 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.
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
110
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
111 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:
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
112
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
113 ```
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
114 Component "upload.example.com" "http_file_share"
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
115 http_paths = {
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
116 file_share = "/"
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
117 }
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
118 ```
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
119
6015477b6dec mod_voipms: Update documentation, from Stephen
Chaz Kettleson <chaz@pyr3x.com>
parents: 6300
diff changeset
120 [API Configuration]: https://voip.ms/m/api.php