Differences between revisions 2 and 32 (spanning 30 versions)
Revision 2 as of 2020-238 23:13:49
Size: 2401
Editor: d50-92-76-47
Comment: add "A word from our sponsors..." section (this is ossguy editing without an account)
Revision 32 as of 2020-239 02:01:29
Size: 8584
Editor: d50-92-76-47
Comment: fix minor typo in "Setup incoming call forwarding" (this is ossguy editing without an account)
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
#format wiki

<<TableOfContents()>>
Line 3: Line 7:
We support nearly all texting features at https://jmp.chat/ (including texting internationally) but currently can only provide US and Canadian phone numbers there. In order to get a phone number in a different country to use with Cheogram, we currently recommend Vonage. Here's how to set that up: These instructions are intended for technical and/or motivated individuals who need to text from a non-US/Canadian phone number. We recommend people who are fine with using a US or Canadian phone number signup for https://jmp.chat/ instead.
Line 5: Line 9:

- note incoming MMS ignored
- add donation stuff per singpolyma chat hist
- add voice/call instructions at top of guide
- test different SMS delivery statuses before launch (Cheogram reg might help?)
- test with Cheogram before launching SGX
- maybe make SGX DNS-accessible from outside
Providing the below SGX services is not free; if you find them useful please consider supporting infrastructure costs [[https://liberapay.com/singpolyma/|on Liberapay]], [[https://www.patreon.com/singpolyma|on Patreon]], or by becoming a paying customer of [[https://jmp.chat|JMP]].
Line 19: Line 17:
Note that with Vonage, very few countries support MMS. And we haven't implemented MMS in the SGX yet, so it won't yet work in any countries. Assume that any MMS sent to your Vonage number will be silently ignored for now.

== Setup incoming call forwarding ==

We haven't written anything to specifically handle calls with Vonage. But you can just forward incoming calls on your Vonage number to another number through their dashboard. To do that, follow these steps:

 1. Login to https://dashboard.nexmo.com/
 1. In the left panel, click Numbers then "Your numbers"
 1. Click the pencil icon under Manage next to the number you want to add forwarding to
 1. Under Voice, change "Forward to" from None to Phone
 1. Enter your phone number under Number
 1. Leave "Event Webhook URL" empty and click Save

Alternately, you may receive calls over XMPP Jingle instead of having them forwarded to a phone number. The steps are the same as above, but in place of steps 4 and 5 you instead:

 1.#4 Under Voice, change "Forward to" from None to SIP
 1. If your [[JabberID]] was {{{user@domain.tld}}} you would enter this as your SIP URI: {{{user%5C40domain.tld%40cheogram.com@sip.cheogram.com}}}

If you want to make outgoing calls, you can write a script to do that, or use https://callwithus.com/ and set your outgoing Caller ID to be your Vonage number.
Line 21: Line 39:
If you don't want to run your own instance of our software to get JMP-like features on non-US/Canadian numbers, then you can use the one that we at Soprani.ca run (see below for how to run your own instance). In order to use our instance, you just need the API Key and API Secret for your Vonage account, and a phone number in your Vonage account to register (so you can send/receive messages on that number using Cheogram). If you don't want to run your own instance of our software to get [[SGX]] features on non-US/Canadian numbers, then you can use the one that we at Soprani.ca run.  Here's how to do it:
Line 23: Line 41:
...  1. Login to https://dashboard.nexmo.com/
 1. Copy down the "API key" and "API Secret" values (the "two box" icons will copy them)
 1. In the left panel, click Numbers then "Your numbers"
 1. Decide which number from this list you're going to use with Cheogram
 1. In the left panel, click your name (under Balance), then Settings
 1. Under "Default SMS Setting" on the right, enter the following:
  * Delivery receipts: https://vonage.webhooks.soprani.ca/messages
  * Inbound messages: https://vonage.webhooks.soprani.ca/messages
  * HTTP Method: POST-JSON
 1. Create a new XMPP account if your existing XMPP account is already used for JMP
 1. Login to your XMPP account from a client that supports ad-hoc commands (Movim, Psi, Gajim)
 1. Add "cheogram.com" to your roster
 1. (Right-)click on cheogram.com and then click on Execute Command
 1. Select "Configure direct message route" and then click Forward or Execute
 1. Next to "Gateway JID:" enter "vonage.sgx.soprani.ca" (without the quotes) and click Next
 1. Enter the API Key, API Secret, and number (starting with '+') from steps 2 and 4, click Next
 1. Registration should succeed if all your info is correct; if not, ask us [[xmpp:discuss@conference.soprani.ca?join|from your chat client]] or [[https://anonymous.cheogram.com/discuss@conference.soprani.ca|on the web]]
 1. Send and receive messages as you would with JMP; see [[https://cheogram.com/faq/#how-to-use|here]] for details
Line 29: Line 64:
... These are the expected parameters that it lists, and the values you need to use:
Line 31: Line 66:
== A word from our sponsors... ==  * xmpp_component_jid - a [[JabberID]] for the SGX that your XMPP server is configured to host (e.g. vonage.sgx.example.com)
 * xmpp_component_password - the password used to login to your component JID on your XMPP server (see [[https://prosody.im/doc/components#adding_an_external_component|here]] for an example)
 * xmpp_server_hostname - the hostname of your XMPP server (could be 127.0.0.1 if run on the same host as the SGX)
 * xmpp_server_port - the port your XMPP server uses for components (e.g. 5347)
 * http_listen_port - the port that the SGX will listen on for incoming messages and delivery receipts from Vonage (used below)
Line 33: Line 72:
Providing the above services and writing the SGX code linked above is not free, if you find it useful please consider supporting infrastructure costs [[https://liberapay.com/singpolyma/|on Liberapay]], [[https://www.patreon.com/singpolyma|on Patreon]], or by becoming a paying customer of [[https://jmp.chat|JMP]]. Configuring components on an XMPP server is beyond the scope of this documentation. An example of where to find such resources would be the [[https://prosody.im/doc/components|Prosody components documentation]].

Now you can run the SGX, using a command like this:

{{{$ bundle exec ./sgx-vonagev0.rb vonage.sgx.example.com my_password 127.0.0.1 5347 12345}}}

Assuming that it works (which it should if your XMPP server is correctly configured to accept the SGX component), you now have a working SGX! You just need to wire it up to Vonage in order to send and receive SMS:

 1. Login to https://dashboard.nexmo.com/
 1. Copy down the "API key" and "API Secret" values (the "two box" icons will copy them)
 1. In the left panel, click Numbers then "Your numbers"
 1. Decide which number from this list you're going to use with your SGX (via Cheogram)
 1. In the left panel, click your name (under Balance), then Settings
 1. Under "Default SMS Setting" on the right, enter the following (this is insecure - see below):
  * Delivery receipts: {{{http://[your_hostname]:[http_listen_port]}}}
  * Inbound messages: {{{http://[your_hostname]:[http_listen_port]}}}
  * HTTP Method: POST-JSON
 1. Create a new XMPP account if your existing XMPP account is already used for JMP
 1. Login to your XMPP account from a client that supports ad-hoc commands (Movim, Psi, Gajim)
 1. Add "cheogram.com" to your roster
 1. (Right-)click on cheogram.com and then click on Execute Command
 1. Select "Configure direct message route" and then click Forward or Execute
 1. Next to "Gateway JID:" enter [xmpp_component_jid] and click Next
 1. Enter the API Key, API Secret, and number (starting with '+') from steps 2 and 4, click Next
 1. Registration should succeed if all your info is correct; if not, ask us [[xmpp:discuss@conference.soprani.ca?join|from your chat client]] or [[https://anonymous.cheogram.com/discuss@conference.soprani.ca|on the web]]
 1. Send and receive messages as you would with JMP; see [[https://cheogram.com/faq/#how-to-use|here]] for details

You're all set! If you're not receiving SMS or delivery receipts for some reason, make sure that http://[your_hostname]:[http_listen_port] is accessible from the Internet (you may need to configure the firewall on your server to allow the [http_listen_port] you picked). To ensure the messages coming from Vonage to your server are encrypted, we recommend you setup a proxy (e.g. using [[https://httpd.apache.org/docs/current/mod/mod_proxy.html#ProxyPass|ProxyPass]]) to your SGX's HTTP port.

== Why Vonage? ==

There are other API providers that we could have used for letting people use phone numbers from other countries through Cheogram, but Vonage was the only one we could find that let anyone signup. For example, Twilio requires a phone number to signup but doesn't let you use a JMP number. And Plivo requires you to use a "work email" address (they explicitly block @gmail.com addresses). If you find another API provider, feel free to write an [[SGX]] for it! Let us know [[xmpp:discuss@conference.soprani.ca?join|from your chat client]] or [[https://anonymous.cheogram.com/discuss@conference.soprani.ca|on the web]] and we can promote it.

Setting up Vonage

These instructions are intended for technical and/or motivated individuals who need to text from a non-US/Canadian phone number. We recommend people who are fine with using a US or Canadian phone number signup for https://jmp.chat/ instead.

Providing the below SGX services is not free; if you find them useful please consider supporting infrastructure costs on Liberapay, on Patreon, or by becoming a paying customer of JMP.

Get a Vonage account

You can signup at https://dashboard.nexmo.com/sign-up - they ask for name, email, and (in the next screen) phone number. We've confirmed that Vonage will accept a JMP number here.

The signup process appears to give you a test phone number in the country you signup from (and/or that your phone number is from), as well as €2 in your account for testing. You can text between that test phone number and the signup number, but you need to add extra funds to the account if you want to text with other numbers.

Note that with Vonage, very few countries support MMS. And we haven't implemented MMS in the SGX yet, so it won't yet work in any countries. Assume that any MMS sent to your Vonage number will be silently ignored for now.

Setup incoming call forwarding

We haven't written anything to specifically handle calls with Vonage. But you can just forward incoming calls on your Vonage number to another number through their dashboard. To do that, follow these steps:

  1. Login to https://dashboard.nexmo.com/

  2. In the left panel, click Numbers then "Your numbers"
  3. Click the pencil icon under Manage next to the number you want to add forwarding to
  4. Under Voice, change "Forward to" from None to Phone
  5. Enter your phone number under Number
  6. Leave "Event Webhook URL" empty and click Save

Alternately, you may receive calls over XMPP Jingle instead of having them forwarded to a phone number. The steps are the same as above, but in place of steps 4 and 5 you instead:

  1. Under Voice, change "Forward to" from None to SIP
  2. If your JabberID was user@domain.tld you would enter this as your SIP URI: user%5C40domain.tld%40cheogram.com@sip.cheogram.com

If you want to make outgoing calls, you can write a script to do that, or use https://callwithus.com/ and set your outgoing Caller ID to be your Vonage number.

Using the Vonage SGX run by Soprani.ca

If you don't want to run your own instance of our software to get SGX features on non-US/Canadian numbers, then you can use the one that we at Soprani.ca run. Here's how to do it:

  1. Login to https://dashboard.nexmo.com/

  2. Copy down the "API key" and "API Secret" values (the "two box" icons will copy them)
  3. In the left panel, click Numbers then "Your numbers"
  4. Decide which number from this list you're going to use with Cheogram
  5. In the left panel, click your name (under Balance), then Settings
  6. Under "Default SMS Setting" on the right, enter the following:
  7. Create a new XMPP account if your existing XMPP account is already used for JMP
  8. Login to your XMPP account from a client that supports ad-hoc commands (Movim, Psi, Gajim)
  9. Add "cheogram.com" to your roster
  10. (Right-)click on cheogram.com and then click on Execute Command
  11. Select "Configure direct message route" and then click Forward or Execute
  12. Next to "Gateway JID:" enter "vonage.sgx.soprani.ca" (without the quotes) and click Next
  13. Enter the API Key, API Secret, and number (starting with '+') from steps 2 and 4, click Next
  14. Registration should succeed if all your info is correct; if not, ask us from your chat client or on the web

  15. Send and receive messages as you would with JMP; see here for details

Using your own instance of the Vonage SGX

If you'd rather run your own instance of the Vonage SGX, start by cloning the SGX from https://gitlab.com/soprani.ca/sgx-vonagev0 . Then run "bundle install" in that directory (installing ruby-bundler if needed). After that you can start the SGX by running "bundle exec ./sgx-vonagev0.rb" - this will give you the usage string.

These are the expected parameters that it lists, and the values you need to use:

  • xmpp_component_jid - a JabberID for the SGX that your XMPP server is configured to host (e.g. vonage.sgx.example.com)

  • xmpp_component_password - the password used to login to your component JID on your XMPP server (see here for an example)

  • xmpp_server_hostname - the hostname of your XMPP server (could be 127.0.0.1 if run on the same host as the SGX)
  • xmpp_server_port - the port your XMPP server uses for components (e.g. 5347)
  • http_listen_port - the port that the SGX will listen on for incoming messages and delivery receipts from Vonage (used below)

Configuring components on an XMPP server is beyond the scope of this documentation. An example of where to find such resources would be the Prosody components documentation.

Now you can run the SGX, using a command like this:

$ bundle exec ./sgx-vonagev0.rb vonage.sgx.example.com my_password 127.0.0.1 5347 12345

Assuming that it works (which it should if your XMPP server is correctly configured to accept the SGX component), you now have a working SGX! You just need to wire it up to Vonage in order to send and receive SMS:

  1. Login to https://dashboard.nexmo.com/

  2. Copy down the "API key" and "API Secret" values (the "two box" icons will copy them)
  3. In the left panel, click Numbers then "Your numbers"
  4. Decide which number from this list you're going to use with your SGX (via Cheogram)
  5. In the left panel, click your name (under Balance), then Settings
  6. Under "Default SMS Setting" on the right, enter the following (this is insecure - see below):
    • Delivery receipts: http://[your_hostname]:[http_listen_port]

    • Inbound messages: http://[your_hostname]:[http_listen_port]

    • HTTP Method: POST-JSON
  7. Create a new XMPP account if your existing XMPP account is already used for JMP
  8. Login to your XMPP account from a client that supports ad-hoc commands (Movim, Psi, Gajim)
  9. Add "cheogram.com" to your roster
  10. (Right-)click on cheogram.com and then click on Execute Command
  11. Select "Configure direct message route" and then click Forward or Execute
  12. Next to "Gateway JID:" enter [xmpp_component_jid] and click Next
  13. Enter the API Key, API Secret, and number (starting with '+') from steps 2 and 4, click Next
  14. Registration should succeed if all your info is correct; if not, ask us from your chat client or on the web

  15. Send and receive messages as you would with JMP; see here for details

You're all set! If you're not receiving SMS or delivery receipts for some reason, make sure that http://[your_hostname]:[http_listen_port] is accessible from the Internet (you may need to configure the firewall on your server to allow the [http_listen_port] you picked). To ensure the messages coming from Vonage to your server are encrypted, we recommend you setup a proxy (e.g. using ProxyPass) to your SGX's HTTP port.

Why Vonage?

There are other API providers that we could have used for letting people use phone numbers from other countries through Cheogram, but Vonage was the only one we could find that let anyone signup. For example, Twilio requires a phone number to signup but doesn't let you use a JMP number. And Plivo requires you to use a "work email" address (they explicitly block @gmail.com addresses). If you find another API provider, feel free to write an SGX for it! Let us know from your chat client or on the web and we can promote it.

VonageSetup (last edited 2023-133 00:11:55 by Singpolyma)